Add bpkg-argument-grouping(1) help topic

7 files changed, 85 insertions, 6 deletions

diff --git a/bpkg/.gitignore b/bpkg/.gitignore
index 007b999..ebdc8f6 100644
--- a/bpkg/.gitignore
+++ b/bpkg/.gitignore
@@ -3,4 +3,5 @@ bpkg
 *-odb.?xx
 repository-signing.?xx
 repository-types.?xx
+argument-grouping.?xx
 version.hxx
diff --git a/bpkg/argument-grouping.cli b/bpkg/argument-grouping.cli
new file mode 100644
index 0000000..459f320
--- /dev/null
+++ b/bpkg/argument-grouping.cli
@@ -0,0 +1,68 @@
+// file      : bpkg/argument-grouping.cli
+// copyright : Copyright (c) 2014-2018 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bpkg/common-options.hxx>;
+
+"\section=1"
+"\name=bpkg-argument-grouping"
+"\summary=argument grouping facility"
+
+// NOTE: the grouping documentation was copied from CLI.
+//
+"
+\h|SYNOPSIS|
+
+\c{\b{bpkg} \b{{} \i{options} \b{\}+} \i{argument} \b{+{} \i{options} \b{\}}}
+
+\h|DESCRIPTION|
+
+For certain commands certain options and command line variables can be grouped
+to only apply to specific arguments. This help topic describes the argument
+grouping facility used for this purpose.
+
+Groups can be specified before (leading) and/or after (trailing) the argument
+they apply to. A leading group starts with '\cb{{}' and ends with '\cb{\}+}'
+while a trailing group starts with '\cb{+{}' and ends with '\cb{\}}'. For
+example:
+
+\
+{ --foo --bar }+ arg   # 'arg' with '--foo' '--bar'
+arg +{ fox=1 baz=2 }   # 'arg' with 'fox=1' 'baz=2'
+\
+
+Multiple leading and/or trailing groups can be specified for the same
+argument. For example:
+
+\
+{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'
+\
+
+Note that the group applies to a single argument only. For example:
+
+\
+{ --foo }+ arg1  arg2 +{ --bar }  # 'arg1' with '--foo' and
+                                  # 'arg2' with '--bar'
+\
+
+The group separators ('\cb{{}', '\cb{\}+'}, etc) must be separate command line
+arguments. In particular, they must not be adjacent either to the arguments
+inside the group nor to the argument they apply to. All such cases will be
+treated as ordinary arguments. For example:
+
+\
+{--foo}+ arg   # '{--foo}+' ...
+arg+{ --foo }  # 'arg+{' ...
+\
+
+If one of the group separators needs to be specified as an argument verbatim,
+then it must be escaped with '\cb{\\}'. For example:
+
+\
+}             # error: unexpected group separator
+}x            # '}x'
+\}            # '}'
+{ \}+ }+ arg  # 'arg' with '}+'
+\
+
+"
diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli
index ed8ed0d..22898c1 100644
--- a/bpkg/bpkg.cli
+++ b/bpkg/bpkg.cli
@@ -295,6 +295,11 @@ namespace bpkg
     {
       "\l{bpkg-repository-signing(1)} \- how to sign repository"
     }
+
+    bool argument-grouping
+    {
+      "\l{bpkg-argument-grouping(1)} \- argument grouping facility"
+    }
   };
 
   class options: common_options
diff --git a/bpkg/buildfile b/bpkg/buildfile
index 8355f49..5c3ba35 100644
--- a/bpkg/buildfile
+++ b/bpkg/buildfile
@@ -42,7 +42,7 @@ rep-info-options           \
 rep-list-options           \
 rep-remove-options
 
-help_topics = repository-signing repository-types
+help_topics = repository-signing repository-types argument-grouping
 
 exe{bpkg}:                                                                 \
   {hxx ixx txx cxx}{** -{$options_topics} -{$help_topics} -*-odb -version} \
@@ -112,7 +112,8 @@ if $cli.configured
   # Help topics.
   #
   cli.cxx{repository-signing}: cli{repository-signing}
-  cli.cxx{repository-types}: cli{repository-types}
+  cli.cxx{repository-types}:   cli{repository-types}
+  cli.cxx{argument-grouping}:  cli{argument-grouping}
 
   # Option length must be the same to get commands/topics/options aligned.
   #
@@ -133,8 +134,8 @@ bpkg::pkg_build_pkg_options=exclude-base --generate-modifier
 
   # Avoid generating CLI runtime and empty inline file for help topics.
   #
-  cli.cxx{repository-signing repository-types}: cli.options += --suppress-cli \
---suppress-inline
+  cli.cxx{repository-signing repository-types argument-grouping}: \
+    cli.options += --suppress-cli --suppress-inline
 
   # Include the generated cli files into the distribution and don't remove
   # them when cleaning in src (so that clean results in a state identical to
diff --git a/bpkg/help.cxx b/bpkg/help.cxx
index 2584f16..a5b6414 100644
--- a/bpkg/help.cxx
+++ b/bpkg/help.cxx
@@ -13,6 +13,7 @@
 //
 #include <bpkg/repository-signing.hxx>
 #include <bpkg/repository-types.hxx>
+#include <bpkg/argument-grouping.hxx>
 
 using namespace std;
 using namespace butl;
@@ -35,6 +36,8 @@ namespace bpkg
         usage = &print_bpkg_repository_signing_usage;
       else if (t == "repository-types")
         usage = &print_bpkg_repository_types_usage;
+      else if (t == "argument-grouping")
+        usage = &print_bpkg_argument_grouping_usage;
       else
         fail << "unknown bpkg command/help topic '" << t << "'" <<
           info << "run 'bpkg help' for more information";
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli
index 6bb4ce2..a1a79de 100644
--- a/bpkg/pkg-build.cli
+++ b/bpkg/pkg-build.cli
@@ -147,7 +147,7 @@ namespace bpkg
 
      The following options can be grouped to apply to a specific \ci{pkg-spec}
      as well as specified globally, in which case they apply to all the
-     specified packages."
+     specified packages (see \l{bpkg-argument-grouping(1)} for details)."
 
     // NOTE: if adding a new option here, don't forget to also update
     //       {validate,merge,compare,print}_options() in pkg-build.cxx!
diff --git a/doc/cli.sh b/doc/cli.sh
index f04da12..e37d80c 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -64,7 +64,8 @@ compile "pkg-build" $o --class-doc  bpkg::pkg_build_pkg_options=exclude-base
 pages="cfg-create help pkg-clean pkg-configure pkg-disfigure \
 pkg-drop pkg-fetch pkg-checkout pkg-install pkg-purge pkg-status pkg-test \
 pkg-uninstall pkg-unpack pkg-update pkg-verify rep-add rep-remove rep-list \
-rep-create rep-fetch rep-info repository-signing repository-types"
+rep-create rep-fetch rep-info repository-signing repository-types \
+argument-grouping"
 
 for p in $pages; do
   compile $p $o