Documentation improvements

23 files changed, 359 insertions, 273 deletions

diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli
index e9611ff..cf0125e 100644
--- a/bpkg/bpkg.cli
+++ b/bpkg/bpkg.cli
@@ -17,125 +17,137 @@ namespace bpkg
 
      \cb{bpkg --help}\n
      \cb{bpkg --version}\n
-     \c{\b{bpkg help} [<command>|<topic>]}\n
+     \c{\b{bpkg help} [<command> | <topic>]}\n
      \c{\b{bpkg} [<common-options>] <command> [<command-options>] <command-args>}
 
      \h|DESCRIPTION|
 
-     @@ TODO
+     @@ TODO Is this a good place to describe some general concepts, like
+     configuration, repositories, packages?
+
+     The example workflow would be:
 
      Note that the common options can also be specified as part of the
-     command-specific options."
+     command-specific options.
+
+     For a detailed description of any command or help topic, use the \cb{help}
+     command or see the corresponding man page (the man pages have the
+     \cb{bpkg-} prefix, for example \l{bpkg-help(1)})."
   }
 
   class commands
   {
     "\h|COMMANDS|"
 
+    //
+    // NOTE: Use the same sentence as in the page's \summary and make
+    // sure it is short enough to fit in one line in usage.
+    //
+
     bool help
     {
       "[<topic>]",
-      "Show help for a command or help topic \- \l{bpkg-help(1)}.",
+      "\l{bpkg-help(1)} \- show help for a command or help topic",
       ""
     }
 
     bool cfg-create|create
     {
       "<dir>",
-      "Create configuration.",
+      "\l{bpkg-cfg-create(1)} \- create configuration",
       ""
     }
 
     bool cfg-add|add
     {
       "<rep>",
-      "Add repository to configuration.",
+      "\l{bpkg-cfg-add(1)} \- add repository to configuration",
       ""
     }
 
     bool cfg-fetch|fetch
     {
-      "Fetch list of available packages."
+      "\l{bpkg-cfg-fetch(1)} \- fetch list of available packages"
     }
 
     bool pkg-status|status
     {
-      "Print package status."
+      "\l{bpkg-pkg-status(1)} \- print package status"
     }
 
     bool pkg-build|build
     {
-      "Build package \- \l{bpkg-pkg-build(1)}."
+      "\l{bpkg-pkg-build(1)} \- build package"
     }
 
     bool pkg-drop|drop
     {
-      "Drop package."
+      "\l{bpkg-pkg-drop(1)} \- drop package"
     }
 
     bool pkg-install|install
     {
-      "Install package."
+      "\l{bpkg-pkg-install(1)} \- install package"
     }
 
     bool pkg-uninstall|uninstall
     {
-      "Uninstall package."
+      "\l{bpkg-pkg-uninstall(1)} \- uninstall package"
     }
 
     bool pkg-update|update
     {
-      "Update package."
+      "\l{bpkg-pkg-update(1)} \- update package"
     }
 
     bool pkg-clean|clean
     {
-      "Clean package."
+      "\l{bpkg-pkg-clean(1)} \- clean package"
     }
 
     bool pkg-verify
     {
       "<archive>",
-      "Verify archive is a valid package.",
+      "\l{bpkg-pkg-verify(1)} \- verify package archive",
       ""
     }
 
     bool pkg-fetch
     {
       "<pkg>/<ver>",
-      "Fetch package archive.",
+      "\l{bpkg-pkg-fetch(1)} \- fetch package archive",
       ""
     }
 
     bool pkg-unpack
     {
-      "Unpack package archive."
+      "\l{bpkg-pkg-unpack(1)} \- unpack package archive"
     }
 
     bool pkg-configure
     {
-      "Configure package."
+      "\l{bpkg-pkg-configure(1)} \- configure package"
     }
 
     bool pkg-disfigure
     {
-      "Disfigure package."
+      "\l{bpkg-pkg-disfigure(1)} \- disfigure package"
     }
 
     bool pkg-purge
     {
-      "Purge package."
+      "\l{bpkg-pkg-purge(1)} \- purge package"
     }
 
     bool rep-info
     {
-      "Print information about repository."
+      "\l{bpkg-rep-info(1)} \- print repository information"
     }
 
     bool rep-create
     {
       "[<dir>]",
-      "Generate repository packages manifest.",
+      "\l{bpkg-rep-create(1)} \- create repository",
       ""
     }
   };
@@ -148,7 +160,7 @@ namespace bpkg
 
     bool common-options
     {
-      "Details on common options \- \l{bpkg-common-options(1)}."
+      "\l{bpkg-common-options(1)} \- details on common options"
     }
   };
 
