Merge branch 'da/mergetool-lib'

diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 539863b1f920f8f34ad9272907cbacbd35a7fcbd..b43458eae6787caab163fadab113dff61e577498 100644 (file)
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -66,6 +66,12 @@ Steps to parse options
 non-option arguments in `argv[]`.
 `argc` is updated appropriately because of the assignment.
 +
+You can also pass NULL instead of a usage array as fourth parameter of
+parse_options(), to avoid displaying a help screen with usage info and
+option list.  This should only be done if necessary, e.g. to implement
+a limited parser for only a subset of the options that needs to be run
+before the full parser, which in turn shows the full help message.
++
 Flags are the bitwise-or of:
 
 `PARSE_OPT_KEEP_DASHDASH`::
@@ -77,6 +83,28 @@ Flags are the bitwise-or of:
        Using this flag, processing is stopped at the first non-option
        argument.
 
+`PARSE_OPT_KEEP_ARGV0`::
+       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
+       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
+       mistakenly interpreted as a known option.  Similarly, if
+       `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
+       `--unknown value` will be mistakenly interpreted as a
+       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.
+
+`PARSE_OPT_NO_INTERNAL_HELP`::
+       By default, parse_options() handles `-h`, `--help` and
+       `--help-all` internally, by showing a help screen.  This option
+       turns it off and allows one to add custom handlers for these
+       options, or to just leave them unknown.
+
 Data Structure
 --------------
 
@@ -109,6 +137,10 @@ There are some macros to easily define options:
        Introduce a boolean option.
        If used, `int_var` is bitwise-ored with `mask`.
 
+`OPT_NEGBIT(short, long, &int_var, description, mask)`::
+       Introduce a boolean option.
+       If used, `int_var` is bitwise-anded with the inverted `mask`.
+
 `OPT_SET_INT(short, long, &int_var, description, integer)`::
        Introduce a boolean option.
        If used, set `int_var` to `integer`.
@@ -138,6 +170,14 @@ There are some macros to easily define options:
 `OPT_ARGUMENT(long, description)`::
        Introduce a long-option argument that will be kept in `argv[]`.
 
+`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
+       Recognize numerical options like -123 and feed the integer as
+       if it was an argument to the function given by `func_ptr`.
+       The result will be put into `var`.  There can be only one such
+       option definition.  It cannot be negated and it takes no
+       arguments.  Short options that happen to be digits take
+       precedence over it.
+
 
 The last element of the array must be `OPT_END()`.
 
@@ -170,7 +210,7 @@ The function must be defined in this form:
 
 The callback mechanism is as follows:
 
-* Inside `funct`, the only interesting member of the structure
+* Inside `func`, the only interesting member of the structure
   given by `opt` is the void pointer `opt->value`.
   `\*opt->value` will be the value that is saved into `var`, if you
   use `OPT_CALLBACK()`.