Prepare for radical source tree reorganization. zack/build-layout-experiment

All top-level files and directories are moved into a temporary storage
directory, REORG.TODO, except for files that will certainly still
exist in their current form at top level when we're done (COPYING,
COPYING.LIB, LICENSES, NEWS, README), all old ChangeLog files (which
are moved to the new directory OldChangeLogs, instead), and the
generated file INSTALL (which is just deleted; in the new order, there
will be no generated files checked into version control).

1 files changed, 1349 insertions, 0 deletions

diff --git a/REORG.TODO/manual/argp.texi b/REORG.TODO/manual/argp.texi
new file mode 100644
index 0000000000..bca3ca5ed9
--- /dev/null
+++ b/REORG.TODO/manual/argp.texi
@@ -0,0 +1,1349 @@
+@node Argp, Suboptions, Getopt, Parsing Program Arguments
+@need 5000
+@section Parsing Program Options with Argp
+@cindex argp (program argument parser)
+@cindex argument parsing with argp
+@cindex option parsing with argp
+
+@dfn{Argp} is an interface for parsing unix-style argument vectors.
+@xref{Program Arguments}.
+
+Argp provides features unavailable in the more commonly used
+@code{getopt} interface.  These features include automatically producing
+output in response to the @samp{--help} and @samp{--version} options, as
+described in the GNU coding standards.  Using argp makes it less likely
+that programmers will neglect to implement these additional options or
+keep them up to date.
+
+Argp also provides the ability to merge several independently defined
+option parsers into one, mediating conflicts between them and making the
+result appear seamless.  A library can export an argp option parser that
+user programs might employ in conjunction with their own option parsers,
+resulting in less work for the user programs.  Some programs may use only
+argument parsers exported by libraries, thereby achieving consistent and
+efficient option-parsing for abstractions implemented by the libraries.
+
+@pindex argp.h
+The header file @file{<argp.h>} should be included to use argp.
+
+@subsection The @code{argp_parse} Function
+
+The main interface to argp is the @code{argp_parse} function.  In many
+cases, calling @code{argp_parse} is the only argument-parsing code
+needed in @code{main}.
+@xref{Program Arguments}.
+
+@comment argp.h
+@comment GNU
+@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}}
+@c Optionally alloca()tes standard help options, initializes the parser,
+@c then parses individual args in a loop, and then finalizes.
+@c  parser_init
+@c   calc_sizes ok
+@c    option_is_end ok
+@c   malloc @ascuheap @acsmem
+@c   parser_convert @mtslocale
+@c    convert_options @mtslocale
+@c     option_is_end ok
+@c     option_is_short ok
+@c      isprint, but locale may change within the loop
+@c     find_long_option ok
+@c   group_parse
+@c    group->parser (from argp->parser)
+@c  parser_parse_next
+@c   getopt_long(_only)_r many issues, same as non_r minus @mtasurace
+@c   parser_parse_arg
+@c    group_parse dup
+@c   parser_parse_opt
+@c    group_parse dup
+@c    argp_error dup @mtasurace:argpbuf @mtsenv @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c    dgettext (bad key error) dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c  parser_finalize
+@c   group_parse
+@c   fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem]
+@c   dgettext dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem
+@c   arg_state_help
+@c   free dup @ascuhelp @acsmem
+The @code{argp_parse} function parses the arguments in @var{argv}, of
+length @var{argc}, using the argp parser @var{argp}.  @xref{Argp
+Parsers}.  Passing a null pointer for @var{argp} is the same as using
+a @code{struct argp} containing all zeros.
+
+@var{flags} is a set of flag bits that modify the parsing behavior.
+@xref{Argp Flags}.  @var{input} is passed through to the argp parser
+@var{argp}, and has meaning defined by @var{argp}.  A typical usage is
+to pass a pointer to a structure which is used for specifying
+parameters to the parser and passing back the results.
+
+Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
+in @var{flags}, calling @code{argp_parse} may result in the program
+exiting.  This behavior is true if an error is detected, or when an
+unknown option is encountered.  @xref{Program Termination}.
+
+If @var{arg_index} is non-null, the index of the first unparsed option
+in @var{argv} is returned as a value.
+
+The return value is zero for successful parsing, or an error code
+(@pxref{Error Codes}) if an error is detected.  Different argp parsers
+may return arbitrary error codes, but the standard error codes are:
+@code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if
+an unknown option or option argument is encountered.
+@end deftypefun
+
+@menu
+* Globals: Argp Global Variables.  Global argp parameters.
+* Parsers: Argp Parsers.        Defining parsers for use with @code{argp_parse}.
+* Flags: Argp Flags.            Flags that modify the behavior of @code{argp_parse}.
+* Help: Argp Help.              Printing help messages when not parsing.
+* Examples: Argp Examples.      Simple examples of programs using argp.
+* Customization: Argp User Customization.
+                                Users may control the @samp{--help} output format.
+@end menu
+
+@node Argp Global Variables, Argp Parsers, , Argp
+@subsection Argp Global Variables
+
+These variables make it easy for user programs to implement the
+@samp{--version} option and provide a bug-reporting address in the
+@samp{--help} output.  These are implemented in argp by default.
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_version
+If defined or set by the user program to a non-zero value, then a
+@samp{--version} option is added when parsing with @code{argp_parse},
+which will print the @samp{--version} string followed by a newline and
+exit.  The exception to this is if the @code{ARGP_NO_EXIT} flag is used.
+@end deftypevar
+
+@comment argp.h
+@comment GNU
+@deftypevar {const char *} argp_program_bug_address
+If defined or set by the user program to a non-zero value,
+@code{argp_program_bug_address} should point to a string that will be
+printed at the end of the standard output for the @samp{--help} option,
+embedded in a sentence that says @samp{Report bugs to @var{address}.}.
+@end deftypevar
+
+@need 1500
+@comment argp.h
+@comment GNU
+@defvar argp_program_version_hook
+If defined or set by the user program to a non-zero value, a
+@samp{--version} option is added when parsing with @code{arg_parse},
+which prints the program version and exits with a status of zero.  This
+is not the case if the @code{ARGP_NO_HELP} flag is used.  If the
+@code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is
+suppressed or modified, as when the argp parser is going to be used by
+other programs.
+
+It should point to a function with this type of signature:
+
+@smallexample
+void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+@xref{Argp Parsing State}, for an explanation of @var{state}.
+
+This variable takes precedence over @code{argp_program_version}, and is
+useful if a program has version information not easily expressed in a
+simple string.
+@end defvar
+
+@comment argp.h
+@comment GNU
+@deftypevar error_t argp_err_exit_status
+This is the exit status used when argp exits due to a parsing error.  If
+not defined or set by the user program, this defaults to:
+@code{EX_USAGE} from @file{<sysexits.h>}.
+@end deftypevar
+
+@node Argp Parsers, Argp Flags, Argp Global Variables, Argp
+@subsection Specifying Argp Parsers
+
+The first argument to the @code{argp_parse} function is a pointer to a
+@code{struct argp}, which is known as an @dfn{argp parser}:
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp}
+This structure specifies how to parse a given set of options and
+arguments, perhaps in conjunction with other argp parsers.  It has the
+following fields:
+
+@table @code
+@item const struct argp_option *options
+A pointer to a vector of @code{argp_option} structures specifying which
+options this argp parser understands; it may be zero if there are no
+options at all.  @xref{Argp Option Vectors}.
+
+@item argp_parser_t parser
+A pointer to a function that defines actions for this parser; it is
+called for each option parsed, and at other well-defined points in the
+parsing process.  A value of zero is the same as a pointer to a function
+that always returns @code{ARGP_ERR_UNKNOWN}.  @xref{Argp Parser
+Functions}.
+
+@item const char *args_doc
+If non-zero, a string describing what non-option arguments are called by
+this parser.  This is only used to print the @samp{Usage:} message.  If
+it contains newlines, the strings separated by them are considered
+alternative usage patterns and printed on separate lines.  Lines after
+the first are prefixed by @samp{ or: } instead of @samp{Usage:}.
+
+@item const char *doc
+If non-zero, a string containing extra text to be printed before and
+after the options in a long help message, with the two sections
+separated by a vertical tab (@code{'\v'}, @code{'\013'}) character.  By
+convention, the documentation before the options is just a short string
+explaining what the program does.  Documentation printed after the
+options describe behavior in more detail.
+
+@item const struct argp_child *children
+A pointer to a vector of @code{argp_child} structures.  This pointer
+specifies which additional argp parsers should be combined with this
+one.  @xref{Argp Children}.
+
+@item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
+If non-zero, a pointer to a function that filters the output of help
+messages.  @xref{Argp Help Filtering}.
+
+@item const char *argp_domain
+If non-zero, the strings used in the argp library are translated using
+the domain described by this string.  If zero, the current default domain
+is used.
+
+@end table
+@end deftp
+
+Of the above group, @code{options}, @code{parser}, @code{args_doc}, and
+the @code{doc} fields are usually all that are needed.  If an argp
+parser is defined as an initialized C variable, only the fields used
+need be specified in the initializer.  The rest will default to zero due
+to the way C structure initialization works.  This design is exploited in
+most argp structures; the most-used fields are grouped near the
+beginning, the unused fields left unspecified.
+
+@menu
+* Options: Argp Option Vectors.   Specifying options in an argp parser.
+* Argp Parser Functions::         Defining actions for an argp parser.
+* Children: Argp Children.        Combining multiple argp parsers.
+* Help Filtering: Argp Help Filtering.  Customizing help output for an argp parser.
+@end menu
+
+@node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
+@subsection Specifying Options in an Argp Parser
+
+The @code{options} field in a @code{struct argp} points to a vector of
+@code{struct argp_option} structures, each of which specifies an option
+that the argp parser supports.  Multiple entries may be used for a single
+option provided it has multiple names.  This should be terminated by an
+entry with zero in all fields.  Note that when using an initialized C
+array for options, writing @code{@{ 0 @}} is enough to achieve this.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_option}
+This structure specifies a single option that an argp parser
+understands, as well as how to parse and document that option.  It has
+the following fields:
+
+@table @code
+@item const char *name
+The long name for this option, corresponding to the long option
+@samp{--@var{name}}; this field may be zero if this option @emph{only}
+has a short name.  To specify multiple names for an option, additional
+entries may follow this one, with the @code{OPTION_ALIAS} flag
+set.  @xref{Argp Option Flags}.
+
+@item int key
+The integer key provided by the current option to the option parser.  If
+@var{key} has a value that is a printable @sc{ascii} character (i.e.,
+@code{isascii (@var{key})} is true), it @emph{also} specifies a short
+option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character
+with the code @var{key}.
+
+@item const char *arg
+If non-zero, this is the name of an argument associated with this
+option, which must be provided (e.g., with the
+@samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
+syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp
+Option Flags}) is set, in which case it @emph{may} be provided.
+
+@item int flags
+Flags associated with this option, some of which are referred to above.
+@xref{Argp Option Flags}.
+
+@item const char *doc
+A documentation string for this option, for printing in help messages.
+
+If both the @code{name} and @code{key} fields are zero, this string
+will be printed tabbed left from the normal option column, making it
+useful as a group header.  This will be the first thing printed in its
+group.  In this usage, it's conventional to end the string with a
+@samp{:} character.
+
+@item int group
+Group identity for this option.
+
+In a long help message, options are sorted alphabetically within each
+group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
+@minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.
+
+Every entry in an options array with this field 0 will inherit the group
+number of the previous entry, or zero if it's the first one.  If it's a
+group header with @code{name} and @code{key} fields both zero, the
+previous entry + 1 is the default.  Automagic options such as
+@samp{--help} are put into group @minus{}1.
+
+Note that because of C structure initialization rules, this field often
+need not be specified, because 0 is the correct value.
+@end table
+@end deftp
+
+
+@menu
+* Flags: Argp Option Flags.     Flags for options.
+@end menu
+
+@node Argp Option Flags, , , Argp Option Vectors
+@subsubsection Flags for Argp Options
+
+The following flags may be or'd together in the @code{flags} field of a
+@code{struct argp_option}.  These flags control various aspects of how
+that option is parsed or displayed in help messages:
+
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item OPTION_ARG_OPTIONAL
+The argument associated with this option is optional.
+
+@comment argp.h
+@comment GNU
+@item OPTION_HIDDEN
+This option isn't displayed in any help messages.
+
+@comment argp.h
+@comment GNU
+@item OPTION_ALIAS
+This option is an alias for the closest previous non-alias option.  This
+means that it will be displayed in the same help entry, and will inherit
+fields other than @code{name} and @code{key} from the option being
+aliased.
+
+
+@comment argp.h
+@comment GNU
+@item OPTION_DOC
+This option isn't actually an option and should be ignored by the actual
+option parser.  It is an arbitrary section of documentation that should
+be displayed in much the same manner as the options.  This is known as a
+@dfn{documentation option}.
+
+If this flag is set, then the option @code{name} field is displayed
+unmodified (e.g., no @samp{--} prefix is added) at the left-margin where
+a @emph{short} option would normally be displayed, and this
+documentation string is left in its usual place.  For purposes of
+sorting, any leading whitespace and punctuation is ignored, unless the
+first non-whitespace character is @samp{-}.  This entry is displayed
+after all options, after @code{OPTION_DOC} entries with a leading
+@samp{-}, in the same group.
+
+@comment argp.h
+@comment GNU
+@item OPTION_NO_USAGE
+This option shouldn't be included in `long' usage messages, but should
+still be included in other help messages.  This is intended for options
+that are completely documented in an argp's @code{args_doc}
+field.  @xref{Argp Parsers}.  Including this option in the generic usage
+list would be redundant, and should be avoided.
+
+For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
+@samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
+should probably be marked @code{OPTION_NO_USAGE}.
+@end vtable
+
+@node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
+@subsection Argp Parser Functions
+
+The function pointed to by the @code{parser} field in a @code{struct
+argp} (@pxref{Argp Parsers}) defines what actions take place in response
+to each option or argument parsed.  It is also used as a hook, allowing a
+parser to perform tasks at certain other points during parsing.
+
+@need 2000
+Argp parser functions have the following type signature:
+
+@cindex argp parser functions
+@smallexample
+error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
+@end smallexample
+
+@noindent
+where the arguments are as follows:
+
+@table @var
+@item key
+For each option that is parsed, @var{parser} is called with a value of
+@var{key} from that option's @code{key} field in the option
+vector.  @xref{Argp Option Vectors}.  @var{parser} is also called at
+other times with special reserved keys, such as @code{ARGP_KEY_ARG} for
+non-option arguments.  @xref{Argp Special Keys}.
+
+@item arg
+If @var{key} is an option, @var{arg} is its given value.  This defaults
+to zero if no value is specified.  Only options that have a non-zero
+@code{arg} field can ever have a value.  These must @emph{always} have a
+value unless the @code{OPTION_ARG_OPTIONAL} flag is specified.  If the
+input being parsed specifies a value for an option that doesn't allow
+one, an error results before @var{parser} ever gets called.
+
+If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option
+argument.  Other special keys always have a zero @var{arg}.
+
+@item state
+@var{state} points to a @code{struct argp_state}, containing useful
+information about the current parsing state for use by
+@var{parser}.  @xref{Argp Parsing State}.
+@end table
+
+When @var{parser} is called, it should perform whatever action is
+appropriate for @var{key}, and return @code{0} for success,
+@code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this
+parser function, or a unix error code if a real error
+occurred.  @xref{Error Codes}.
+
+@comment argp.h
+@comment GNU
+@deftypevr Macro int ARGP_ERR_UNKNOWN
+Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
+@var{key} value they do not recognize, or for non-option arguments
+(@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle.
+@end deftypevr
+
+@need 3000
+A typical parser function uses a switch statement on @var{key}:
+
+@smallexample
+error_t
+parse_opt (int key, char *arg, struct argp_state *state)
+@{
+  switch (key)
+    @{
+    case @var{option_key}:
+      @var{action}
+      break;
+    @dots{}
+    default:
+      return ARGP_ERR_UNKNOWN;
+    @}
+  return 0;
+@}
+@end smallexample
+
+@menu
+* Keys: Argp Special Keys.           Special values for the @var{key} argument.
+* State: Argp Parsing State.         What the @var{state} argument refers to.
+* Functions: Argp Helper Functions.  Functions to help during argp parsing.
+@end menu
+
+@node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
+@subsubsection Special Keys for Argp Parser Functions
+
+In addition to key values corresponding to user options, the @var{key}
+argument to argp parser functions may have a number of other special
+values.  In the following example @var{arg} and @var{state} refer to
+parser function arguments.  @xref{Argp Parser Functions}.
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ARG
+This is not an option at all, but rather a command line argument, whose
+value is pointed to by @var{arg}.
+
+When there are multiple parser functions in play due to argp parsers
+being combined, it's impossible to know which one will handle a specific
+argument.  Each is called until one returns 0 or an error other than
+@code{ARGP_ERR_UNKNOWN}; if an argument is not handled,
+@code{argp_parse} immediately returns success, without parsing any more
+arguments.
+
+Once a parser function returns success for this key, that fact is
+recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be
+used.  @emph{However}, if while processing the argument a parser function
+decrements the @code{next} field of its @var{state} argument, the option
+won't be considered processed; this is to allow you to actually modify
+the argument, perhaps into an option, and have it processed again.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ARGS
+If a parser function returns @code{ARGP_ERR_UNKNOWN} for
+@code{ARGP_KEY_ARG}, it is immediately called again with the key
+@code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
+convenient for consuming all remaining arguments.  @var{arg} is 0, and
+the tail of the argument vector may be found at @code{@var{state}->argv
++ @var{state}->next}.  If success is returned for this key, and
+@code{@var{state}->next} is unchanged, all remaining arguments are
+considered to have been consumed.  Otherwise, the amount by which
+@code{@var{state}->next} has been adjusted indicates how many were used.
+Here's an example that uses both, for different args:
+
+
+@smallexample
+@dots{}
+case ARGP_KEY_ARG:
+  if (@var{state}->arg_num == 0)
+    /* First argument */
+    first_arg = @var{arg};
+  else
+    /* Let the next case parse it.  */
+    return ARGP_KEY_UNKNOWN;
+  break;
+case ARGP_KEY_ARGS:
+  remaining_args = @var{state}->argv + @var{state}->next;
+  num_remaining_args = @var{state}->argc - @var{state}->next;
+  break;
+@end smallexample
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_END
+This indicates that there are no more command line arguments.  Parser
+functions are called in a different order, children first.  This allows
+each parser to clean up its state for the parent.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_NO_ARGS
+Because it's common to do some special processing if there aren't any
+non-option args, parser functions are called with this key if they
+didn't successfully process any non-option arguments.  This is called
+just before @code{ARGP_KEY_END}, where more general validity checks on
+previously parsed arguments take place.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_INIT
+This is passed in before any parsing is done.  Afterwards, the values of
+each element of the @code{child_input} field of @var{state}, if any, are
+copied to each child's state to be the initial value of the @code{input}
+when @emph{their} parsers are called.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_SUCCESS
+Passed in when parsing has successfully been completed, even if
+arguments remain.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ERROR
+Passed in if an error has occurred and parsing is terminated.  In this
+case a call with a key of @code{ARGP_KEY_SUCCESS} is never made.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_FINI
+The final key ever seen by any parser, even after
+@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}.  Any resources
+allocated by @code{ARGP_KEY_INIT} may be freed here.  At times, certain
+resources allocated are to be returned to the caller after a successful
+parse.  In that case, those particular resources can be freed in the
+@code{ARGP_KEY_ERROR} case.
+@end vtable
+
+In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
+functions, and @code{ARGP_KEY_FINI} the last, unless an error was
+returned by the parser for @code{ARGP_KEY_INIT}.  Other keys can occur
+in one the following orders.  @var{opt} refers to an arbitrary option
+key:
+
+@table @asis
+@item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
+The arguments being parsed did not contain any non-option arguments.
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
+All non-option arguments were successfully handled by a parser
+function.  There may be multiple parser functions if multiple argp
+parsers were combined.
+
+@item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
+Some non-option argument went unrecognized.
+
+This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
+for an argument, in which case parsing stops at that argument if
+@var{arg_index} is a null pointer.  Otherwise an error occurs.
+@end table
+
+In all cases, if a non-null value for @var{arg_index} gets passed to
+@code{argp_parse}, the index of the first unparsed command-line argument
+is passed back in that value.
+
+If an error occurs and is either detected by argp or because a parser
+function returned an error value, each parser is called with
+@code{ARGP_KEY_ERROR}.  No further calls are made, except the final call
+with @code{ARGP_KEY_FINI}.
+
+@node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
+@subsubsection Argp Parsing State
+
+The third argument to argp parser functions (@pxref{Argp Parser
+Functions}) is a pointer to a @code{struct argp_state}, which contains
+information about the state of the option parsing.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_state}
+This structure has the following fields, which may be modified as noted:
+
+@table @code
+@item const struct argp *const root_argp
+The top level argp parser being parsed.  Note that this is often
+@emph{not} the same @code{struct argp} passed into @code{argp_parse} by
+the invoking program.  @xref{Argp}.  It is an internal argp parser that
+contains options implemented by @code{argp_parse} itself, such as
+@samp{--help}.
+
+@item int argc
+@itemx char **argv
+The argument vector being parsed.  This may be modified.
+
+@item int next
+The index in @code{argv} of the next argument to be parsed.  This may be
+modified.
+
+One way to consume all remaining arguments in the input is to set
+@code{@var{state}->next = @var{state}->argc}, perhaps after recording
+the value of the @code{next} field to find the consumed arguments.  The
+current option can be re-parsed immediately by decrementing this field,
+then modifying @code{@var{state}->argv[@var{state}->next]} to reflect
+the option that should be reexamined.
+
+@item unsigned flags
+The flags supplied to @code{argp_parse}.  These may be modified, although
+some flags may only take effect when @code{argp_parse} is first
+invoked.  @xref{Argp Flags}.
+
+@item unsigned arg_num
+While calling a parsing function with the @var{key} argument
+@code{ARGP_KEY_ARG}, this represents the number of the current arg,
+starting at 0.  It is incremented after each @code{ARGP_KEY_ARG} call
+returns.  At all other times, this is the number of @code{ARGP_KEY_ARG}
+arguments that have been processed.
+
+@item int quoted
+If non-zero, the index in @code{argv} of the first argument following a
+special @samp{--} argument.  This prevents anything that follows from
+being interpreted as an option.  It is only set after argument parsing
+has proceeded past this point.
+
+@item void *input
+An arbitrary pointer passed in from the caller of @code{argp_parse}, in
+the @var{input} argument.
+
+@item void **child_inputs
+These are values that will be passed to child parsers.  This vector will
+be the same length as the number of children in the current parser.  Each
+child parser will be given the value of
+@code{@var{state}->child_inputs[@var{i}]} as @emph{its}
+@code{@var{state}->input} field, where @var{i} is the index of the child
+in the this parser's @code{children} field.  @xref{Argp Children}.
+
+@item void *hook
+For the parser function's use.  Initialized to 0, but otherwise ignored
+by argp.
+
+@item char *name
+The name used when printing messages.  This is initialized to
+@code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is
+unavailable.
+
+@item FILE *err_stream
+@itemx FILE *out_stream
+The stdio streams used when argp prints.  Error messages are printed to
+@code{err_stream}, all other output, such as @samp{--help} output) to
+@code{out_stream}.  These are initialized to @code{stderr} and
+@code{stdout} respectively.  @xref{Standard Streams}.
+
+@item void *pstate
+Private, for use by the argp implementation.
+@end table
+@end deftp
+
+@node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
+@subsubsection Functions For Use in Argp Parsers
+
+Argp provides a number of functions available to the user of argp
+(@pxref{Argp Parser Functions}), mostly for producing error messages.
+These take as their first argument the @var{state} argument to the
+parser function.  @xref{Argp Parsing State}.
+
+
+@cindex usage messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_usage (const struct argp_state *@var{state})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls argp_state_help with stderr and ARGP_HELP_STD_USAGE.
+Outputs the standard usage message for the argp parser referred to by
+@var{state} to @code{@var{state}->err_stream} and terminates the program
+with @code{exit (argp_err_exit_status)}.  @xref{Argp Global Variables}.
+@end deftypefun
+
+@cindex syntax error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Lock stream, vasprintf the formatted message into a buffer, print the
+@c buffer prefixed by the short program name (in libc,
+@c argp_short_program_name is a macro that expands to
+@c program_invocation_short_name), releases the buffer, then call
+@c argp_state_help with stream and ARGP_HELP_STD_ERR, unlocking the
+@c stream at the end.
+Prints the printf format string @var{fmt} and following args, preceded
+by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
+--help}} message, and terminates the program with an exit status of
+@code{argp_err_exit_status}.  @xref{Argp Global Variables}.
+@end deftypefun
+
+@cindex error messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}}
+@c Lock stream, write out the short program name, vasprintf the optional
+@c formatted message to a buffer, print the buffer prefixed by colon and
+@c blank, release the buffer, call strerror_r with an automatic buffer,
+@c print it out after colon and blank, put[w]c a line break, unlock the
+@c stream, then exit unless ARGP_NO_EXIT.
+Similar to the standard GNU error-reporting function @code{error}, this
+prints the program name and @samp{:}, the printf format string
+@var{fmt}, and the appropriate following args.  If it is non-zero, the
+standard unix error text for @var{errnum} is printed.  If @var{status} is
+non-zero, it terminates the program with that value as its exit status.
+
+The difference between @code{argp_failure} and @code{argp_error} is that
+@code{argp_error} is for @emph{parsing errors}, whereas
+@code{argp_failure} is for other problems that occur during parsing but
+don't reflect a syntactic problem with the input, such as illegal values
+for options, bad phase of the moon, etc.
+@end deftypefun
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls _help with the short program name and optionally exit.
+@c The main problems in _help, besides the usual issues with stream I/O
+@c and translation, are the use of a static buffer (uparams, thus
+@c @mtasurace:argpbuf) that makes the whole thing thread-unsafe, reading
+@c from the environment for ARGP_HELP_FMT, accessing the locale object
+@c multiple times.
+
+@c _help @mtsenv @mtasurace:argpbuf @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c  dgettext @ascuintl
+@c  flockfile @aculock
+@c  funlockfile @aculock
+@c  fill_in_uparams @mtsenv @mtasurace:argpbuf @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem
+@c   argp_failure dup (status = errnum = 0)
+@c   atoi dup @mtslocale
+@c  argp_hol @ascuheap @acsmem
+@c   make_hol @ascuheap @acsmem
+@c   hol_add_cluster @ascuheap @acsmem
+@c   hol_append @ascuheap @acsmem
+@c  hol_set_group ok
+@c   hol_find_entry ok
+@c  hol_sort @mtslocale @acucorrupt
+@c   qsort dup @acucorrupt
+@c    hol_entry_qcmp @mtslocale
+@c     hol_entry_cmp @mtslocale
+@c      group_cmp ok
+@c      hol_cluster_cmp ok
+@c       group_cmp ok
+@c      hol_entry_first_short @mtslocale
+@c       hol_entry_short_iterate [@mtslocale]
+@c        until_short ok
+@c         oshort ok
+@c          isprint ok
+@c      odoc ok
+@c      hol_entry_first_long ok
+@c      canon_doc_option @mtslocale
+@c      tolower dup
+@c  hol_usage @mtslocale @ascuintl @ascuheap @acsmem
+@c   hol_entry_short_iterate ok
+@c    add_argless_short_opt ok
+@c   argp_fmtstream_printf dup
+@c   hol_entry_short_iterate @mtslocale @ascuintl @ascuheap @acsmem
+@c    usage_argful_short_opt @mtslocale @ascuintl @ascuheap @acsmem
+@c     dgettext dup
+@c     argp_fmtstream_printf dup
+@c   hol_entry_long_iterate @mtslocale @ascuintl @ascuheap @acsmem
+@c    usage_long_opt @mtslocale @ascuintl @ascuheap @acsmem
+@c     dgettext dup
+@c     argp_fmtstream_printf dup
+@c  hol_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c   hol_entry_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_set_lmargin dup
+@c    argp_fmtstream_wmargin dup
+@c    argp_fmtstream_set_wmargin dup
+@c    comma @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_putc dup
+@c     hol_cluster_is_child ok
+@c     argp_fmtstream_wmargin dup
+@c     print_header dup
+@c     argp_fmtstream_set_wmargin dup
+@c     argp_fmtstream_puts dup
+@c     indent_to dup
+@c    argp_fmtstream_putc dup
+@c    arg @mtslocale @ascuheap @acsmem
+@c     argp_fmtstream_printf dup
+@c    odoc dup
+@c    argp_fmtstream_puts dup
+@c    argp_fmtstream_printf dup
+@c    print_header @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c     dgettext dup
+@c     filter_doc dup
+@c     argp_fmtstream_putc dup
+@c     indent_to dup
+@c     argp_fmtstream_set_lmargin dup
+@c     argp_fmtstream_set_wmargin dup
+@c     argp_fmtstream_puts dup
+@c     free dup
+@c    filter_doc dup
+@c    argp_fmtstream_point dup
+@c    indent_to @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_point dup
+@c     argp_fmtstream_putc dup
+@c   dgettext dup
+@c   filter_doc dup
+@c   argp_fmtstream_putc dup
+@c   argp_fmtstream_puts dup
+@c   free dup
+@c  hol_free @ascuheap @acsmem
+@c   free dup
+@c  argp_args_levels ok
+@c  argp_args_usage @mtslocale @ascuintl @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   dgettext dup
+@c   filter_doc ok
+@c    argp_input ok
+@c    argp->help_filter
+@c   space @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_point dup
+@c    argp_fmtstream_rmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c     argp_fmtstream_update dup
+@c    argp_fmtstream_putc dup
+@c   argp_fmtstream_write dup
+@c   free dup
+@c  argp_doc @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock
+@c   dgettext @ascuintl
+@c   strndup @ascuheap @acsmem
+@c   argp_input dup
+@c   argp->help_filter
+@c   argp_fmtstream_putc @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_ensure dup
+@c   argp_fmtstream_write dup
+@c   argp_fmtstream_puts dup
+@c   argp_fmtstream_point @mtslocale @asucorrupt @acucorrupt @aculock
+@c    argp_fmtstream_update dup
+@c   argp_fmtstream_lmargin dup
+@c   free dup
+@c  argp_make_fmtstream @ascuheap @acsmem
+@c  argp_fmtstream_free @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   argp_fmtstream_update @mtslocale @asucorrupt @acucorrupt @aculock
+@c    put[w]c_unlocked dup
+@c    isblank in loop @mtslocale
+@c    fxprintf @aculock
+@c   fxprintf @aculock
+@c   free dup
+@c  argp_fmtstream_set_wmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c   argp_fmtstream_update dup
+@c  argp_fmtstream_printf @mtslocale @ascuheap @acsmem
+@c   argp_fmtstream_ensure dup
+@c   vsnprintf dup
+@c  argp_fmtstream_set_lmargin @mtslocale @asucorrupt @acucorrupt @aculock
+@c   argp_fmtstream_update dup
+@c  argp_fmtstream_puts @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c   argp_fmtstream_write @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c    argp_fmtstream_ensure @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock
+@c     argp_fmtstream_update dup
+@c     fxprintf @aculock
+@c     realloc @ascuheap @acsmem
+Outputs a help message for the argp parser referred to by @var{state},
+to @var{stream}.  The @var{flags} argument determines what sort of help
+message is produced.  @xref{Argp Help Flags}.
+@end deftypefun
+
+Error output is sent to @code{@var{state}->err_stream}, and the program
+name printed is @code{@var{state}->name}.
+
+The output or program termination behavior of these functions may be
+suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are
+passed to @code{argp_parse}.  @xref{Argp Flags}.
+
+This behavior is useful if an argp parser is exported for use by other
+programs (e.g., by a library), and may be used in a context where it is
+not desirable to terminate the program in response to parsing errors.  In
+argp parsers intended for such general use, and for the case where the
+program @emph{doesn't} terminate, calls to any of these functions should
+be followed by code that returns the appropriate error code:
+
+@smallexample
+if (@var{bad argument syntax})
+  @{
+     argp_usage (@var{state});
+     return EINVAL;
+  @}
+@end smallexample
+
+@noindent
+If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT}
+is not set, the return may be omitted.
+
+@node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
+@subsection Combining Multiple Argp Parsers
+
+The @code{children} field in a @code{struct argp} enables other argp
+parsers to be combined with the referencing one for the parsing of a
+single set of arguments.  This field should point to a vector of
+@code{struct argp_child}, which is terminated by an entry having a value
+of zero in the @code{argp} field.
+
+Where conflicts between combined parsers arise, as when two specify an
+option with the same name, the parser conflicts are resolved in favor of
+the parent argp parser(s), or the earlier of the argp parsers in the
+list of children.
+
+@comment argp.h
+@comment GNU
+@deftp {Data Type} {struct argp_child}
+An entry in the list of subsidiary argp parsers pointed to by the
+@code{children} field in a @code{struct argp}.  The fields are as
+follows:
+
+@table @code
+@item const struct argp *argp
+The child argp parser, or zero to end of the list.
+
+@item int flags
+Flags for this child.
+
+@item const char *header
+If non-zero, this is an optional header to be printed within help output
+before the child options.  As a side-effect, a non-zero value forces the
+child options to be grouped together.  To achieve this effect without
+actually printing a header string, use a value of @code{""}.  As with
+header strings specified in an option entry, the conventional value of
+the last character is @samp{:}.  @xref{Argp Option Vectors}.
+
+@item int group
+This is where the child options are grouped relative to the other
+`consolidated' options in the parent argp parser.  The values are the
+same as the @code{group} field in @code{struct argp_option}.  @xref{Argp
+Option Vectors}.  All child-groupings follow parent options at a
+particular group level.  If both this field and @code{header} are zero,
+then the child's options aren't grouped together, they are merged with
+parent options at the parent option group level.
+
+@end table
+@end deftp
+
+@node Argp Flags, Argp Help, Argp Parsers, Argp
+@subsection Flags for @code{argp_parse}
+
+The default behavior of @code{argp_parse} is designed to be convenient
+for the most common case of parsing program command line argument.  To
+modify these defaults, the following flags may be or'd together in the
+@var{flags} argument to @code{argp_parse}:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_PARSE_ARGV0
+Don't ignore the first element of the @var{argv} argument to
+@code{argp_parse}.  Unless @code{ARGP_NO_ERRS} is set, the first element
+of the argument vector is skipped for option parsing purposes, as it
+corresponds to the program name in a command line.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ERRS
+Don't print error messages for unknown options to @code{stderr}; unless
+this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
+is used as the program name in the error messages.  This flag implies
+@code{ARGP_NO_EXIT}.  This is based on the assumption that silent exiting
+upon errors is bad behavior.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ARGS
+Don't parse any non-option args.  Normally these are parsed by calling
+the parse functions with a key of @code{ARGP_KEY_ARG}, the actual
+argument being the value.  This flag needn't normally be set, as the
+default behavior is to stop parsing as soon as an argument fails to be
+parsed.  @xref{Argp Parser Functions}.
+
+@comment argp.h
+@comment GNU
+@item ARGP_IN_ORDER
+Parse options and arguments in the same order they occur on the command
+line.  Normally they're rearranged so that all options come first.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_HELP
+Don't provide the standard long option @samp{--help}, which ordinarily
+causes usage and option help information to be output to @code{stdout}
+and @code{exit (0)}.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_EXIT
+Don't exit on errors, although they may still result in error messages.
+
+@comment argp.h
+@comment GNU
+@item ARGP_LONG_ONLY
+Use the GNU getopt `long-only' rules for parsing arguments.  This allows
+long-options to be recognized with only a single @samp{-}
+(i.e., @samp{-help}).  This results in a less useful interface, and its
+use is discouraged as it conflicts with the way most GNU programs work
+as well as the GNU coding standards.
+
+@comment argp.h
+@comment GNU
+@item ARGP_SILENT
+Turns off any message-printing/exiting options, specifically
+@code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
+@end vtable
+
+@node Argp Help Filtering, , Argp Children, Argp Parsers
+@need 2000
+@subsection Customizing Argp Help Output
+
+The @code{help_filter} field in a @code{struct argp} is a pointer to a
+function that filters the text of help messages before displaying
+them.  They have a function signature like:
+
+@smallexample
+char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
+@end smallexample
+
+
+@noindent
+Where @var{key} is either a key from an option, in which case @var{text}
+is that option's help text.  @xref{Argp Option Vectors}.  Alternately, one
+of the special keys with names beginning with @samp{ARGP_KEY_HELP_}
+might be used, describing which other help text @var{text} will contain.
+@xref{Argp Help Filter Keys}.
+
+The function should return either @var{text} if it remains as-is, or a
+replacement string allocated using @code{malloc}.  This will be either be
+freed by argp or zero, which prints nothing.  The value of @var{text} is
+supplied @emph{after} any translation has been done, so if any of the
+replacement text needs translation, it will be done by the filter
+function.  @var{input} is either the input supplied to @code{argp_parse}
+or it is zero, if @code{argp_help} was called directly by the user.
+
+@menu
+* Keys: Argp Help Filter Keys.  Special @var{key} values for help filter functions.
+@end menu
+
+@node Argp Help Filter Keys, , , Argp Help Filtering
+@subsubsection Special Keys for Argp Help Filter Functions
+
+The following special values may be passed to an argp help filter
+function as the first argument in addition to key values for user
+options.  They specify which help text the @var{text} argument contains:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_PRE_DOC
+The help text preceding options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_POST_DOC
+The help text following options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_HEADER
+The option header string.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_EXTRA
+This is used after all other documentation; @var{text} is zero for this key.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_DUP_ARGS_NOTE
+The explanatory note printed when duplicate option arguments have been suppressed.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_ARGS_DOC
+The argument doc string; formally the @code{args_doc} field from the argp parser.  @xref{Argp Parsers}.
+@end vtable
+
+@node Argp Help, Argp Examples, Argp Flags, Argp
+@subsection The @code{argp_help} Function
+
+Normally programs using argp need not be written with particular
+printing argument-usage-type help messages in mind as the standard
+@samp{--help} option is handled automatically by argp.  Typical error
+cases can be handled using @code{argp_usage} and
+@code{argp_error}.  @xref{Argp Helper Functions}.  However, if it's
+desirable to print a help message in some context other than parsing the
+program options, argp offers the @code{argp_help} interface.
+
+@comment argp.h
+@comment GNU
+@deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
+@safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}}
+@c Just calls _help.
+This outputs a help message for the argp parser @var{argp} to
+@var{stream}.  The type of messages printed will be determined by
+@var{flags}.
+
+Any options such as @samp{--help} that are implemented automatically by
+argp itself will @emph{not} be present in the help output; for this
+reason it is best to use @code{argp_state_help} if calling from within
+an argp parser function.  @xref{Argp Helper Functions}.
+@end deftypefun
+
+@menu
+* Flags: Argp Help Flags.       Specifying what sort of help message to print.
+@end menu
+
+@node Argp Help Flags, , , Argp Help
+@subsection Flags for the @code{argp_help} Function
+
+When calling @code{argp_help} (@pxref{Argp Help}) or
+@code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output
+is determined by the @var{flags} argument.  This should consist of any of
+the following flags, or'd together:
+
+@vtable @code
+@item ARGP_HELP_USAGE
+A unix @samp{Usage:} message that explicitly lists all options.
+
+@item ARGP_HELP_SHORT_USAGE
+A unix @samp{Usage:} message that displays an appropriate placeholder to
+indicate where the options go; useful for showing the non-option
+argument syntax.
+
+@item ARGP_HELP_SEE
+A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
+program name and @samp{--help}.
+
+@item ARGP_HELP_LONG
+A verbose option help message that gives each option available along
+with its documentation string.
+
+@item ARGP_HELP_PRE_DOC
+The part of the argp parser doc string preceding the verbose option help.
+
+@item ARGP_HELP_POST_DOC
+The part of the argp parser doc string that following the verbose option help.
+
+@item ARGP_HELP_DOC
+@code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
+
+@item ARGP_HELP_BUG_ADDR
+A message that prints where to report bugs for this program, if the
+@code{argp_program_bug_address} variable contains this information.
+
+@item ARGP_HELP_LONG_ONLY
+This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode.
+@end vtable
+
+The following flags are only understood when used with
+@code{argp_state_help}.  They control whether the function returns after
+printing its output, or terminates the program:
+
+@vtable @code
+@item ARGP_HELP_EXIT_ERR
+This will terminate the program with @code{exit (argp_err_exit_status)}.
+
+@item ARGP_HELP_EXIT_OK
+This will terminate the program with @code{exit (0)}.
+@end vtable
+
+The following flags are combinations of the basic flags for printing
+standard messages:
+
+@vtable @code
+@item ARGP_HELP_STD_ERR
+Assuming that an error message for a parsing error has printed, this
+prints a message on how to get help, and terminates the program with an
+error.
+
+@item ARGP_HELP_STD_USAGE
+This prints a standard usage message and terminates the program with an
+error.  This is used when no other specific error messages are
+appropriate or available.
+
+@item ARGP_HELP_STD_HELP
+This prints the standard response for a @samp{--help} option, and
+terminates the program successfully.
+@end vtable
+
+@node Argp Examples, Argp User Customization, Argp Help, Argp
+@subsection Argp Examples
+
+These example programs demonstrate the basic usage of argp.
+
+@menu
+* 1: Argp Example 1.            A minimal program using argp.
+* 2: Argp Example 2.            A program using only default options.
+* 3: Argp Example 3.            A simple program with user options.
+* 4: Argp Example 4.            Combining multiple argp parsers.
+@end menu
+
+@node Argp Example 1, Argp Example 2, , Argp Examples
+@subsubsection A Minimal Program Using Argp
+
+This is perhaps the smallest program possible that uses argp.  It won't
+do much except give an error message and exit when there are any
+arguments, and prints a rather pointless message for @samp{--help}.
+
+@smallexample
+@include argp-ex1.c.texi
+@end smallexample
+
+@node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
+@subsubsection A Program Using Argp with Only Default Options
+
+This program doesn't use any options or arguments, it uses argp to be
+compliant with the GNU standard command line format.
+
+In addition to giving no arguments and implementing a @samp{--help}
+option, this example has a @samp{--version} option, which will put the
+given documentation string and bug address in the @samp{--help} output,
+as per GNU standards.
+
+The variable @code{argp} contains the argument parser
+specification.  Adding fields to this structure is the way most
+parameters are passed to @code{argp_parse}.  The first three fields are
+normally used, but they are not in this small program.  There are also
+two global variables that argp can use defined here,
+@code{argp_program_version} and @code{argp_program_bug_address}.  They
+are considered global variables because they will almost always be
+constant for a given program, even if they use different argument
+parsers for various tasks.
+
+@smallexample
+@include argp-ex2.c.texi
+@end smallexample
+
+@node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
+@subsubsection A Program Using Argp with User Options
+
+This program uses the same features as example 2, adding user options
+and arguments.
+
+We now use the first four fields in @code{argp} (@pxref{Argp Parsers})
+and specify @code{parse_opt} as the parser function.  @xref{Argp Parser
+Functions}.
+
+Note that in this example, @code{main} uses a structure to communicate
+with the @code{parse_opt} function, a pointer to which it passes in the
+@code{input} argument to @code{argp_parse}.  @xref{Argp}.  It is retrieved
+by @code{parse_opt} through the @code{input} field in its @code{state}
+argument.  @xref{Argp Parsing State}.  Of course, it's also possible to
+use global variables instead, but using a structure like this is
+somewhat more flexible and clean.
+
+@smallexample
+@include argp-ex3.c.texi
+@end smallexample
+
+@node Argp Example 4, , Argp Example 3, Argp Examples
+@subsubsection A Program Using Multiple Combined Argp Parsers
+
+This program uses the same features as example 3, but has more options,
+and presents more structure in the @samp{--help} output.  It also
+illustrates how you can `steal' the remainder of the input arguments
+past a certain point for programs that accept a list of items.  It also
+illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only
+given if no non-option arguments were supplied to the
+program.  @xref{Argp Special Keys}.
+
+For structuring help output, two features are used: @emph{headers} and a
+two part option string.  The @emph{headers} are entries in the options
+vector.  @xref{Argp Option Vectors}.  The first four fields are zero.  The
+two part documentation string are in the variable @code{doc}, which
+allows documentation both before and after the options.  @xref{Argp
+Parsers}, the two parts of @code{doc} are separated by a vertical-tab
+character (@code{'\v'}, or @code{'\013'}).  By convention, the
+documentation before the options is a short string stating what the
+program does, and after any options it is longer, describing the
+behavior in more detail.  All documentation strings are automatically
+filled for output, although newlines may be included to force a line
+break at a particular point.  In addition, documentation strings are
+passed to the @code{gettext} function, for possible translation into the
+current locale.
+
+@smallexample
+@include argp-ex4.c.texi
+@end smallexample
+
+@node Argp User Customization, , Argp Examples, Argp
+@subsection Argp User Customization
+
+@cindex ARGP_HELP_FMT environment variable
+The formatting of argp @samp{--help} output may be controlled to some
+extent by a program's users, by setting the @code{ARGP_HELP_FMT}
+environment variable to a comma-separated list of tokens.  Whitespace is
+ignored:
+
+@table @samp
+@item dup-args
+@itemx no-dup-args
+These turn @dfn{duplicate-argument-mode} on or off.  In duplicate
+argument mode, if an option that accepts an argument has multiple names,
+the argument is shown for each name.  Otherwise, it is only shown for the
+first long option.  A note is subsequently printed so the user knows that
+it applies to other names as well.  The default is @samp{no-dup-args},
+which is less consistent, but prettier.
+
+@item dup-args-note
+@item no-dup-args-note
+These will enable or disable the note informing the user of suppressed
+option argument duplication.  The default is @samp{dup-args-note}.
+
+@item short-opt-col=@var{n}
+This prints the first short option in column @var{n}.  The default is 2.
+
+@item long-opt-col=@var{n}
+This prints the first long option in column @var{n}.  The default is 6.
+
+@item doc-opt-col=@var{n}
+This prints `documentation options' (@pxref{Argp Option Flags}) in
+column @var{n}.  The default is 2.
+
+@item opt-doc-col=@var{n}
+This prints the documentation for options starting in column
+@var{n}.  The default is 29.
+
+@item header-col=@var{n}
+This will indent the group headers that document groups of options to
+column @var{n}.  The default is 1.
+
+@item usage-indent=@var{n}
+This will indent continuation lines in @samp{Usage:} messages to column
+@var{n}.  The default is 12.
+
+@item rmargin=@var{n}
+This will word wrap help output at or before column @var{n}.  The default
+is 79.
+@end table