Proofreading changes

8 files changed, 59 insertions, 52 deletions

diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index dc1fb69..3b3d762 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -105,15 +105,14 @@ namespace bdep
      \
 
      If our \cb{hello} project wanted to use \cb{libhello} as a dependency
-     package, then \cb{repositories.manifest} could look like this:
+     package, then its \cb{repositories.manifest} could look like this:
 
      \
      : 1
+     summary: hello project repository
+     :
      role: prerequisite
      location: https://example.com/libhello.git
-     :
-     role: base
-     summary: hello project repository
      \
 
      See \l{bpkg#manifest-repository-list Repository List Manifest} for
@@ -141,9 +140,9 @@ namespace bdep
      the project and one or more associated build configurations. For example,
      if we list a new dependency in the package's \cb{manifest} file, then
      \cb{bdep} fetches and configures this dependency in a build
-     configuration. Similarly, if we upgrade a dependency in a build
-     configuration, then \cb{bdep} updates the corresponding entry in the
-     package's \cb{lockfile}.
+     configuration. Similarly, if we upgrade or downgrade a dependency in a
+     build configuration, then \cb{bdep} updates the corresponding entry in
+     the package's \cb{lockfile}.
 
      A typical \cb{bdep} workflow would consist of the following steps.
 
@@ -151,7 +150,7 @@ namespace bdep
 
      \li|\b{Obtain the Project}\n
 
-         Normally we would use the version control system to obtail the
+         Normally we would use the version control system to obtain the
          project we want to develop:
 
          \
@@ -190,7 +189,7 @@ namespace bdep
          \
 
          We can now use the \l{bdep-status(1)} command to examine the status
-         of our project in its configuration:
+         of our project in its configurations:
 
          \
          $ bdep status -a
@@ -253,7 +252,7 @@ namespace bdep
          \
          $ cat manifest
          ...
-         depends: libhello >= 1.0.0
+         depends: libhello ^1.0.0
          ...
          \
 
@@ -284,7 +283,7 @@ namespace bdep
 
          $ bdep status -i
          hello configured 0.1.0-a.0.19700101000000#1
-           libhello >= 1.0.0 configured 1.0.0
+           libhello ^1.0.0 configured 1.0.0
          \
 
          Note that by default build configurations are automatically
@@ -342,10 +341,13 @@ namespace bdep
 
          \
          $ bdep sync libhello
+         synchronizing:
+           upgrade libhello/1.1.0
+           reconfigure hello/0.1.0
 
          $ bdep status -i
          hello configured 0.1.0-a.0.19700101000000#1
-           libhello >= 1.0.0 configured 1.1.0
+           libhello ^1.0.0 configured 1.1.0
          \
 
          Let's say we didn't like the new version and would like to go back to
@@ -357,6 +359,9 @@ namespace bdep
          libhello configured 1.1.0 available [1.0.0] (1.1.0)
 
          $ bdep sync libhello/1.0.0
+         synchronizing:
+           downgrade libhello/1.1.0
+           reconfigure hello/0.1.0
          \
 
          ||
diff --git a/bdep/config.cli b/bdep/config.cli
index 2c9e19f..494353e 100644
--- a/bdep/config.cli
+++ b/bdep/config.cli
@@ -65,12 +65,13 @@ namespace bdep
 
      \li|\cb{create}
 
-         The \cb{add} subcommand adds an existing \l{bpkg(1)} configuration in
-         directory <cfg-dir> to the project's build configuration set. The
-         \cb{create} subcommand creates a new configuration in directory
-         <cfg-dir> by executing the \l{bpkg-cfg-create(1)} command and passing
-         to it <cfg-args>, if any. It then proceeds as \cb{add} by adding the
-         new configuration to the project's build configuration set.
+         The \cb{add} subcommand adds an existing \l{bpkg(1)} build
+         configuration in directory <cfg-dir> to the project's build
+         configuration set. The \cb{create} subcommand creates a new
+         configuration in directory <cfg-dir> by executing the
+         \l{bpkg-cfg-create(1)} command and passing to it <cfg-args>, if
+         any. It then proceeds as \cb{add} by adding the new configuration to
+         the project's build configuration set.
 
          In both subcommands, if <cfg-name> is specified, then the added
          configuration is given this name. Several \cb{bdep} commands can use
@@ -101,8 +102,8 @@ namespace bdep
 
      \li|\cb{remove}
 
-         The \cb{remove} subcommand removes one or more configurations from
-         the project's build configuration set. See
+         The \cb{remove} subcommand removes one or more build configurations
+         from the project's build configuration set. See
          \l{bdep-projects-configs(1)} for various ways to specify build
          configurations.|
 
@@ -119,7 +120,7 @@ namespace bdep
          forward (\c{\b{--}[\b{no-}]\b{forward}}), and
          auto-synchronization (\c{\b{--}[\b{no-}]\b{auto-sync}}) flags.
          Note that changing any of these flags requires an explicit
-         \cb{sync} command to take effect.||"
+         \l{bdep-sync(1)} command to take effect.||"
 
     bool add;
     bool create;
diff --git a/bdep/fetch.cli b/bdep/fetch.cli
index 48c7c38..5b82090 100644
--- a/bdep/fetch.cli
+++ b/bdep/fetch.cli
@@ -25,11 +25,12 @@ namespace bdep
      \h|DESCRIPTION|
 
      The \cb{fetch} command fetches the list of packages available in the
-     project's repositories in one or more build configurations. If no project
-     or package directory is specified, then the current working directory is
-     assumed. If no configuration is specified, then the default configuration
-     is assumed. See \l{bdep-projects-configs(1)} for details on specifying
-     projects and configurations.
+     project's prerequisite/complement repositories in one or more build
+     configurations. If no project or package directory is specified, then the
+     current working directory is assumed. If no configuration is specified,
+     then the default configuration is assumed. See
+     \l{bdep-projects-configs(1)} for details on specifying projects and
+     configurations.
 
      If the \cb{--full|-F} option is specified, then instead \cb{fetch}
      performs a full re-fetch of all the repositories added to the
diff --git a/bdep/init.cli b/bdep/init.cli
index 57b1abb..0f0e882 100644
--- a/bdep/init.cli
+++ b/bdep/init.cli
@@ -51,8 +51,8 @@ namespace bdep
      form.
 
      The third (\cb{--config-add}) and fourth (\cb{--config-create}) forms are
-     shortcuts that can be used to first add an existing or newly created
-     build configuration and then initialize project packages in that
+     shortcuts to first adding an existing or newly created build
+     configuration and then initializing project packages in that
      configuration. Semantically they are equivalent to first performing the
      \cb{config add} or \cb{config create} commands (\l{bdep-config(1)}),
      respectively, followed by the first form. Optional <cfg-args> in the
@@ -73,7 +73,7 @@ namespace bdep
      The following invocations illustrate the common \cb{init} use cases (the
      current working directory is shown before the shell prompt).
 
-     Create new build configuration in \cb{../prj-gcc}, call it \cb{gcc} and
+     Create new build configuration in \cb{../prj-gcc}, call it \cb{gcc}, and
      initialize project packages \cb{foo} and \cb{libfoo} in this
      configuration:
 
diff --git a/bdep/new.cli b/bdep/new.cli
index c46f57d..3e037e1 100644
--- a/bdep/new.cli
+++ b/bdep/new.cli
@@ -37,21 +37,21 @@ namespace bdep
      The \cb{new} command creates and initializes a new \cb{build2} project.
      All three forms first create according to <spec> a new \cb{build2}
      project called <name> in the <name> subdirectory of the current working
-     directory (unless overriden with \c{\b{--directory}|\b{-d}}).
+     directory (unless overridden with \c{\b{--directory}|\b{-d}}).
 
      The first form then, unless the \cb{--no-init} option is specified,
      initializes an empty project database as if by executing the
      \l{bdep-init(1)} command with the \cb{--empty} option. Similarly, the
      second and third forms add an existing or create new build configuration
-     and then initialize the project in that configuraton as if by executing
+     and then initialize the project in that configuration as if by executing
      the \l{bdep-init(1)} command with the \cb{--config-add} or
      \cb{--config-create} option, respectively.
 
      The project parameters such as type (executable, library, etc), language,
      and version control system can be customized as described next. Some of
-     the parameters also support parameter-specific options (such as the file
-     extensions to use in a C++ project) that can be specified after the
-     parameter value.
+     these parameters also support parameter-specific options (such as the
+     file extensions to use in a C++ project) that can be specified with a
+     comma after the parameter value.
 
      The project type can be specified with the \c{\b{--type}|\b{-t}} option.
      Valid values for this option and their semantics are described next. If
@@ -192,15 +192,15 @@ namespace bdep
     cmd_new_lang --lang|-l
     {
       "<lang>[,<opt>...]",
-      "Specify language type and options. Valid values for <lang> are \cb{c}
+      "Specify project language and options. Valid values for <lang> are \cb{c}
        and \cb{c++} (default). Valid values for <opt> are language-specific."
     }
 
     cmd_new_vcs --vcs|-s
     {
       "<vcs>[,<opt>...]",
-      "Specify version control system and options. Valid values for <vcs> are
-       \cb{git} (default) and \cb{none}. Valid values for <opt> are
+      "Specify project version control system and options. Valid values for
+       <vcs> are \cb{git} (default) and \cb{none}. Valid values for <opt> are
        system-specific."
     }
 
diff --git a/bdep/project.cli b/bdep/project.cli
index 2fe37e4..e62daf2 100644
--- a/bdep/project.cli
+++ b/bdep/project.cli
@@ -19,7 +19,7 @@ namespace bdep
 
     bool --no-default
     {
-      "Don't make the first added or created configuration then default."
+      "Don't make the first added or created configuration the default."
     }
 
     bool --forward
diff --git a/bdep/projects-configs.cli b/bdep/projects-configs.cli
index 256d0a1..d3e3e5e 100644
--- a/bdep/projects-configs.cli
+++ b/bdep/projects-configs.cli
@@ -61,7 +61,7 @@ include <bdep/common-options.hxx>;
   A project managed by \cb{bdep} has one or more associated build
   configurations (see \l{bdep-config(1)} for details). One of these
   configurations can be designated as the default and used if no configuration
-  is explicitly specified. So, for example, running \cb{status} without any
+  is specified explicitly. So, for example, running \cb{status} without any
   arguments in the project directory will show the status of all the project
   packages initialized in the default configuration.
 
@@ -77,7 +77,7 @@ include <bdep/common-options.hxx>;
   mixed. For example:
 
   \
-  $ bdep status @gcc -c ../builds/clang/
+  $ bdep status @gcc -c ../builds/clang
   \
 
   Finally, we can use the \c{\b{--all}|\b{-a}} option to specify all the
diff --git a/bdep/sync.cli b/bdep/sync.cli
index 838a01c..dde86a2 100644
--- a/bdep/sync.cli
+++ b/bdep/sync.cli
@@ -35,12 +35,12 @@ namespace bdep
      The \cb{sync} command synchronizes a project with its build
      configurations. The first form (no arguments nor \cb{--upgrade} or
      \cb{--patch} are specified) upgrades the project packages to the latest
-     iteration, adjusts their dependencies according to the latest manifest
-     information, and updates the lockfile. If no project or package directory
-     is specified, then the current working directory is assumed. If no
-     configuration is specified, then the default configuration is assumed. See
-     \l{bdep-projects-configs(1)} for details on specifying projects and
-     configurations.
+     version/iteration, adjusts their dependencies according to the latest
+     manifest information, and updates the lockfile. If no project or package
+     directory is specified, then the current working directory is assumed. If
+     no configuration is specified, then the default configuration is
+     assumed. See \l{bdep-projects-configs(1)} for details on specifying
+     projects and configurations.
 
      The second form (no arguments but either \cb{--upgrade} or \cb{--patch}
      is specified), in addition to the first form's functionality, also
@@ -96,7 +96,7 @@ namespace bdep
      suitable version:
 
      \
-     foo/$ edit manifest  # Add 'depends: libx >= 1.0.0'
+     foo/$ edit manifest  # Add 'depends: libx ^1.0.0'
      foo/$ bdep sync
      \
 
@@ -106,7 +106,7 @@ namespace bdep
      foo/$ bdep sync -u
      \
 
-     Upgrade all the dependencies of all the initialzied packages in a
+     Upgrade all the dependencies of all the initialized packages in a
      project recursively:
 
      \
@@ -120,7 +120,7 @@ namespace bdep
      prj/$ bdep sync libx
      \
 
-     Upgrade \cb{libx} and its immediate dependecies to the latest version:
+     Upgrade \cb{libx} and its immediate dependencies to the latest version:
 
      \
      prj/$ bdep sync -i libx
@@ -132,7 +132,7 @@ namespace bdep
      prj/$ bdep sync -p libx
      \
 
-     Upgrade \cb{libx} and all its dependecies recursively to the latest patch
+     Upgrade \cb{libx} and all its dependencies recursively to the latest patch
      version.
 
      \
@@ -145,7 +145,7 @@ namespace bdep
      prj/$ bdep sync libx/1.2.3
      \
 
-     Upgrade \cb{libx} to version \cb{1.2.3} and patch all its dependecies,
+     Upgrade \cb{libx} to version \cb{1.2.3} and patch all its dependencies,
      recursively:
 
      \
@@ -202,7 +202,7 @@ namespace bdep
     bool --implicit
     {
       "Perform implicit synchronization. This mode is normally used by other
-       tools (for example, a build system hook) to ensure packages and
+       tools (for example, a build system hook) to ensure projects and
        configurations are synchronized. To improve performance, especially for
        the \"everything is already synchronized\" case, \cb{sync} executed in
        this mode assumes that no configuration flags (see \l{bdep-config(1)})