From a2884d0ae08c4c13998570aa0073b05dec82c543 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Sat, 24 Mar 2018 08:35:54 +0200
Subject: Document argument groups

---
 cli/options.cli | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/cli/options.cli b/cli/options.cli
index ca80729..30b45b3 100644
--- a/cli/options.cli
+++ b/cli/options.cli
@@ -76,10 +76,54 @@ class options
 
   bool --generate-group-scanner
   {
-    "Generate the \c{group_scanner} implementation. This scanner supports the
-     notion of argument groups that are only applied to a certain argument.
+    "Generate the \c{group_scanner} implementation. This scanner supports
+     grouping of arguments (usually options) to apply only to a certain
+     argument.
 
-     @@ TODO"
+     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 '}+'
+     \
+     "
   };
 
   bool --suppress-inline
-- 
cgit v1.1