diff --git a/bpkg/bpkg.cxx b/bpkg/bpkg.cxx
index 182471c..dc318ed 100644
--- a/bpkg/bpkg.cxx
+++ b/bpkg/bpkg.cxx
@@ -146,7 +146,7 @@ try
     if (cmd.help ())
     {
       assert (h);
-      r = help (ho, "help", help_options::print_usage);
+      r = help (ho, "help", print_bpkg_help_usage);
       break;
     }
 
@@ -155,7 +155,7 @@ try
     // if (cmd.pkg_verify ())
     // {
     //  if (h)
-    //    r = help (ho, "pkg-verify", pkg_verify_options::print_usage);
+    //    r = help (ho, "pkg-verify", print_bpkg_pkg_verify_usage);
     //  else
     //    r = pkg_verify (parse<pkg_verify_options> (co, args), args);
     //
diff --git a/bpkg/cfg-add.cli b/bpkg/cfg-add.cli
index 34909e9..8bc17c3 100644
--- a/bpkg/cfg-add.cli
+++ b/bpkg/cfg-add.cli
@@ -8,23 +8,25 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-cfg-add"
 "\summary=add repository to configuration"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <rep>",
 
-bpkg cfg-add [<options>] <rep>"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg cfg-add}|\b{add} [<options>] <rep>}
 
-The \cb{cfg-add} command adds the specified source repository to the
-configuration. Note that this command doesn't fetch the available
-packages list for the newly added repository. To do that, use the
-\cb{cfg-fetch} command.
-"
-*/
+     \h|DESCRIPTION|
+
+     The \cb{cfg-add} command adds the specified package repository to the
+     configuration. Note that it doesn't fetch the list of available packages
+     for the newly added repository. For that, use the \l{bpkg-cfg-fetch(1)}
+     command, normally, after adding all the repositories you wish to use."
+  }
 
-namespace bpkg
-{
   class cfg_add_options: configuration_options
   {
+    "\h|CFG-ADD OPTIONS|"
   };
 }
diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli
index e28778e..2f6070d 100644
--- a/bpkg/cfg-create.cli
+++ b/bpkg/cfg-create.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg cfg-create} [<options>] [(<module> | <conf-var>)...]}
+     \c{\b{bpkg cfg-create}|\b{create} [<options>] [(<module> | <conf-var>)...]}
 
      \h|DESCRIPTION|
 
@@ -25,7 +25,7 @@ namespace bpkg
      configuration directory to be empty or to not exist (in which case it
      will be created).
 
-     By default the resulting configuration loads the \cb{config}, \cb{test},
+     By default, the resulting configuration loads the \cb{config}, \cb{test},
      and \cb{install} modules. However, additional modules and, if required,
      their configuration variables can be specified as the \cb{cfg-create}
      arguments. For example:
@@ -43,14 +43,15 @@ namespace bpkg
     dir_path --directory|-d (".")
     {
       "<dir>",
-      "Create configuration in <dir> rather than in the current working
+      "Create the configuration in <dir> rather than in the current working
        directory."
     }
 
     bool --wipe
     {
       "Wipe the configuration directory clean before creating the new
-       configuration."
+       configuration. For safety, this option requires that you specify the
+       configuration directory explicitly with \cb{--directory|-d}."
     }
   };
 }
diff --git a/bpkg/cfg-create.cxx b/bpkg/cfg-create.cxx
index 624edb2..62b39d8 100644
--- a/bpkg/cfg-create.cxx
+++ b/bpkg/cfg-create.cxx
@@ -23,6 +23,9 @@ namespace bpkg
   {
     tracer trace ("cfg_create");
 
+    if (o.wipe () && !o.directory_specified ())
+      fail << "--wipe requires explicit --directory|-d";
+
     dir_path c (o.directory ());
     level4 ([&]{trace << "creating configuration in " << c;});
 
diff --git a/bpkg/cfg-fetch.cli b/bpkg/cfg-fetch.cli
index 6b889cc..9cc75fd 100644
--- a/bpkg/cfg-fetch.cli
+++ b/bpkg/cfg-fetch.cli
@@ -6,23 +6,27 @@ include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-cfg-fetch"
-"\summary=fetch available packages list"
+"\summary=fetch list of available packages"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options>",
 
-bpkg cfg-fetch [<options>]"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg cfg-fetch}|\b{fetch} [<options>]}
 
-The \cb{cfg-fetch} command recursively fetches the prerequisite repository
-and available package lists for all the repositories that were added
-(\cb{cfg-add}) to the configuration."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{cfg-fetch} command fetches the list of available packages for all
+     the repositories that were previously added with the \l{bpkg-cfg-add(1)}
+     command as well as all their complement and prerequisite repositories,
+     recursively."
+  }
 
