New command line help setup

8 files changed, 170 insertions, 172 deletions

diff --git a/bpkg/bpkg-options.cli b/bpkg/bpkg-options.cli
index 5da4213..b0f14e3 100644
--- a/bpkg/bpkg-options.cli
+++ b/bpkg/bpkg-options.cli
@@ -10,25 +10,39 @@ include <bpkg/common-options.cli>;
 
 namespace bpkg
 {
-  class bpkg_options: common_options
   {
-    bool --help;
-    bool --version;
-  };
+    "<command> <topic> <common-options> <command-options> <command-args>",
+
+    "\h|SYNOPSIS|
+
+     \cb{bpkg --help}\n
+     \cb{bpkg --version}\n
+     \c{\b{bpkg help} [<command>|<topic>]}\n
+     \c{\b{bpkg} [<common-options>] <command> [<command-options>] <command-args>}
+
+     \h|DESCRIPTION|
+
+     @@ TODO
+
+     Note that the common options can also be specified as part of the
+     command-specific options."
+  }
 
-  class bpkg_commands
+  class commands
   {
+    "\h|COMMANDS|"
+
     bool help
     {
       "[<topic>]",
-      "Show detailed help for a command or help topic.",
+      "Show help for a command or help topic \- \l{bpkg-help(1)}.",
       ""
     };
 
     bool build
     {
       "<pkg>...",
-      "Build one or more packages.",
+      "Build one or more packages \- \l{bpkg-build-options(1)}.",
       ""
     };
 
@@ -140,11 +154,19 @@ namespace bpkg
 
   // Make sure these don't conflict with command names above.
   //
-  class bpkg_topics
+  class topics
   {
-    bool common
+    "\h|HELP TOPICS|"
+
+    bool common-options
     {
-      "Detailed description of common options."
+      "Options common for all commands \- \l{bpkg-common-options(1)}."
     };
   };
+
+  class options: common_options
+  {
+    bool --help;
+    bool --version;
+  };
 }
diff --git a/bpkg/bpkg.cxx b/bpkg/bpkg.cxx
index 85f6477..386d284 100644
--- a/bpkg/bpkg.cxx
+++ b/bpkg/bpkg.cxx
@@ -72,10 +72,10 @@ try
 
   // First parse common options and --version/--help.
   //
-  bpkg_options bo;
-  bo.parse (args, unknown_mode::stop);
+  options o;
+  o.parse (args, unknown_mode::stop);
 
-  if (bo.version ())
+  if (o.version ())
   {
     cout << "bpkg " << BPKG_VERSION_STR << "; " <<
       "libbpkg " << LIBBPKG_VERSION_STR << endl
@@ -84,13 +84,13 @@ try
     return 0;
   }
 
-  if (bo.help ())
+  if (o.help ())
   {
     help (help_options (), "", nullptr);
     return 0;
   }
 
-  const common_options& co (bo);
+  const common_options& co (o);
 
   // The next argument should be a command.
   //
@@ -100,7 +100,7 @@ try
 
   int cmd_argc (2);
   char* cmd_argv[] {argv[0], const_cast<char*> (args.next ())};
-  bpkg_commands cmd;
+  commands cmd;
   cmd.parse (cmd_argc, cmd_argv, true, unknown_mode::stop);
 
   if (cmd_argc != 1)
@@ -125,7 +125,7 @@ try
 
       // First see if this is a command.
       //
-      cmd = bpkg_commands (); // Clear help option.
+      cmd = commands (); // Clear the help option.
       cmd.parse (cmd_argc, cmd_argv, true, unknown_mode::stop);
 
       // If not, then it got to be a help topic.
diff --git a/bpkg/build-options.cli b/bpkg/build-options.cli
index 7164dbb..00a4c9c 100644
--- a/bpkg/build-options.cli
+++ b/bpkg/build-options.cli
@@ -8,41 +8,42 @@ include <bpkg/configuration-options.cli>;
 "\name=bpkg-build"
 "\summary=build one or more packages"
 
