Documentation work

10 files changed, 225 insertions, 25 deletions

diff --git a/bdep/.gitignore b/bdep/.gitignore
index 02a0554..da387e5 100644
--- a/bdep/.gitignore
+++ b/bdep/.gitignore
@@ -1,4 +1,5 @@
 bdep
 *-odb.?xx
 *-options.?xx
+projects-configs.?xx
 version.hxx
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index 69c7ffc..9974458 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -100,6 +100,11 @@ namespace bdep
     {
       "\l{bdep-common-options(1)} \- details on common options"
     }
+
+    bool projects-configs
+    {
+      "\l{bdep-projects-configs(1)} \- specifying projects and configurations"
+    }
   };
 
   class options: common_options
diff --git a/bdep/buildfile b/bdep/buildfile
index 75f5320..ac355e4 100644
--- a/bdep/buildfile
+++ b/bdep/buildfile
@@ -26,10 +26,13 @@ fetch-options    \
 status-options   \
 config-options
 
-exe{bdep}: {hxx ixx txx cxx}{** -{$options_topics} -*-odb -version}  \
-           {hxx ixx cxx}{$options_topics}                            \
-           {hxx ixx cxx}{project-odb database-views-odb}             \
-           {hxx}{version} $libs
+help_topics = projects-configs
+
+exe{bdep}:                                                                  \
+  {hxx ixx txx cxx}{** -{$options_topics} -{$help_topics} -*-odb -version}  \
+  {hxx ixx cxx}{$options_topics} {hxx cxx}{$help_topics}                    \
+  {hxx ixx cxx}{project-odb database-views-odb}                             \
+  {hxx}{version} $libs
 
 hxx{version}: in{version} $src_root/file{manifest}
 
@@ -62,6 +65,10 @@ if $cli.configured
   cli.cxx{status-options}: cli{status}
   cli.cxx{config-options}: cli{config}
 
+  # Help topics.
+  #
+  cli.cxx{projects-configs}: cli{projects-configs}
+
   # Option length must be the same to get commands/topics/options aligned.
   #
   cli.options += -I $src_root --include-with-brackets --include-prefix bdep \
@@ -78,6 +85,10 @@ if $cli.configured
   cli.cxx{new-options}: cli.options += \
 --cxx-prologue "#include <bdep/new-parsers.hxx>"
 
+  # Avoid generating CLI runtime and empty inline file for help topics.
+  #
+  cli.cxx{projects-configs}: cli.options += --suppress-cli --suppress-inline
+
   # Include the generated cli files into the distribution and don't remove
   # them when cleaning in src (so that clean results in a state identical to
   # distributed).
diff --git a/bdep/help.cxx b/bdep/help.cxx
index ec2c4c2..098e902 100644
--- a/bdep/help.cxx
+++ b/bdep/help.cxx
@@ -9,6 +9,10 @@
 #include <bdep/diagnostics.hxx>
 #include <bdep/bdep-options.hxx>
 
+// Help topics.
+//
+#include <bdep/projects-configs.hxx>
+
 using namespace std;
 using namespace butl;
 
@@ -26,6 +30,8 @@ namespace bdep
       //
       else if (t == "common-options")
         usage = &print_bdep_common_options_long_usage;
+      else if (t == "projects-configs")
+        usage = &print_bdep_projects_configs_usage;
       else
         fail << "unknown bdep command/help topic '" << t << "'" <<
           info << "run 'bdep help' for more information";
diff --git a/bdep/init.cli b/bdep/init.cli
index 8629bfe..ded6913 100644
--- a/bdep/init.cli
+++ b/bdep/init.cli
@@ -46,12 +46,12 @@ namespace bdep
      <cfg-args> are arguments to \cb{bpkg cfg-create}. <pkg-args> are arguments
      to \cb{bpkg pkg-build}.
 
-     In the first variant the configurations can also be specified as
+     In the first form the configurations can also be specified as
      directories using the \cb{--config|-c} option.
 
-     The second and third variants are semantically equivalent to first
+     The second and third forms are semantically equivalent to first
      performing the \cb{config add} and \cb{config create} commands
-     (\l{bdep-config(1)}), respectively, followed by the first variant. In
+     (\l{bdep-config(1)}), respectively, followed by the first form. In
      both cases the \cb{--default|-d} option can be used to make the
      added/created configuration default.
      "
diff --git a/bdep/new.cli b/bdep/new.cli
index ddf61c0..1e91b41 100644
--- a/bdep/new.cli
+++ b/bdep/new.cli
@@ -34,7 +34,7 @@ namespace bdep
 
      The \cb{new} command...
 
-     The first variant, unless the \cb{--no-init} is specified, initializes
+     The first form, unless the \cb{--no-init} is specified, initializes
      an empty configuration set, as if by performing \cb{init --empty}.
 
      Recognized \cb{c++} language options:
