Autogenerated HTML docs for v2.37.3-485-gbe1a0

2 files changed, 121 insertions, 9 deletions

diff --git a/technical/api-parse-options.html b/technical/api-parse-options.html
index 3298585db..8820a402d 100644
--- a/technical/api-parse-options.html
+++ b/technical/api-parse-options.html
@@ -747,7 +747,8 @@ and to provide a usage help with consistent look.</p></div>
 <h2 id="_basics">Basics</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>The argument vector <code>argv[]</code> may usually contain mandatory or optional

-<em>non-option arguments</em>, e.g. a filename or a branch, and <em>options</em>.

+<em>non-option arguments</em>, e.g. a filename or a branch, <em>options</em>, and

+<em>subcommands</em>.

 Options are optional arguments that start with a dash and

 that allow to change the behavior of a command.</p></div>

 <div class="ulist"><ul>

@@ -813,6 +814,53 @@ Options and non-option arguments can clearly be separated using the <code>--</co
 </p>

 </li>

 </ul></div>

+<div class="paragraph"><p>Subcommands are special in a couple of ways:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+Subcommands only have long form, and they have no double dash prefix, no

+  negated form, and no description, and they don&#8217;t take any arguments, and

+  can&#8217;t be abbreviated.

+</p>

+</li>

+<li>

+<p>

+There must be exactly one subcommand among the arguments, or zero if the

+  command has a default operation mode.

+</p>

+</li>

+<li>

+<p>

+All arguments following the subcommand are considered to be arguments of

+  the subcommand, and, conversely, arguments meant for the subcommand may

+  not preceed the subcommand.

+</p>

+</li>

+</ul></div>

+<div class="paragraph"><p>Therefore, if the options array contains at least one subcommand and

+<code>parse_options()</code> encounters the first dashless argument, it will either:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+stop and return, if that dashless argument is a known subcommand, setting

+  <code>value</code> to the function pointer associated with that subcommand, storing

+  the name of the subcommand in argv[0], and leaving the rest of the

+  arguments unprocessed, or

+</p>

+</li>

+<li>

+<p>

+stop and return, if it was invoked with the <code>PARSE_OPT_SUBCOMMAND_OPTIONAL</code>

+  flag and that dashless argument doesn&#8217;t match any subcommands, leaving

+  <code>value</code> unchanged and the rest of the arguments unprocessed, or

+</p>

+</li>

+<li>

+<p>

+show error and usage, and abort.

+</p>

+</li>

+</ul></div>

 </div>

 </div>

 <div class="sect1">

@@ -885,11 +933,11 @@ before the full parser, which in turn shows the full help message.</p></div>
 </p>

 </dd>

 <dt class="hdlist1">

-<code>PARSE_OPT_KEEP_UNKNOWN</code>

+<code>PARSE_OPT_KEEP_UNKNOWN_OPT</code>

 </dt>

 <dd>

 <p>

-        Keep unknown arguments instead of erroring out.  This doesn&#8217;t