-namespace bpkg
-{
   class cfg_fetch_options: configuration_options
   {
+    "\h|CFG-FETCH OPTIONS|"
   };
 }
diff --git a/bpkg/common.cli b/bpkg/common.cli
index 17ee1a6..92c3748 100644
--- a/bpkg/common.cli
+++ b/bpkg/common.cli
@@ -6,7 +6,7 @@ include <bpkg/types>;
 
 "\section=1"
 "\name=bpkg-common-options"
-"\summary=options common for all commands"
+"\summary=details on common options"
 
 namespace bpkg
 {
@@ -19,8 +19,9 @@ namespace bpkg
 
      \h|DESCRIPTION|
 
-     The common options can be specified either before the command or after,
-     togethere with the command-specific options."
+     The common options control behavior that is common to all or most of the
+     \cb{bpkg} commands. They can be specified either before the command or
+     after, together with the command-specific options."
   }
 
   class common_options = 0
@@ -32,8 +33,7 @@ namespace bpkg
     {
       "",
       "The common options are summarized below with a more detailed description
-       available as the \l{bpkg-common-options(1) \cb{common-options}} help
-       topic.",
+       available in \l{bpkg-common-options(1)}.",
       ""
     }
 
@@ -61,9 +61,9 @@ namespace bpkg
 
        \li|high-level information messages|
 
-       \li|essential underlying commands that are being executed|
+       \li|essential underlying commands being executed|
 
-       \li|all underlying commands that are being executed|
+       \li|all underlying commands being executed|
 
        \li|information that could be helpful to the user|
 
diff --git a/bpkg/help.cli b/bpkg/help.cli
index 69e818c..f50841e 100644
--- a/bpkg/help.cli
+++ b/bpkg/help.cli
@@ -10,11 +10,21 @@ include <bpkg/common.cli>;
 
 namespace bpkg
 {
-  class help_options: common_options
   {
-    /*
-    "Show detailed help for a command or help topic or the list of
+    "<command> <topic>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bpkg help} [<command> | <topic>]}
+
+     \h|DESCRIPTION|
+
+     Show the detailed help for <command> or help <topic> or a summary of
      available commands and topics if none was specified."
-    */
+  }
+
+  class help_options: common_options
+  {
+    //"\h|HELP OPTIONS|"
   };
 }
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli
index 54e0252..aa16f58 100644
--- a/bpkg/pkg-build.cli
+++ b/bpkg/pkg-build.cli
@@ -6,7 +6,7 @@ include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-build"
-"\summary=build one or more packages"
+"\summary=build package"
 
 namespace bpkg
 {
@@ -15,19 +15,22 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...}
+     \c{\b{bpkg pkg-build}|\b{build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...}
 
      \h|DESCRIPTION|
 
      The \cb{pkg-build} command builds one or more packages including all their
      prerequisites. Each package can be specified as just the name (<pkg>) with
      optional package version (<ver>) in which case the package will be
-     automatically fetched from one of the configuration's source repositories
-     (see the \cb{cfg-add} and \cb{cfg-fetch} commands). Alternatively, the
-     package can be specified as either the path to the package source archive
-     (<file>) or package source directory (<dir>). See the \cb{pkg-fetch} and
-     \cb{pkg-unpack} commands for more information on the semantics of
-     specifying the package as an archive or directory.
+     automatically fetched from one of the repositories. See the
+     \l{bpkg-cfg-add(1)} and \l{bpkg-cfg-fetch(1)} commands for more
+     information on package repositories.
+
+     Alternatively, the package can be specified as either the path to the
+     package archive (<file>) or to the package directory (<dir>). See the
+     \l{bpkg-pkg-fetch(1)} and \l{bpkg-pkg-unpack(1)} commands for more
+     information on the semantics of specifying the package as an archive or
+     a directory.
 
      Packages that are specified explicitly on the command line will be
      \i{held}, that is, they will not be considered for automatic removal if
@@ -49,15 +52,15 @@ namespace bpkg
       "Assume the answer to all prompts is \cb{yes}."
     }
 
-    bool --configure-only|-c
-    {
-      "Configure all the packages but don't update."
-    }
-
     bool --print-only|-p
     {
       "Print to \cb{STDOUT} what would be done without actually doing
        anything."
     }
+
+    bool --configure-only|-c
+    {
+      "Configure all the packages but don't update."
+    }
   };
 }
diff --git a/bpkg/pkg-clean.cli b/bpkg/pkg-clean.cli
index 9452291..ffad75a 100644
--- a/bpkg/pkg-clean.cli
+++ b/bpkg/pkg-clean.cli
@@ -8,21 +8,24 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-clean"
 "\summary=clean package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg>",
 