diff --git a/bdep/projects-configs.cli b/bdep/projects-configs.cli
new file mode 100644
index 0000000..82ab462
--- /dev/null
+++ b/bdep/projects-configs.cli
@@ -0,0 +1,87 @@
+// file      : bdep/projects-configs.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bdep/common-options.hxx>;
+
+"\section=1"
+"\name=bdep-projects-configs"
+"\summary=specifying projects and configurations"
+
+{
+  "<command>
+   <prj-spec> <prj-dir>
+   <pkg-spec> <pkg-dir>
+   <cfg-spec> <cfg-name> <cfg-dir>",
+
+  "
+  \h|SYNOPSIS|
+
+  \c{\b{bdep} <command> [<pkg-spec>] [<cfg-spec>] ...}
+
+  \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
+     <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
+     <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}
+
+  \h|DESCRIPTION|
+
+  Most \cb{bdep} commands operate on a project or some of its packages as well
+  as its build configurations. For example, \cb{status} (\l{bdep-status(1)})
+  shows the status of one or more project packages in one or more build
+  configurations. While \cb{fetch} (\l{bdep-fetch(1)}) re-fetches the list of
+  available to the project dependency packages, again, in one or more build
+  configurations.
+
+  Without any \c{\b{--directory}|\b{-d}} options specified, the current
+  working directory is assumed to be either the project root directory, the
+  package root directory, or one of the package subdirectories. This is the
+  common \cb{bdep} usage mode where you run it from within your project's
+  source code directories, similar to version control tools such as
+  \cb{git(1)}.
+
+  Alternatively, the project or (several) package directories can be specified
+  with the \c{\b{--directory}|\b{-d}} options. Note that \cb{bdep} operates
+  on a single project but potentially multiple packages belonging to said
+  project at a time.
+
+  Some \cb{bdep} commands, such as \cb{fetch}, operate on the whole project.
+  If such a command is given a package directory (either as the working
+  directory or with \c{\b{--directory}|\b{-d}}), then it automatically
+  determines its project directory and uses that.
+
+  Other commands, such as \cb{status}, operate on one or more packages. If
+  such a command is given a project directory, then it automatically
+  determines the list of packages belonging to this project and uses
+  that. Note that what exactly \i{belonging} means is command-specific. For
+  most commands it means all the packages initialized in a given build
+  configuration. For \cb{init} (\l{bdep-init(1)}), however, it means all the
+  packages available in the project (for example, as listed in
+  \cb{packages.manifest}).
+
+  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
+  arguments in the project directory will show the status of all the project
+  packages initialized in the default configuration.
+
+  An associated build configuration can be assigned a name in which case we
+  can specify it using the \c{\b{@}\i{cfg-name}} notation. For example:
+
+  \
+  bdep status @gcc @clang
+  \
+
+  A configuration without a name can be specified as a directory using the
+  \c{\b{--config}|\b{-c}} option. Name and directory specifications can be
+  mixed. For example:
+
+  \
+  bdep status @gcc -c ../builds/clang/
+  \
+
+  Finally, we can use the \c{\b{--all}|\b{-a}} option to specify all the
+  build configurations associated with the project.
+
+  "
+}
diff --git a/bdep/status.cli b/bdep/status.cli
index 6a562da..8ef909b 100644
--- a/bdep/status.cli
+++ b/bdep/status.cli
@@ -28,17 +28,19 @@ namespace bdep
 
      \h|DESCRIPTION|
 
-     The \cb{status} command prints the status of the project and/or its
-     dependencies in build configurations. If no <dep-spec> arguments are
-     specified, then \cb{status} prints the status of the project's packages.
-     Otherwise, the status of the specified dependency packages is printed.
-     Additionally, the status of immediate or all dependencies of the above
-     packages can be printed by specifying the \c{\b{--immediate}|\b{-i}} or
-     \c{\b{--recursive}|\b{-r}} options, respectively. Note that the status is
-     written to \cb{STDOUT}, not \cb{STDERR}.
+     The \cb{status} command prints the status of project packages and/or
+     their dependencies in build configurations. If no <dep-spec> arguments
+     are specified, then \cb{status} prints the status of the project's
+     packages. Otherwise, the status of the specified dependency packages is
+     printed. Additionally, the status of immediate or all dependencies of the
+     above packages can be printed by specifying the
+     \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} options,
+     respectively. See \l{bdep-projects-configs(1)} for details on specifying
+     packages (<pkg-spec>) and configurations (<cfg-spec>).
 
-     The status of each package is printed on a separate line. The semantics
-     of <dep-spec> and the format of the status line are described in
+     The status of each package is printed on a separate line. Note that the
+     status is written to \cb{STDOUT}, not \cb{STDERR}. The semantics of
+     <dep-spec> and the format of the status line are described in
      \l{bpkg-pkg-status(1)}.
      "
   }
diff --git a/bdep/sync.cli b/bdep/sync.cli
index 0a3965d..7db5ac9 100644
--- a/bdep/sync.cli
+++ b/bdep/sync.cli
@@ -14,19 +14,85 @@ namespace bdep
     "<options>
      <prj-spec> <prj-dir>
      <pkg-spec> <pkg-dir>
