Improve cfg-create documentation

1 files changed, 26 insertions, 12 deletions

diff --git a/bpkg/cfg-create-options.cli b/bpkg/cfg-create-options.cli
index 4ff0973..25bdd7a 100644
--- a/bpkg/cfg-create-options.cli
+++ b/bpkg/cfg-create-options.cli
@@ -8,24 +8,38 @@ include <bpkg/common-options.cli>;
 "\name=bpkg-cfg-create"
 "\summary=create configuration"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <module> <conf-var>",
 
-bpkg cfg-create [<options>] [(<module>|<conf-var>)...]"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg cfg-create} [<options>] [(<module> | <conf-var>)...]}
 
-The \cb{cfg-create} command creates a new \cb{bpkg} configuration with
-the specified \cb{build2} modules and configuration variables. Unless
-the \cb{--wipe} option is specified, \cb{cfg-create} expects the
-configuration directory to not exist (in which case it will be created)
-or to be empty."
-*/
+     \h|DESCRIPTION|
+
+     The \cb{cfg-create} command creates a new \cb{bpkg} configuration with
+     the specified \cb{build2} modules and configuration variables. Unless
+     the \cb{--wipe} option is specified, \cb{cfg-create} expects the
+     configuration directory to be empty or to not exist (in which case it
+     will be created).
+
+     By default the resulting configuration only loads the \cb{config} and
+     \cb{install} modules. However, additional modules and, if required,
+     their configuration variables can be specified as the \cb{cfg-create}
+     arguments. For example:
+
+     \
+     bpkg cfg-create cxx config.cxx=clang++ config.install.root=/usr/local
+     \
+     "
+  }
 
-namespace bpkg
-{
   class cfg_create_options: common_options
   {
+    "\h|CFG-CREATE OPTIONS|"
+
     dir_path --directory|-d (".")
     {
       "<dir>",