Update build command documentation

1 files changed, 27 insertions, 18 deletions

diff --git a/bpkg/build-options.cli b/bpkg/build-options.cli
index b03f1ee..300afa1 100644
--- a/bpkg/build-options.cli
+++ b/bpkg/build-options.cli
@@ -4,35 +4,44 @@
 
 include <bpkg/configuration-options.cli>;
 
-/*
 "\section=1"
 "\name=bpkg-build"
+"\summary=build one or more packages"
 
-"\h{SYNOPSIS}
+"\project=bpkg"          //@@ command line
+"\version=0.1.0"         //@@ command line
+"\date=12 November 2015" //@@ command line; release date
 
-bpkg build [<options>] (<pkg>[/<ver>]|<file>|<dir>)..."
+{
+"<options> <pkg> <ver> <file> <dir>",
+
+"\h|SYNOPSIS|
+
+\c{\b{bpkg build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...}
 
-"\h{DESCRIPTION}
+\h|DESCRIPTION|
 
 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 \cb{rep-add} and \cb{rep-fetch}). Alternatively,
-the package can be specified as either the path to the package
-source archive (<file>) or package source directory (<dir>). See
-\cb{pkg-fetch} and \cb{pkg-unpack} for more information on the
-semantics of specifying the package as an archive or directory.
+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.
 
 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>) as well as an archive or directory, will, in addition, have
-their versions \i{held}, that is, they will not be automatically upgraded.
+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 also supports several \cb{--*-only} options
-that allow you to limit the amount of work that will be done.
-*/
+The \cb{build} command also supports several \cb{--*-only} options that allow
+you to limit the amount of work that will be done.
+
+\h|OPTIONS|"
+}
 
 namespace bpkg
 {
@@ -45,7 +54,7 @@ namespace bpkg
 
     bool --configure-only|-c
     {
-      "Configuring all the packages but don't update."
+      "Configure all the packages but don't update."
     };
 
     bool --print-only|-p