-bpkg pkg-clean <pkg>..."
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-clean}|\b{clean} [<options>] <pkg>...}
 
-The \cb{pkg-clean} command cleans the previously configured
-(\cb{pkg-configure}) package. Underneath, this command doesn't
-do much more than run (\cb{b clean})."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-clean} command cleans the previously configured
+     (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package.
+     Underneath, this command doesn't do much more than run \cb{b clean}."
+  }
 
-namespace bpkg
-{
   class pkg_clean_options: configuration_options
   {
+    "\h|PKG-CLEAN OPTIONS|"
   };
 }
diff --git a/bpkg/pkg-configure.cli b/bpkg/pkg-configure.cli
index 4ef9707..274a3c3 100644
--- a/bpkg/pkg-configure.cli
+++ b/bpkg/pkg-configure.cli
@@ -8,24 +8,26 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-configure"
 "\summary=configure package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg> <conf-var>",
 
-bpkg pkg-configure <pkg> [<conf-vars>]"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-configure} [<options>] <pkg> [<conf-var>...]}
 
-The \cb{pkg-configure} command configures the output directory for
-the previously unpacked (\cb{pkg-unpack}) package. The package
-inherits the common \cb{build2} configuration values that were
-specified when creating the \cb{bpkg} configuration (\cb{cfg-create}).
-Additional, package-specific configuration variables can be specified
-after the package name."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-configure} command configures the previously unpacked
+     (\l{bpkg-pkg-unpack(1)}) package. The package inherits the common
+     \cb{build2} configuration values that were specified when creating the
+     configuration (\l{bpkg-cfg-create(1)}). Additional, package-specific
+     configuration variables can be specified after the package name."
+  }
 
-namespace bpkg
-{
   class pkg_configure_options: configuration_options
   {
+    "\h|PKG-CONFIGURE OPTIONS|"
   };
 }
diff --git a/bpkg/pkg-disfigure.cli b/bpkg/pkg-disfigure.cli
index 6f5c80b..51ab956 100644
--- a/bpkg/pkg-disfigure.cli
+++ b/bpkg/pkg-disfigure.cli
@@ -8,20 +8,24 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-disfigure"
 "\summary=disfigure package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options>",
 
-bpkg pkg-disfigure <pkg> [<ver>]"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-disfigure} [<options>] <pkg>}
 
-The \cb{pkg-disfigure} command disfigures the previously configured
-(\cb{pkg-configure}) package and returns it to the \cb{unpacked} state."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-disfigure} command disfigures the previously configured
+     (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package and
+     returns it to the \cb{unpacked} state."
+  }
 
-namespace bpkg
-{
   class pkg_disfigure_options: configuration_options
   {
+    "\h|PKG-DISFIGURE OPTIONS|"
   };
 }
diff --git a/bpkg/pkg-drop.cli b/bpkg/pkg-drop.cli
index 6ec7130..7737d15 100644
--- a/bpkg/pkg-drop.cli
+++ b/bpkg/pkg-drop.cli
@@ -6,29 +6,34 @@ include <bpkg/configuration.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-drop"
-"\summary=drop one or more packages"
+"\summary=drop package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options>",
 
-bpkg pkg-drop [<options>] <pkg>..."
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-drop}|\b{drop} [<options>] <pkg>...}
 
-The \cb{pkg-drop} command drops one or more packages from the configuration.
-If the packages being dropped still have dependents, then those will have
-to be drop as well and you will be prompted for a confirmation. Similarly,
-if the packages being dropped have prerequisites that are no longer needed,
-you will be offered to drop those as well.
+     \h|DESCRIPTION|
 
-The \cb{pkg-drop} command also supports several \cb{--*-only} options that
-allow you to limit the amount of work that will be done.
-*/
+     The \cb{pkg-drop} command drops one or more packages from the
+     configuration. If the packages being dropped still have dependent
+     packages, then those will have to be drop as well and you will be prompted
+     to confirm. Similarly, if the packages being dropped have prerequisite
+     packages that would otherwise no longer be needed, you will be offered to
+     drop those as well.
+
+     The \cb{pkg-drop} command also supports several \cb{--*-only} options that
+     allow you to limit the amount of work that will be done."
+  }
 