-     <cfg-spec> <cfg-name> <cfg-dir>",
+     <cfg-spec> <cfg-name> <cfg-dir>
+     <dep-spec> <pkg> <ver>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>]}
+     \c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>]\n
+        \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}\n
+        \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}]\n
+        \ \ \ \ \ \ \ \ \ \ <dep-spec>...
+        }
 
-     \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
+     \c{<dep-spec> = <pkg>[\b{/}<ver>]\n
+        <cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
         <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
         <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}
 
      \h|DESCRIPTION|
 
-     The \cb{sync} command..."
+     The \cb{sync} command synchronizes a project with its build
+     configurations. The first form (no arguments nor \cb{--upgrade} or
+     \cb{--patch} specified) upgrades the project packages to the latest
+     iteration, adjusts their dependencies according to the latest manifest
+     information and updates the lockfile.
+
+     The second form (no arguments but with either \cb{--upgrade} or
+     \cb{--patch} specified), in addition to the first form's functionality,
+     also upgrades or patches immediate (by default or
+     \c{\b{--immediate}|\b{-i}} specified) or all (\c{\b{--recursive}|\b{-r}}
+     specified) dependencies of the specified project packages.
+
+     The third form (one or more arguments), in addition to the first form's
+     functionality, also upgrades (by default or \cb{--upgrade} specified) or
+     patches (\cb{--patch} specified) the specified dependencies. If
+     \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} is specified,
+     then it also upgrades or patches the immediate or all dependencies of the
+     specified dependencies, respectively. Alternative to \cb{--upgrade} and
+     \cb{--patch}, the desired upgrade (or downgrade) version can be specified
+     explicitly.
+
+     As an example, consider project \cb{proj} with two packages, \cb{test}
+     and \cb{libtest}:
+
+     \
+     proj/
+    ├── test/
+    └── libtest/
+     \
+
+     The following invocations illustrate the common \cb{sync} use cases (the
+     current working directory is shown before the shell prompt):
+
+     \
+     proj/$ bdep sync        # Synchronize test/ and libtest/ with the
+                             # default configuration.
+
+     proj/$ cd test
+     test/$ bdep sync        # The same (all packages in a project are
+                             # always synchronized together).
+
+     test/$ edit manifest    # Add 'depends: libx >= 1.0.0'
+     test/$ bdep sync        # Fetch and configure suitable libx version.
+
+     test/$ bdep sync -u     # Upgrade all immediate dependencies of test.
+     test/$ cd ../
+     proj/$ bdep sync -u -r  # Upgrade all dependencies of all packages in
+                             # a project recursively.
+
+     proj/$ bdep sync    libx  # Upgrade libx to the latest version.
+     proj/$ bdep sync -i libx  # ...and its immediate dependecies.
+
+     proj/$ bdep sync -p libx     # Upgrade libx to the latest patch.
+     proj/$ bdep sync -p -r libx  # ...and its dependecies, recursively.
+
+     proj/$ bdep sync libx/1.2.3        # Upgrade libx to version 1.2.3.
+     proj/$ bdep sync -p -r libx/1.2.3  # ...and patch its dependecies,
+                                        # recursively.
+     \
+
+     "
   }
 
   // Note that not all project/configuration options are valid for all
@@ -36,9 +102,26 @@ namespace bdep
   {
     "\h|SYNC OPTIONS|"
 
-    bool --yes|-y
+    bool --upgrade|-u
     {
-      "Don't prompt for confirmation when up/down-grading dependencies."
+      "Upgrade the dependencies to the latest available version that satisfies
+       all the constraints."
+    }
+
+    bool --patch|-p
+    {
+      "Upgrade the dependencies to the latest available patch version that
+       satisfies all the constraints."
+    }
+
+    bool --immediate|-i
+    {
+      "Also upgrade or patch immediate dependencies."
+    }
+
+    bool --recursive|-r
+    {
+      "Also upgrade or patch all dependencies, recursively."
     }
 
     bool --fetch|-f
@@ -50,5 +133,10 @@ namespace bdep
     {
       "Perform the \cb{fetch --full} command prior to synchronization."
     }
+
+    bool --yes|-y
+    {
+      "Don't prompt for confirmation when up/down-grading dependencies."
+    }
   };
 }
diff --git a/doc/cli.sh b/doc/cli.sh
index af6638d..48a8b74 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -57,7 +57,7 @@ o="--suppress-undocumented --output-prefix bdep- --class-doc bdep::common_option
 compile "common" $o --output-suffix "-options" --class-doc bdep::common_options=long
 compile "bdep" $o --output-prefix "" --class-doc bdep::commands=short --class-doc bdep::topics=short
 
-pages="new help init sync fetch status config"
+pages="new help init sync fetch status config projects-configs"
 
 for p in $pages; do
   compile $p $o