From f175735e5c11f056e8f0ac36746f6dbc1eba6539 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 10 Sep 2021 13:36:31 +0200
Subject: Update argument grouping documentation with multi-argument support

---
 bpkg/argument-grouping.cli | 94 ++++++++++++++++++++++++----------------------
 1 file changed, 49 insertions(+), 45 deletions(-)

diff --git a/bpkg/argument-grouping.cli b/bpkg/argument-grouping.cli
index c30a360..573f53d 100644
--- a/bpkg/argument-grouping.cli
+++ b/bpkg/argument-grouping.cli
@@ -7,7 +7,8 @@ include <bpkg/common-options.hxx>;
 "\name=bpkg-argument-grouping"
 "\summary=argument grouping facility"
 
-// NOTE: the grouping documentation was copied from CLI.
+// NOTE: the grouping documentation (indented part) was copied verbatim from
+//       CLI's --generate-group-scanner documentation.
 //
 "
 \h|SYNOPSIS|
@@ -20,48 +21,51 @@ 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 '}+'
-\
-
+     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'
+     \
+
+     The group applies to a single argument only unless multiple arguments
+     are themselves grouped with '\cb{{}' and '\cb{\}}'. For example:
+
+     \
+     { --foo }+ arg1  arg2 +{ --bar }      # 'arg1' with '--foo'
+                                           # 'arg2' with '--bar'
+
+     { --foo }+ { arg1  arg2 } +{ --bar }  # 'arg1' with '--foo' '--bar'
+                                           # 'arg2' with '--foo' '--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 '}+'
+     \
 "
-- 
cgit v1.1