-namespace bpkg
-{
   class pkg_drop_options: configuration_options
   {
+    "\h|PKG-DROP OPTIONS|"
+
     bool --yes|-y
     {
       "Assume the answer to all prompts is \cb{yes}. Note that this option
@@ -44,19 +49,19 @@ namespace bpkg
 
     bool --drop-dependent
     {
-      "Don't warn about or ask for confirmation of dropping dependent
+      "Don't warn about or ask for confirmation if dropping dependent
        packages."
     }
 
-    bool --disfigure-only
-    {
-      "Disfigure all the packages but don't purge."
-    }
-
     bool --print-only|-p
     {
       "Print to \cb{STDOUT} what would be done without actually doing
        anything."
     }
+
+    bool --disfigure-only
+    {
+      "Disfigure all the packages but don't purge."
+    }
   };
 }
diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli
index ba1d5d9..562daab 100644
--- a/bpkg/pkg-fetch.cli
+++ b/bpkg/pkg-fetch.cli
@@ -8,33 +8,37 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-fetch"
 "\summary=fetch package archive"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg> <ver> <file>",
 
-bpkg pkg-fetch [<options>] (<pkg>/<ver>)|(-e <file>)"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-fetch} [<options>] (<pkg>/<ver>) | (-e <file>)}
 
-The \cb{pkg-fetch} command fetches the archive for the specified package
-name and version from one of the configuration's repositories. If the
-\cb{-r|--replace} option is specified, then \cb{pkg-fetch} will replace the
-archive of a package that is already in the \cb{fetched} or \cb{unpacked}
-state. Otherwise, \cb{pkg-fetch} expects the package to not exist in the
-configuration's database.
+     \h|DESCRIPTION|
 
-If the \cb{-e|--existing} option is used, then instead of the name and
-version argument, \cb{pkg-fetch} expects a local path to the existing
-package archive. In this case, \cb{bpkg} will use the archive in place,
-without copying it to the configuration or package cache directories.
-Also, unless the \cb{-p|--purge} option is specified, \cb{bpkg} will
-not attempt to remove the archive when the package is purged with the
-\cb{pkg-purge} command."
-*/
+     The \cb{pkg-fetch} command fetches the archive for the specified package
+     name and version from one of the repositories (\l{bpkg-cfg-add(1)}). If
+     the \cb{--replace|-r} option is specified, then \cb{pkg-fetch} will
+     replace the archive of a package that is already in the \cb{fetched} or
+     \cb{unpacked} state (\l{bpkg-pkg-status(1)}). Otherwise, \cb{pkg-fetch}
+     expects the package to not exist in the configuration.
+
+     If the \cb{--existing|-e} option is used, then instead of the name and
+     version arguments, \cb{pkg-fetch} expects a local path to an existing
+     package archive. In this case, \cb{bpkg} will use the archive in place,
+     without copying it to the configuration or package cache directories.
+     Also, unless the \cb{--purge|-p} option is specified, \cb{bpkg} will not
+     attempt to remove this archive when the package is later purged with the
+     \l{bpkg-pkg-purge(1)} command."
+  }
 
-namespace bpkg
-{
   class pkg_fetch_options: configuration_options
   {
+    "\h|PKG-FETCH OPTIONS|"
+
     bool --replace|-r
     {
       "Replace the archive if the package is already fetched or unpacked."
@@ -43,7 +47,7 @@ namespace bpkg
     bool --existing|-e
     {
       "Treat the argument as an existing package archive path rather than
-       package name/version to fetch."
+       the package name/version to fetch."
     }
 
     bool --purge|-p
diff --git a/bpkg/pkg-install.cli b/bpkg/pkg-install.cli
index 0c1385b..3c700a0 100644
--- a/bpkg/pkg-install.cli
+++ b/bpkg/pkg-install.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-install} [<options>] <pkg>...}
+     \c{\b{bpkg pkg-install}|\b{install} [<options>] <pkg>...}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-purge.cli b/bpkg/pkg-purge.cli
index da618d3..490f316 100644
--- a/bpkg/pkg-purge.cli
+++ b/bpkg/pkg-purge.cli
@@ -8,39 +8,42 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-purge"
 "\summary=purge package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg>",
 
-bpkg pkg-purge [<options>] <pkg>"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-purge} [<options>] <pkg>}
 
-The \cb{pkg-purge} command removes the package directory and archive
-from the filesystem and removes the package from the configuration's
-database. Only packages in the \cb{fetched} and \cb{unpacked} state can
-be purged plus \cb{broken} packages if the \cb{-f|--force} options is
-specified (see this option's description for details on purging broken
-packages). If the \cb{-k|--keep} option is specified, then the package
-archive is not removed (see this option's description for details on
-this mode)."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-purge} command removes the package directory and archive from
+     the filesystem and removes the package from the configuration.  Only
+     packages in the \cb{fetched} and \cb{unpacked} state
+     (\l{bpkg-pkg-status(1)}) can be purged plus \cb{broken} packages if the
+     \cb{--force|-f} option is specified (see the option's description for
+     details on purging broken packages). If the \cb{--keep|-k} option is
+     specified, then the package archive is not removed (see the option's
+     description for details on this mode)."
+  }
 
