23 files changed, 56 insertions, 28 deletions
diff --git a/bpkg/bpkg-options.cli b/bpkg/bpkg-options.cli
index 176eafd..5da4213 100644
--- a/bpkg/bpkg-options.cli
+++ b/bpkg/bpkg-options.cli
@@ -4,6 +4,10 @@
 
 include <bpkg/common-options.cli>;
 
+"\section=1"
+"\name=bpkg"
+"\summary=build2 package manager"
+
 namespace bpkg
 {
   class bpkg_options: common_options
@@ -38,7 +42,7 @@ namespace bpkg
     bool pkg-verify
     {
       "<archive>",
-      "Verify archive is a valid \cb{bpkg} package.",
+      "Verify archive is a valid package.",
       ""
     };
 
@@ -138,7 +142,7 @@ namespace bpkg
   //
   class bpkg_topics
   {
-    bool options
+    bool common
     {
       "Detailed description of common options."
     };
diff --git a/bpkg/bpkg.cxx b/bpkg/bpkg.cxx
index 6246d6f..85f6477 100644
--- a/bpkg/bpkg.cxx
+++ b/bpkg/bpkg.cxx
@@ -173,7 +173,7 @@ try
     if (cmd.NP##CMD ())                                                 \
     {                                                                   \
       if (h)                                                            \
-        help (ho, SP#CMD, NP##CMD##_options::print_usage);              \
+        help (ho, SP#CMD, print_bpkg_##NP##CMD##_usage);                \
       else                                                              \
         r = NP##CMD (parse<NP##CMD##_options> (co, args), args);        \
                                                                         \
diff --git a/bpkg/build-options.cli b/bpkg/build-options.cli
index 300afa1..7164dbb 100644
--- a/bpkg/build-options.cli
+++ b/bpkg/build-options.cli
@@ -8,10 +8,6 @@ include <bpkg/configuration-options.cli>;
 "\name=bpkg-build"
 "\summary=build one or more packages"
 
-"\project=bpkg"          //@@ command line
-"\version=0.1.0"         //@@ command line
-"\date=12 November 2015" //@@ command line; release date
-
 {
 "<options> <pkg> <ver> <file> <dir>",
 
diff --git a/bpkg/buildfile b/bpkg/buildfile
index e01dc92..cc03a28 100644
--- a/bpkg/buildfile
+++ b/bpkg/buildfile
@@ -39,7 +39,8 @@ exe{bpkg}: cxx{satisfaction fetch package package-odb manifest-utility \
 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 --long-usage --option-length 22
+--generate-parse --ansi-color --page-usage 'bpkg::print_$name$_'          \
+--long-usage --option-length 20
 
 cli.cxx{common-options}: cli{common-options}
 cli.cxx{common-options}: cli.options += --short-usage
diff --git a/bpkg/cfg-create-options.cli b/bpkg/cfg-create-options.cli
index cbdf1c9..f368d82 100644
--- a/bpkg/cfg-create-options.cli
+++ b/bpkg/cfg-create-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/common-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-cfg-create"
+"\summary=create configuration"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg cfg-create [<options>] [(<module>|<conf-var>)...]"
diff --git a/bpkg/common-options.cli b/bpkg/common-options.cli
index 04c67e3..a8b6744 100644
--- a/bpkg/common-options.cli
+++ b/bpkg/common-options.cli
@@ -4,6 +4,10 @@
 
 include <bpkg/types>;
 
+"\section=1"
+"\name=bpkg-common"
+"\summary=common options for all commands"
+
 namespace bpkg
 {
   class common_options = 0
diff --git a/bpkg/configuration-options.cli b/bpkg/configuration-options.cli
index 712c7da..97c0fa3 100644
--- a/bpkg/configuration-options.cli
+++ b/bpkg/configuration-options.cli
@@ -4,6 +4,8 @@
 
 include <bpkg/common-options.cli>;
 
+"\name=configuration" // Not a man page.
+
 namespace bpkg
 {
   // Common options for commands that operate on a configuration.
diff --git a/bpkg/drop-options.cli b/bpkg/drop-options.cli
index ca67c14..5669256 100644
--- a/bpkg/drop-options.cli
+++ b/bpkg/drop-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-drop"
+"\summary=drop one or more packages"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg drop [<options>] <pkg>..."
diff --git a/bpkg/help-options.cli b/bpkg/help-options.cli
index 4ed03cf..51d9c2d 100644
--- a/bpkg/help-options.cli
+++ b/bpkg/help-options.cli
@@ -4,6 +4,10 @@
 
 include <bpkg/common-options.cli>;
 
+"\section=1"
+"\name=bpkg-help"
+"\summary=show help for a command or help topic"
+
 namespace bpkg
 {
   class help_options: common_options
diff --git a/bpkg/help.cxx b/bpkg/help.cxx
index f03ad21..0505061 100644
--- a/bpkg/help.cxx
+++ b/bpkg/help.cxx
@@ -21,6 +21,8 @@ namespace bpkg
   {
     ostream& o (cout);
 
+    //@@ TODO
+
     o << "usage: bpkg --help" << endl
       << "       bpkg --version" << endl
       << "       bpkg help [<command>|<topic>]" << endl
@@ -60,9 +62,11 @@ namespace bpkg
     {
       usage (o);
 
+      //@@ TODO
+
       o << endl
         << "The common options are summarized below. For details, see the " <<
-        "'options' help" << endl
+        "'common' help" << endl
         << "topic." << endl
         << endl;
 
@@ -70,9 +74,9 @@ namespace bpkg
     }
     else if (t.empty ())     // General help.
       help ();
-    else if (t == "options") // Help topics.
+    else if (t == "common")  // Help topics.
     {
-      common_options::print_long_usage (cout);
+      print_bpkg_common_long_usage (cout);
     }
     else
       fail << "unknown bpkg command/help topic '" << t << "'" <<
diff --git a/bpkg/pkg-clean-options.cli b/bpkg/pkg-clean-options.cli
index bc8b0eb..e790db6 100644
--- a/bpkg/pkg-clean-options.cli
+++ b/bpkg/pkg-clean-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-clean"
+"\summary=clean package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-clean <pkg>"
diff --git a/bpkg/pkg-configure-options.cli b/bpkg/pkg-configure-options.cli
index f7b8f9f..0da9c64 100644
--- a/bpkg/pkg-configure-options.cli
+++ b/bpkg/pkg-configure-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-configure"
+"\summary=configure package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-configure <pkg> [<conf-vars>]"
diff --git a/bpkg/pkg-disfigure-options.cli b/bpkg/pkg-disfigure-options.cli
index 2fe045e..0f6c45c 100644
--- a/bpkg/pkg-disfigure-options.cli
+++ b/bpkg/pkg-disfigure-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-disfigure"
+"\summary=disfigure package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-disfigure <pkg> [<ver>]"
diff --git a/bpkg/pkg-fetch-options.cli b/bpkg/pkg-fetch-options.cli
index a064da5..441d63e 100644
--- a/bpkg/pkg-fetch-options.cli
+++ b/bpkg/pkg-fetch-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-fetch"
+"\summary=fetch package archive"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-fetch [<options>] (<pkg>/<ver>)|(-e <file>)"
diff --git a/bpkg/pkg-purge-options.cli b/bpkg/pkg-purge-options.cli
index a4d7633..8b54124 100644
--- a/bpkg/pkg-purge-options.cli
+++ b/bpkg/pkg-purge-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-purge"
+"\summary=purge package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-purge [<options>] <pkg>"
diff --git a/bpkg/pkg-status-options.cli b/bpkg/pkg-status-options.cli
index dbc040a..c3ea3d6 100644
--- a/bpkg/pkg-status-options.cli
+++ b/bpkg/pkg-status-options.cli
@@ -8,10 +8,6 @@ include <bpkg/configuration-options.cli>;
 "\name=bpkg-pkg-status"
 "\summary=print package status"
 
-"\project=bpkg"          //@@ command line
-"\version=0.1.0"         //@@ command line
-"\date=12 November 2015" //@@ command line; release date
-
 {
 "<options> <pkg> <ver>",
 
diff --git a/bpkg/pkg-unpack-options.cli b/bpkg/pkg-unpack-options.cli
index 97386a1..41928f6 100644
--- a/bpkg/pkg-unpack-options.cli
+++ b/bpkg/pkg-unpack-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-unpack"
+"\summary=unpack package archive"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-unpack [<options>] <pkg>|(-e <dir>)"
diff --git a/bpkg/pkg-update-options.cli b/bpkg/pkg-update-options.cli
index 8ad9c02..a395041 100644
--- a/bpkg/pkg-update-options.cli
+++ b/bpkg/pkg-update-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-update"
+"\summary=update package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-update <pkg>"
diff --git a/bpkg/pkg-verify-options.cli b/bpkg/pkg-verify-options.cli
index cffdb00..d430330 100644
--- a/bpkg/pkg-verify-options.cli
+++ b/bpkg/pkg-verify-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/common-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-pkg-verify"
+"\summary=verify archive is a valid package"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg pkg-verify <archive>"
diff --git a/bpkg/rep-add-options.cli b/bpkg/rep-add-options.cli
index fc6cbf3..e9abf51 100644
--- a/bpkg/rep-add-options.cli
+++ b/bpkg/rep-add-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-rep-add"
+"\summary=add repository to configuration"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg rep-add [<options>] <rep>"
diff --git a/bpkg/rep-create-options.cli b/bpkg/rep-create-options.cli
index c961c05..13c3b3d 100644
--- a/bpkg/rep-create-options.cli
+++ b/bpkg/rep-create-options.cli
@@ -4,6 +4,10 @@
 
 include <bpkg/common-options.cli>;
 
+"\section=1"
+"\name=bpkg-rep-create"
+"\summary=create repository manifest file"
+
 namespace bpkg
 {
   class rep_create_options: common_options
diff --git a/bpkg/rep-fetch-options.cli b/bpkg/rep-fetch-options.cli
index 0cba10d..8cb9ddb 100644
--- a/bpkg/rep-fetch-options.cli
+++ b/bpkg/rep-fetch-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-rep-fetch"
+"\summary=fetch available packages list"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg rep-fetch [<options>]"
diff --git a/bpkg/rep-info-options.cli b/bpkg/rep-info-options.cli
index 6af380f..0a61df1 100644
--- a/bpkg/rep-info-options.cli
+++ b/bpkg/rep-info-options.cli
@@ -4,10 +4,11 @@
 
 include <bpkg/common-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-rep-info"
+"\summary=print information about repository"
 
+/*
 "\h{SYNOPSIS}
 
 bpkg rep-info [<options>] <rep>"