diff options
| -rw-r--r-- | bpkg/argument-grouping.cli | 94 |
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 '}+' + \ " |