-namespace bpkg
-{
   class pkg_purge_options: configuration_options
   {
+    "\h|PKG-PURGE OPTIONS|"
+
     bool --keep|-k
     {
-      "Keep the package archive. Note that in this mode the package is
-       still retained in the configuration's database in the \cb{fetched}
-       state."
+      "Keep the package archive. Note that in this mode the package is still
+       retained in the configuration's database in the \cb{fetched} state."
     }
 
     bool --force|-f
     {
-      "Purge a broken package. In this mode \cb{bpkg} will verify that
-       the package directory and archive no longer exist and will remove
-       the package from the configuration's database."
+      "Purge a broken package. In this mode \cb{bpkg} will verify that the
+       package directory and archive no longer exist and then remove the
+       package from the configuration."
     }
   };
 }
diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli
index fb20f78..87ff442 100644
--- a/bpkg/pkg-status.cli
+++ b/bpkg/pkg-status.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]}
+     \c{\b{bpkg pkg-status}|\b{status} [<options>] <pkg>[/<ver>]}
 
      \h|DESCRIPTION|
 
@@ -23,19 +23,19 @@ namespace bpkg
      if <ver> is specified, package version. Note that the status is written
      to \cb{STDOUT}, not \cb{STDERR}.
 
-     The status format is regular. First always comes one of the following
-     status words:
+     The status output format is regular. First always comes one of the
+     following status words:
 
      \dl|
 
      \li|\cb{unknown}
 
-         package is not part of the configuration nor available in one of the
+         package is not part of the configuration nor available from any of the
          repositories|
 
      \li|\cb{available}
 
-         package is not part of the configuration but is available in one of
+         package is not part of the configuration but is available from one of
          the repositories|
 
      \li|\cb{fetched}
@@ -48,7 +48,12 @@ namespace bpkg
 
      \li|\cb{configured}
 
-         package is part of the configuration and is configured||
+         package is part of the configuration and is configured|
+
+     \li|\cb{broken}
+
+         package is part of the configuration and is broken (broken packages
+         can only be purged; see \l{bpkg-pkg-purge(1)})||
 
 
      If only the package name was specified without the package version, then
@@ -56,47 +61,47 @@ namespace bpkg
      versions.
 
      Similarly, if only the package name was specified, then the \cb{fetched},
-     \cb{unpacked}, and \cb{configured} status words are followed by the
-     version of the package. After the possible package version, these status
+     \cb{unpacked}, \cb{configured}, and \cb{broken} status words are followed
+     by the version of the package. After the package version, these status
      words may be followed by one or more sub-status words. Currently, these
-     can be \cb{hold_package} (package should not be automatically dropped)
-     and \cb{hold_version} (package should not be automatically upgraded).
-     Finally, if only the package name was specified and newer versions are
-     available in the repositories, then the sub-status words are followed
+     can be \cb{hold_package} (package should not be automatically dropped) and
+     \cb{hold_version} (package should not be automatically upgraded). Finally,
+     if only the package name was specified and newer versions are available
+     from some of the repositories, then the sub-status word is followed
      by '\cb{;}', the \cb{available} status word, and the list of newer
      versions.
 
-     Below are some examples, assuming the configuration has libfoo 1.0.0
-     configured and held as well as libfoo 1.1.0 and 1.1.1 available from a
-     repository.
+     Below are some examples, assuming the configuration has \cb{libfoo}
+     \cb{1.0.0} configured and held as well as \cb{libfoo} \cb{1.1.0} and
+     \cb{1.1.1} available from a repository.
 
      \
-     bpkg pkg-status libbar
+     bpkg status libbar
      unknown
 
-     bpkg pkg-status libbar/1.0.0
+     bpkg status libbar/1.0.0
      unknown
 
-     bpkg pkg-status libfoo/1.0.0
+     bpkg status libfoo/1.0.0
      configured hold_package
 
-     bpkg pkg-status libfoo/1.1.0
+     bpkg status libfoo/1.1.0
      available
 
-     bpkg pkg-status libfoo
+     bpkg status libfoo
      configured 1.0.0 hold_package; available 1.1.0 1.1.1
      \
 
-     Assuming now that we dropped libfoo from the configuration:
+     Assuming now that we dropped \cb{libfoo} from the configuration:
 
      \
-     bpkg pkg-status libfoo/1.0.0
+     bpkg status libfoo/1.0.0
      unknown
 
-     bpkg pkg-status libfoo/1.1.0
+     bpkg status libfoo/1.1.0
      available
 
