aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-09-10 13:36:31 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-09-10 13:36:31 +0200
commitf175735e5c11f056e8f0ac36746f6dbc1eba6539 (patch)
treece369c438bab52b272dc8401618b653c65daf360
parentf7a31c6a617c043171df737d4246c50c1f7286f3 (diff)
Update argument grouping documentation with multi-argument support
-rw-r--r--bpkg/argument-grouping.cli94
1 files 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 '}+'
+ \
"