+namespace bpkg
 {
-"<options> <pkg> <ver> <file> <dir>",
-
-"\h|SYNOPSIS|
+  {
+    "<options> <pkg> <ver> <file> <dir>",
 
-\c{\b{bpkg build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...}
+    "\h|SYNOPSIS|
 
-\h|DESCRIPTION|
+     \c{\b{bpkg build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...}
 
-The \cb{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{rep-add} and \cb{rep-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.
+     \h|DESCRIPTION|
 
-Packages that are specified explicitly on the command line will be \i{held},
-that is, they will not be considered for automatic removal if they no longer
-have any dependents. Packages that are specified with the explicit package
-version (<ver>) or as an archive or directory, will, in addition, have their
-versions held, that is, they will not be automatically upgraded.
+     The \cb{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{rep-add} and \cb{rep-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.
 
-The \cb{build} command also supports several \cb{--*-only} options that allow
-you to limit the amount of work that will be done.
+     Packages that are specified explicitly on the command line will be
+     \i{held}, that is, they will not be considered for automatic removal if
+     they no longer have any dependents. Packages that are specified with the
+     explicit package version (<ver>) or as an archive or directory, will, in
+     addition, have their versions held, that is, they will not be
+     automatically upgraded.
 
-\h|OPTIONS|"
-}
+     The \cb{build} command also supports several \cb{--*-only} options that
+     allow you to limit the amount of work that will be done."
+  }
 
-namespace bpkg
-{
   class build_options: configuration_options
   {
+    "\h|BUILD OPTIONS|"
+
     bool --yes|-y
     {
       "Assume the answer to all prompts is \cb{yes}."
diff --git a/bpkg/buildfile b/bpkg/buildfile
index cc03a28..02fdb31 100644
--- a/bpkg/buildfile
+++ b/bpkg/buildfile
@@ -40,19 +40,17 @@ cli.options += -I $src_root --include-with-brackets --include-prefix bpkg \
 --guard-prefix BPKG --cxx-prologue "#include <bpkg/types-parsers>"        \
 --cli-namespace bpkg::cli --generate-file-scanner --generate-specifier    \
 --generate-parse --ansi-color --page-usage 'bpkg::print_$name$_'          \
---long-usage --option-length 20
+--include-base-last --long-usage --option-length 20
 
 cli.cxx{common-options}: cli{common-options}
 cli.cxx{common-options}: cli.options += --short-usage
 
+cli.cxx{configuration-options}: cli{configuration-options}
+
 cli.cxx{bpkg-options}: cli{bpkg-options}
-cli.cxx{bpkg-options}: cli.options += --short-usage
+cli.cxx{bpkg-options}: cli.options += --suppress-undocumented
 
 cli.cxx{help-options}: cli{help-options}
-cli.cxx{help-options}: cli.options += --exclude-base
-
-cli.cxx{configuration-options}: cli{configuration-options}
-cli.cxx{configuration-options}: cli.options += --exclude-base
 
 #
 #
@@ -69,22 +67,15 @@ cli.cxx{pkg-configure-options}: cli{pkg-configure-options}
 cli.cxx{pkg-disfigure-options}: cli{pkg-disfigure-options}
 cli.cxx{pkg-update-options}:    cli{pkg-update-options}
 cli.cxx{pkg-clean-options}:     cli{pkg-clean-options}
-
-cli.cxx{pkg-verify-options}: cli{pkg-verify-options}
-cli.cxx{pkg-verify-options}: cli.options += --exclude-base
+cli.cxx{pkg-verify-options}:    cli{pkg-verify-options}
 
 # cfg-*
 #
 cli.cxx{cfg-create-options}: cli{cfg-create-options}
-cli.cxx{cfg-create-options}: cli.options += --exclude-base
 
 # rep-*
 #
 cli.cxx{rep-add-options}:   cli{rep-add-options}
 cli.cxx{rep-fetch-options}: cli{rep-fetch-options}
-
 cli.cxx{rep-info-options}: cli{rep-info-options}
-cli.cxx{rep-info-options}: cli.options += --exclude-base
-
 cli.cxx{rep-create-options}: cli{rep-create-options}
-cli.cxx{rep-create-options}: cli.options += --exclude-base
diff --git a/bpkg/common-options.cli b/bpkg/common-options.cli
index a8b6744..f07d70e 100644
--- a/bpkg/common-options.cli
+++ b/bpkg/common-options.cli
@@ -5,13 +5,38 @@
 include <bpkg/types>;
 
 "\section=1"
-"\name=bpkg-common"
-"\summary=common options for all commands"
+"\name=bpkg-common-options"
+"\summary=options common for all commands"
 
 namespace bpkg
 {
+  {
+    "<common-options>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bpkg} [<common-options>] ...}
+
+     \h|DESCRIPTION|
+
+     The common options can be specified either before the command or after,
+     togethere with the command-specific options."
+  }
+
   class common_options = 0
   {
+    "\h|COMMON OPTIONS|"
+
+    // Retain this note only in the summary.
+    //
+    {
+      "",
+      "The common options are summarized below with a more detailed description
+       available as the \l{bpkg-common-options(1) \cb{common-options}} help
+       topic.",
+      ""
+    }
+
     bool -v
     {
       "Print underlying commands being executed. This is equivalent to
diff --git a/bpkg/help b/bpkg/help
index 8bd5596..e941d40 100644
--- a/bpkg/help
+++ b/bpkg/help
@@ -12,10 +12,10 @@
 
 namespace bpkg
 {
+  using usage_function = cli::usage_para (std::ostream&, cli::usage_para);
+
   int
-  help (const help_options&,
-        const string& topic,
-        void (*usage) (std::ostream&));
+  help (const help_options&, const string& topic, usage_function* usage);
 }
 
 #endif // BPKG_HELP
diff --git a/bpkg/help.cxx b/bpkg/help.cxx
index 0505061..df4a286 100644
--- a/bpkg/help.cxx
+++ b/bpkg/help.cxx
@@ -19,64 +19,21 @@ namespace bpkg
   static void
   help ()
   {
-    ostream& o (cout);
-
-    //@@ TODO
-
-    o << "usage: bpkg --help" << endl
-      << "       bpkg --version" << endl
-      << "       bpkg help [<command>|<topic>]" << endl
-      << "       bpkg [<common-options>] <command> [<command-options>] " <<
-      "[<command-args>]" << endl
-      << endl;
-
-    o << "The commands are:" << endl
-      << endl;
-
-    bpkg_commands::print_short_usage (o);
-    o << endl;
-
-    o << "The help topics are:" << endl
-      << endl;
-
-    bpkg_topics::print_short_usage (o);
-    o << endl;
-
-    o << "The common options are summarized below. Note that they can also "
-      "be specified" << endl
-      << "as part of the command-specific options." << endl
-      << endl;
-
-    common_options::print_short_usage (o);
-    o << endl;
-
-    o << ""<< endl;
+    print_bpkg_usage (cout);
   }
 
   int
-  help (const help_options&, const string& t, void (*usage) (std::ostream&))
+  help (const help_options&, const string& t, usage_function* usage)
   {
     ostream& o (cout);
 
     if (usage != nullptr)    // Command.
-    {
-      usage (o);
-
-      //@@ TODO
-
-      o << endl
-        << "The common options are summarized below. For details, see the " <<
-        "'common' help" << endl
-        << "topic." << endl
-        << endl;
-
-      common_options::print_short_usage (o);
-    }
-    else if (t.empty ())     // General help.
+      usage (o, cli::usage_para::none);
+    else if (t.empty ())             // General help.
       help ();
-    else if (t == "common")  // Help topics.
+    else if (t == "common-options")  // Help topics.
     {
-      print_bpkg_common_long_usage (cout);
+      print_bpkg_common_options_long_usage (cout);
     }
     else
       fail << "unknown bpkg command/help topic '" << t << "'" <<
diff --git a/bpkg/pkg-status-options.cli b/bpkg/pkg-status-options.cli
index c3ea3d6..f106ddc 100644
--- a/bpkg/pkg-status-options.cli
+++ b/bpkg/pkg-status-options.cli
@@ -8,100 +8,102 @@ include <bpkg/configuration-options.cli>;
 "\name=bpkg-pkg-status"
 "\summary=print package status"
 
+namespace bpkg
 {
-"<options> <pkg> <ver>",
-
-"\h|SYNOPSIS|
+  {
+    "<options> <pkg> <ver>",
 
-\c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]}
+    "\h|SYNOPSIS|
 
-\h|DESCRIPTION|
+     \c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]}
 
-The \cb{pkg-status} command prints the status of the specified package or, if
-<ver> is specified, package version. Note that the status is written to
-\cb{STDOUT}, not \cb{STDERR}.
+     \h|DESCRIPTION|
 
-The status format is regular. First always comes one of the following status
-words:
+     The \cb{pkg-status} command prints the status of the specified package or,
+     if <ver> is specified, package version. Note that the status is written
+     to \cb{STDOUT}, not \cb{STDERR}.
 
-\dl|
+     The status format is regular. First always comes one of the following
+     status words:
 
-\li|\cb{unknown}
+     \dl|
 
-    package is not part of the configuration nor available in one of the
-    repositories|
+     \li|\cb{unknown}
 
-\li|\cb{available}
+         package is not part of the configuration nor available in one of the
+         repositories|
 
-    package is not part of the configuration but is available in one of the
-    repositories|
+     \li|\cb{available}
 
-\li|\cb{fetched}
+         package is not part of the configuration but is available in one of
+         the repositories|
 
-    package is part of the configuration and is fetched|
+     \li|\cb{fetched}
 
-\li|\cb{unpacked}
+         package is part of the configuration and is fetched|
 
-    package is part of the configuration and is unpacked|
+     \li|\cb{unpacked}
 
-\li|\cb{configured}
+         package is part of the configuration and is unpacked|
 
-    package is part of the configuration and is configured||
+     \li|\cb{configured}
 
+         package is part of the configuration and is configured||
 
-If only the package name was specified without the package version, then the
-\cb{available} status word is followed by the list of available 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 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 by '\cb{;}',
-the \cb{available} status word, and the list of newer versions.
+     If only the package name was specified without the package version, then
+     the \cb{available} status word is followed by the list of available
+     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.
+     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
+     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
+     by '\cb{;}', the \cb{available} status word, and the list of newer
+     versions.
 
-\
-bpkg pkg-status libbar
-unknown
+     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.
 
-bpkg pkg-status libbar/1.0.0
-unknown
+     \
+     bpkg pkg-status libbar
+     unknown
 
-bpkg pkg-status libfoo/1.0.0
-configured hold_package
+     bpkg pkg-status libbar/1.0.0
+     unknown
 
-bpkg pkg-status libfoo/1.1.0
-available
+     bpkg pkg-status libfoo/1.0.0
+     configured hold_package
 
-bpkg pkg-status libfoo
-configured 1.0.0 hold_package; available 1.1.0 1.1.1
-\
+     bpkg pkg-status libfoo/1.1.0
+     available
 
-Assuming now that we dropped libfoo from the configuration:
+     bpkg pkg-status libfoo
+     configured 1.0.0 hold_package; available 1.1.0 1.1.1
+     \
 
-\
-bpkg pkg-status libfoo/1.0.0
-unknown
+     Assuming now that we dropped libfoo from the configuration:
 
-bpkg pkg-status libfoo/1.1.0
-available
+     \
+     bpkg pkg-status libfoo/1.0.0
+     unknown
 
-bpkg pkg-status libfoo
-available 1.1.0 1.1.1
-\
+     bpkg pkg-status libfoo/1.1.0
+     available
 
-\h|OPTIONS|"
-}
+     bpkg pkg-status libfoo
+     available 1.1.0 1.1.1
+     \
+     "
+  }
 
-namespace bpkg
-{
   class pkg_status_options: configuration_options
   {
+    "\h|PKG-STATUS OPTIONS|"
   };
 }