-     bpkg pkg-status libfoo
+     bpkg status libfoo
      available 1.1.0 1.1.1
      \
      "
diff --git a/bpkg/pkg-uninstall.cli b/bpkg/pkg-uninstall.cli
index 536f6ec..89f9dc0 100644
--- a/bpkg/pkg-uninstall.cli
+++ b/bpkg/pkg-uninstall.cli
@@ -15,12 +15,12 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-uninstall} [<options>] <pkg>...}
+     \c{\b{bpkg pkg-uninstall}|\b{uninstall} [<options>] <pkg>...}
 
      \h|DESCRIPTION|
 
      The \cb{pkg-uninstall} command uninstalls one or more packages that were
-     previously installed with \l{bpkg-cfg-install(1)}. Underneath, this
+     previously installed with \l{bpkg-pkg-install(1)}. Underneath, this
      command doesn't do much more than run \cb{b uninstall}."
   }
 
diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli
index 847ecb2..67f37b7 100644
--- a/bpkg/pkg-unpack.cli
+++ b/bpkg/pkg-unpack.cli
@@ -8,37 +8,40 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-unpack"
 "\summary=unpack package archive"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg> <dir>",
 
-bpkg pkg-unpack [<options>] <pkg>|(-e <dir>)"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-unpack} [<options>] <pkg> | (-e <dir>)}
 
-The \cb{pkg-unpack} command unpacks the archive for the previously
-fetched (\cb{pkg-fetch}) package. If the \cb{-e|--existing} option
-is used, then instead of the package name, \cb{pkg-unpack} expects
-a local path to the existing package source directory. In this case,
-\cb{bpkg} will use the directory in place, without copying it to the
-configuration or package cache directories. Also, unless the
-\cb{-p|--purge} option is specified, \cb{bpkg} will not attempt to
-remove this directory when the package is purged with the \cb{pkg-purge}
-command.
+     \h|DESCRIPTION|
 
-If \cb{-e|--existing} is specified together with the \cb{-r|--replace}
-option, then \cb{pkg-unpack} will replace the archive and/or source
-directory of a package that is already in the \cb{unpacked} or
-\cb{fetched} state."
-*/
+     The \cb{pkg-unpack} command unpacks the archive for the previously fetched
+     (\l{bpkg-pkg-fetch(1)}) package. If the \cb{--existing|-e} option is used,
+     then instead of the package name, \cb{pkg-unpack} expects a local path to
+     an existing package directory. In this case, \cb{bpkg} will use the
+     directory in place, without copying it to the configuration or package
+     cache directories. Also, unless the \cb{--purge|-p} option is specified,
+     \cb{bpkg} will not attempt to remove this directory when the package is
+     later purged with the \l{bpkg-pkg-purge(1)} command.
+
+     If \cb{--existing|-e} is specified together with the \cb{--replace|-r}
+     option, then \cb{pkg-unpack} will replace the archive and/or source
+     directory of a package that is already in the \cb{unpacked} or
+     \cb{fetched} state (\l{bpkg-pkg-status(1)})."
+  }
 
-namespace bpkg
-{
   class pkg_unpack_options: configuration_options
   {
+    "\h|PKG-UNPACK OPTIONS|"
+
     bool --existing|-e
     {
       "Treat the argument as an existing package directory path rather than
-       package name to unpack."
+       the package name to unpack."
     }
 
     bool --purge|-p
@@ -49,7 +52,7 @@ namespace bpkg
     bool --replace|-r
     {
       "Replace the source directory if the package is already unpacked or
-       fetched. Can only be specified together with \cb{-e|--existing}."
+       fetched. Can only be specified together with \cb{--existing|-e}."
     }
   };
 }
diff --git a/bpkg/pkg-update.cli b/bpkg/pkg-update.cli
index 09a5f59..cce17b0 100644
--- a/bpkg/pkg-update.cli
+++ b/bpkg/pkg-update.cli
@@ -8,21 +8,24 @@ include <bpkg/configuration.cli>;
 "\name=bpkg-pkg-update"
 "\summary=update package"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <pkg>",
 
-bpkg pkg-update <pkg>..."
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-update}|\b{update} [<options>] <pkg>...}
 
-The \cb{pkg-update} command updates the previously configured
-(\cb{pkg-configure}) package. Underneath, this command doesn't
-do much more than run (\cb{b update})."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-update} command updates the previously configured
+     (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package.
+     Underneath, this command doesn't do much more than run \cb{b update}."
+  }
 
-namespace bpkg
-{
   class pkg_update_options: configuration_options
   {
+    "\h|PKG-UPDATE OPTIONS|"
   };
 }
diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli
index 850b7d4..534b98e 100644
--- a/bpkg/pkg-verify.cli
+++ b/bpkg/pkg-verify.cli
@@ -6,35 +6,41 @@ include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-verify"
-"\summary=verify archive is a valid package"
+"\summary=verify package archive"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <archive>",
 
-bpkg pkg-verify <archive>"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-verify} [<options>] <archive>}
 
-The \cb{pkg-verify} command verifies that the specified archive is a
-valid \cb{bpkg} package. Specifically, it checks that the archive
-contains a valid manifest file and that both the archive's name
-and its top-level directory match the canonical <name>-<version>
-form."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{pkg-verify} command verifies that the specified archive is a
+     valid \cb{bpkg} package. Specifically, it checks that the archive's name
+     and the top-level directory inside the archive match the canonical
+     '\c{\i{name}\b{-}\i{version}}' form and that there is a valid manifest
+     file in that top-level directory."
+  }
 
-namespace bpkg
-{
   class pkg_verify_options: common_options
   {
+    "\h|PKG-VERIFY OPTIONS|"
+
     bool --silent
     {
-      "Suppress error messages about the reason why the package is
+      "Suppress the error messages about the reason why the package is
        invalid. Just return the error status."
     }
 
     bool --ignore-unknown
     {
-      "Ignore unknown manifest entries."
+      "Ignore unknown manifest entries. By default, \cb{bpkg} will refuse to
+       declare such a package validate since it cannot be sure the unknown
+       entries are valid."
     }
   };
 }
diff --git a/bpkg/rep-create.cli b/bpkg/rep-create.cli
index b472cfc..fc11a0c 100644
--- a/bpkg/rep-create.cli
+++ b/bpkg/rep-create.cli
@@ -6,19 +6,28 @@ include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-rep-create"
-"\summary=create repository manifest file"
+"\summary=create repository"
 
 namespace bpkg
 {
-  class rep_create_options: common_options
   {
-    /*
-      "Create repository manifest file (\cb{packages}) based on the
-       packages present in the repository directory."
+    "<options> <dir>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bpkg rep-create} [<options>] [<dir>]}
+
+     \h|DESCRIPTION|
 
-      "Use <dir> as the repository root directory instead of the
-       current working directory."
-    */
+     The \cb{rep-create} command regenerates the \cb{packages} manifest file
+     based on the files present in the repository directory. If <dir> is not
+     specified, then the current working directory is used as the repository
+     root."
+  }
+
+  class rep_create_options: common_options
+  {
+    "\h|REP-CREATE OPTIONS|"
 
     bool --ignore-unknown
     {
diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli
index 0db3004..7554620 100644
--- a/bpkg/rep-info.cli
+++ b/bpkg/rep-info.cli
@@ -6,27 +6,31 @@ include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-rep-info"
-"\summary=print information about repository"
+"\summary=print repository information"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <rep>",
 
-bpkg rep-info [<options>] <rep>"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg rep-info} [<options>] <rep>}
 
-The \cb{rep-info} command prints information about the specified repository.
-By default it print the repository's name and location as the first line
-followed by the list of prerequisite/complement repositories and the list
-of available packages. This default behavior, however, can be altered in
-various ways using options listed below. Note that the information is
-written to \cb{STDOUT}, not \cb{STDERR}."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{rep-info} command prints various information about the specified
+     repository. By default it print the repository's name and location as the
+     first line followed by the list of complement and prerequisite
+     repositories and the list of available packages. This default behavior,
+     however, can be altered in various ways using options listed below. Note
+     that the information is written to \cb{STDOUT}, not \cb{STDERR}."
+  }
 
-namespace bpkg
-{
   class rep_info_options: common_options
   {
+    "\h|REP-INFO OPTIONS|"
+
     bool --name|-n
     {
       "Print the specified repository's name and location."
@@ -34,20 +38,20 @@ namespace bpkg
 
     bool --repositories|-r
     {
-      "Print information about prerequisite/complement repositories."
+      "Print the list of complement and prerequisite repositories."
     }
 
     bool --packages|-p
     {
-      "Print information about available packages."
+      "Print the list of available packages."
     }
 
     bool --manifest|-m
     {
-      "Instead of printing the information in the human-readable form, dump
-       it as manifest(s). Normally you would use this option in combination
-       with \cb{--packages|-p} or \cb{--repositories|-r} to only dump one
-       of the manifests."
+      "Instead of printing the information in the human-readable form, dump it
+       as manifest(s). Normally you would use this option in combination with
+       \cb{--packages|-p} or \cb{--repositories|-r} to only dump one of the
+       manifests."
     }
   };
 }