+        Keep unknown options instead of erroring out.  This doesn&#8217;t

         work for all combinations of arguments as users might expect

         it to do.  E.g. if the first argument in <code>--unknown --known</code>

         takes a value (which we can&#8217;t know), the second one is

@@ -899,6 +947,8 @@ before the full parser, which in turn shows the full help message.</p></div>
         non-option, not as a value belonging to the unknown option,

         the parser early.  That&#8217;s why parse_options() errors out if

         both options are set.

+        Note that non-option arguments are always kept, even without

+        this flag.

 </p>

 </dd>

 <dt class="hdlist1">

@@ -912,9 +962,20 @@ before the full parser, which in turn shows the full help message.</p></div>
         options, or to just leave them unknown.

 </p>

 </dd>

+<dt class="hdlist1">

+<code>PARSE_OPT_SUBCOMMAND_OPTIONAL</code>

+</dt>

+<dd>

+<p>

+        Don&#8217;t error out when no subcommand is specified.

+</p>

+</dd>

 </dl></div>

 </li>

 </ol></div>

+<div class="paragraph"><p>Note that <code>PARSE_OPT_STOP_AT_NON_OPTION</code> is incompatible with subcommands;

+while <code>PARSE_OPT_KEEP_DASHDASH</code> and <code>PARSE_OPT_KEEP_UNKNOWN_OPT</code> can only be

+used with subcommands when combined with <code>PARSE_OPT_SUBCOMMAND_OPTIONAL</code>.</p></div>

 </div>

 </div>

 <div class="sect1">

@@ -1169,9 +1230,19 @@ There are some macros to easily define options:</p></div>
 <p>

         Define an "operation mode" option, only one of which in the same

         group of "operating mode" options that share the same <code>int_var</code>

-        can be given by the user. <code>enum_val</code> is set to <code>int_var</code> when the

+        can be given by the user. <code>int_var</code> is set to <code>enum_val</code> when the

         option is used, but an error is reported if other "operating mode"

         option has already set its value to the same <code>int_var</code>.

+        In new commands consider using subcommands instead.

+</p>

+</dd>

+<dt class="hdlist1">

+<code>OPT_SUBCOMMAND(long, &amp;fn_ptr, subcommand_fn)</code>

+</dt>

+<dd>

+<p>

+        Define a subcommand.  <code>subcommand_fn</code> is put into <code>fn_ptr</code> when

+        this subcommand is used.

 </p>

 </dd>

 </dl></div>

@@ -1280,7 +1351,7 @@ for real-world examples.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-09-23 14:33:59 PDT

+ 2022-09-01 13:55:22 PDT

 </div>

 </div>

 </body>

diff --git a/technical/api-parse-options.txt b/technical/api-parse-options.txt
index acfd5dc1d..c2a5e4291 100644
--- a/technical/api-parse-options.txt
+++ b/technical/api-parse-options.txt
@@ -8,7 +8,8 @@ Basics
 ------
 
 The argument vector `argv[]` may usually contain mandatory or optional
-'non-option arguments', e.g. a filename or a branch, and 'options'.
+'non-option arguments', e.g. a filename or a branch, 'options', and
+'subcommands'.
 Options are optional arguments that start with a dash and
 that allow to change the behavior of a command.
 
@@ -48,6 +49,33 @@ The parse-options API allows:
   option, e.g. `-a -b --option -- --this-is-a-file` indicates that
   `--this-is-a-file` must not be processed as an option.
 
+Subcommands are special in a couple of ways:
+
+* Subcommands only have long form, and they have no double dash prefix, no
+  negated form, and no description, and they don't take any arguments, and
+  can't be abbreviated.
+
+* There must be exactly one subcommand among the arguments, or zero if the
+  command has a default operation mode.
+
+* All arguments following the subcommand are considered to be arguments of
+  the subcommand, and, conversely, arguments meant for the subcommand may
+  not preceed the subcommand.
+
+Therefore, if the options array contains at least one subcommand and
+`parse_options()` encounters the first dashless argument, it will either:
+
+* stop and return, if that dashless argument is a known subcommand, setting
+  `value` to the function pointer associated with that subcommand, storing
+  the name of the subcommand in argv[0], and leaving the rest of the
+  arguments unprocessed, or
+
+* stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL`
+  flag and that dashless argument doesn't match any subcommands, leaving
+  `value` unchanged and the rest of the arguments unprocessed, or
+
+* show error and usage, and abort.
+
 Steps to parse options
 ----------------------
 
@@ -90,8 +118,8 @@ Flags are the bitwise-or of:
 	Keep the first argument, which contains the program name.  It's
 	removed from argv[] by default.
 
-`PARSE_OPT_KEEP_UNKNOWN`::
-	Keep unknown arguments instead of erroring out.  This doesn't
+`PARSE_OPT_KEEP_UNKNOWN_OPT`::
+	Keep unknown options instead of erroring out.  This doesn't
 	work for all combinations of arguments as users might expect
 	it to do.  E.g. if the first argument in `--unknown --known`
 	takes a value (which we can't know), the second one is
@@ -101,6 +129,8 @@ Flags are the bitwise-or of:
 	non-option, not as a value belonging to the unknown option,
 	the parser early.  That's why parse_options() errors out if
 	both options are set.
+	Note that non-option arguments are always kept, even without
+	this flag.
 
 `PARSE_OPT_NO_INTERNAL_HELP`::
 	By default, parse_options() handles `-h`, `--help` and
@@ -108,6 +138,13 @@ Flags are the bitwise-or of:
 	turns it off and allows one to add custom handlers for these
 	options, or to just leave them unknown.
 
+`PARSE_OPT_SUBCOMMAND_OPTIONAL`::
+	Don't error out when no subcommand is specified.
+
+Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands;
+while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be
+used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`.
+
 Data Structure
 --------------
 
@@ -236,10 +273,14 @@ There are some macros to easily define options:
 `OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
 	Define an "operation mode" option, only one of which in the same
 	group of "operating mode" options that share the same `int_var`
-	can be given by the user. `enum_val` is set to `int_var` when the
+	can be given by the user. `int_var` is set to `enum_val` when the
 	option is used, but an error is reported if other "operating mode"
 	option has already set its value to the same `int_var`.
+	In new commands consider using subcommands instead.
 
+`OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::
+	Define a subcommand.  `subcommand_fn` is put into `fn_ptr` when
+	this subcommand is used.
 
 The last element of the array must be `OPT_END()`.