aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-09-10 13:35:40 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-09-10 13:35:40 +0200
commit005a7ca6b0c83e491b84623377862a51ecbdbb24 (patch)
tree36dd02022d0144de8ab2f0f2bd72c1558ad591e6
parent09b1d3ff6e0d0db3210207b94c6106ea647e9318 (diff)
Update argument grouping documentation with multi-argument support
-rw-r--r--bdep/argument-grouping.cli95
1 files changed, 49 insertions, 46 deletions
diff --git a/bdep/argument-grouping.cli b/bdep/argument-grouping.cli
index bd181f1..df32daf 100644
--- a/bdep/argument-grouping.cli
+++ b/bdep/argument-grouping.cli
@@ -7,8 +7,8 @@ include <bdep/common-options.hxx>;
"\name=bdep-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 +20,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 '}+'
+ \
"