Update.cvs/libc-ud-970604f

1997-06-04 05:09  Miles Bader  <miles@gnu.ai.mit.edu>

	* argp/argp-help.c (_help): Use uparams.usage_indent instead of
	the USAGE_INDENT macro.

	* manual/summary.awk: Strip trailing commas from node-names.

	* manual/.cvsignore: Ignore chapters-incl[12] rather than
	chapters-incl.

	* manual/Makefile (%.c.texi): Deal with multiple @-commands on a
	single line.

	* manual/string.texi (Argz Functions, Envz Functions): Add magic
	comments for generating summary.texi.

1997-06-02 22:18  Miles Bader  <miles@gnu.ai.mit.edu>

	* manual/argp.texi: New file.
	* manual/examples/argp-ex1.c, manual/examples/argp-ex2.c,
	manual/examples/argp-ex3.c, manual/examples/argp-ex4.c: New files.
	* manual/Makefile [chapters] (chapters-incl1): New rule & include.
	[chapters-incl1] (chapters-incl2): New rule & include.
	(chapters-incl): Set based on $(chapters-incl1) & $(chapters-incl2).
	* manual/maint.texi (Contributors): Give myself credit.

1997-06-01 15:01  Miles Bader  <miles@gnu.ai.mit.edu>

	* manual/getopt.texi: New file.
	* manual/startup.texi: Mention argp_parse in places that
	previously mentioned only getopt.
	Include getopt.texi (now containing all the getopt nodes that used
	to be here) and argp.texi.
	(Program Arguments): Move parsing bits into the new Parsing
	Program Arguments node.
	(Parsing Program Arguments): New node.
	(Parsing Options, Example of Getopt, Long Options, Long Option
	Example): Nodes removed.
	* manual/libc.texinfo: (Program Arguments): Menu updated.
	(Parsing Program Arguments): New menu.

1 files changed, 1127 insertions, 0 deletions

diff --git a/manual/argp.texi b/manual/argp.texi
new file mode 100644
index 0000000..53a405e
--- /dev/null
+++ b/manual/argp.texi
@@ -0,0 +1,1127 @@
+@ignore
+   Documentation for the argp argument parser
+
+   Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+   Written by Miles Bader <miles@gnu.ai.mit.edu>.
+
+   The GNU C Library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Library General Public License as
+   published by the Free Software Foundation; either version 2 of the
+   License, or (at your option) any later version.
+
+   The GNU C Library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Library General Public License for more details.
+
+   You should have received a copy of the GNU Library General Public
+   License along with the GNU C Library; see the file COPYING.LIB.  If not,
+   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+   Boston, MA 02111-1307, USA.  */
+@end ignore
+
+@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
+(@pxref{Program Arguments}).
+
+Unlike the more common @code{getopt} interface, it provides many related
+convenience features in addition to parsing options, such as
+automatically producing output in response to @samp{--help} and
+@samp{--version} options (as defined by the GNU coding standards).
+Doing these things in argp results in a more consistent look for
+programs that use it, and makes less likely that implementors will
+neglect to implement them 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,
+which programs can easily use in conjunction with their own option
+parser.  This results in less work for user programs (indeed, some may
+use only argument parsers exported by libraries, and have no options of
+their own), and more consistent option-parsing for the abstractions
+implemented by the library.
+
+@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; often, a
+call to @code{argp_parse} is the only argument-parsing code needed in
+@code{main} (@pxref{Program Arguments}).
+
+@comment argp.h
+@comment GNU
+@deftypefun {error_t} argp_parse (const struct argp *@var{argp}, @w{int @var{argc}, char **@var{argv}}, @w{unsigned @var{flags}}, @w{int *@var{arg_index}}, @w{void *@var{input}})
+The @code{argp_parse} function parses the arguments in in @var{argv}, of
+length @var{argc}, using the argp parser @var{argp} (@pxref{Argp
+Parsers}); a value of zero is the same as a @code{struct argp}
+containing all zeros.  @var{flags} is a set of flag bits that modify the
+parsing behavior (@pxref{Argp Flags}).  @var{input} is passed through to
+the argp parser @var{argp}, and has meaning defined by it; a typical
+usage is to pass a pointer to a structure which can be used for
+specifying parameters to the parser and passing back results from it.
+
+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---for instance when an unknown option is encountered.
+@xref{Program Termination}.
+
+The return value is zero for successful parsing, or a unix error code
+(@pxref{Error Codes}) if an error was detected.  Different argp parsers
+may return arbitrary error codes, but standard ones are @code{ENOMEM} if
+a memory allocation error occurred, or @code{EINVAL} if an unknown option
+or option argument was 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 very easy for every user program to implement
+the @samp{--version} option and provide a bug-reporting address in the
+@samp{--help} output (which is implemented by argp regardless).
+
+@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}
+(unless the @code{ARGP_NO_HELP} flag is used), which will print this
+string followed by a newline and exit (unless 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 string that is the
+bug-reporting address for the program.  It will be printed at the end of
+the standard output for the @samp{--help} option, embedded in a sentence
+that says something like @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, then a
+@samp{--version} option is added when parsing with @code{argp_parse}
+(unless the @code{ARGP_NO_HELP} flag is used), which calls this function
+to print the version, and then exits with a status of 0 (unless the
+@code{ARGP_NO_EXIT} flag is used).  It should point to a function with
+the following type 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 precedent over @code{argp_program_version}, and is
+useful if a program has version information that cannot be easily
+specified as a simple string.
+@end defvar
+
+@comment argp.h
+@comment GNU
+@deftypevar error_t argp_err_exit_status
+The exit status that argp will use when exiting 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 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 wanted by
+this parser; it 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 prefix 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
+saying what the program does, and that afterwards is longer, describing
+the behavior in more detail.
+
+@item const struct argp_child *children
+A pointer to a vector of @code{argp_children} structures specifying
+additional argp parsers that 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 to filter the output of help
+messages.  @xref{Argp Help Filtering}.
+@end table
+@end deftp
+
+The @code{options}, @code{parser}, @code{args_doc}, and @code{doc}
+fields are usually all that are needed.  If an argp parser is defined as
+an initialized C variable, only the used fields need be specified in in
+the initializer---the rest will default to zero due to the way C
+structure initialization works (this fact is exploited for most argp
+structures, grouping the most-used fields near the beginning, so that
+unused fields can simply be 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 argp parser supports (actually, sometimes multiple entries may used
+for a single option if it has many names).  It 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, and how to parse and document it.  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 can be zero if this option 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 (@pxref{Argp
+Option Flags}).
+
+@item int key
+The integer key that is provided to the argp parser's parsing function
+when this option is being parsed.  Also, 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 out-dented from the normal option column, making it
+useful as a group header (it 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
+The group this option is in.
+
+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},
+-@var{m}, @dots{}, -2, -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, unless its a group header (@code{name} and
+@code{key} fields both zero), in which case, the previous entry + 1 is
+the default.  Automagic options such as @samp{--help} are put into group
+-1.
+
+Note that because of C structure initialization rules, this field
+often need not be specified, because 0 is the right 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}, and 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 aliased option.
+
+@comment argp.h
+@comment GNU
+@item OPTION_DOC
+This option isn't actually an option (and so should be ignored by the
+actual option parser), but rather an arbitrary piece of documentation
+that should be displayed in much the same manner as the options (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 the
+documentation string in the normal place.  For purposes of sorting, any
+leading whitespace and punctuation is ignored, except that if the first
+non-whitespace character is not @samp{-}, this entry is displayed after
+all options (and @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 is still
+included in help messages).  This is mainly intended for options that
+are completely documented in an argp's @code{args_doc} field
+(@pxref{Argp Parsers}), in which case including the option
+in the generic usage list would be redundant.
+
+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 that is parsed, and is also used as a hook,
+to allow a parser to do something 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
+(@pxref{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 the value given for it, or zero
+if no value was specified.  Only options that have a non-zero @code{arg}
+field can ever have a value, and those must @emph{always} have a value,
+unless the @code{OPTION_ARG_OPTIONAL} flag was 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 either @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
+(@pxref{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 do not which 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 (@var{arg} and @var{state} refer to parser function arguments;
+@pxref{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 (due to argp parsers being
+combined), it's impossible to know which one wants to handle an
+argument, so each is called in turn, until one returns 0 or an error
+other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one,
+@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_END
+There are no more command line arguments at all.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_NO_ARGS
+Because it's common to want 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.  Called just
+before @code{ARGP_KEY_END} (where more general validity checks on
+previously parsed arguments can take place).
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_INIT
+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 there are
+still arguments remaining).
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_ERROR
+Passed in if an error has occurred, and parsing terminated (in which 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 (although sometimes
+certain resources allocated there 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 contained no non-option arguments at all.
+
+@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 was unrecognized.
+
+This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
+for an argument, in which case parsing stops at that argument.  If a
+non-zero value for @var{arg_index} was passed to @code{argp_parse}, the
+index of this argument is returned in it, otherwise an error occurs.
+@end table
+
+If an error occurs (either detected by argp, or because a parser
+function returned an error value), then each parser is called with
+@code{ARGP_KEY_ERROR}, and no further calls are made except the final
+call with @code{ARGP_KEY_FINI}.
+
+@node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
+@subsubsection Functions For Use in Argp Parsers
+
+Argp provides a number of functions for the user of argp parser
+functions (@pxref{Argp Parser Functions}), mostly for producing error
+messages.  These take as their first argument the @var{state} argument
+to the parser function (@pxref{Argp Parsing State}).
+
+@cindex usage messages, in argp
+@comment argp.h
+@comment GNU
+@deftypefun void argp_usage (const struct argp_state *@var{state})
+Output the standard usage message for the argp parser referred to by
+@var{state} to @code{@var{state}->err_stream} and terminate the program
+with @code{exit (argp_err_exit_status)} (@pxref{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}, @w{const char *@var{fmt}, @dots{}})
+Print 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 terminate the program with an exit status of
+@code{argp_err_exit_status} (@pxref{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}, @w{int @var{status}, int @var{errnum},} @w{const char *@var{fmt}, @dots{}})
+Similarly to the standard gnu error-reporting function @code{error},
+print the printf format string @var{fmt} and following args, preceded by
+the program name and @samp{:}, and followed by the standard unix error
+text for @var{errnum} if it is non-zero; then if @var{status} is
+non-zero, terminate the program with that as its exit status.
+
+The difference between this function 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}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}})
+Output 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,
+respectively, were 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, calls to any of these
+functions should be followed by code return of an appropriate error code
+for the case where the program @emph{doesn't} terminate; for example:
+
+@smallexample
+if (@var{bad argument syntax})
+  @{
+     argp_usage (@var{state});
+     return EINVAL;
+  @}
+@end smallexample
+
+@noindent
+If it's known that a parser function will only be used when
+@code{ARGP_NO_EXIT} is not set, the return may be omitted.
+
+@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 (@pxref{Argp}), but instead 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.  May be modified.
+
+@item int next
+The index in @code{argv} of the next argument to be parsed.  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).
+Also, you can cause the current option to be re-parsed by decrementing
+this field, and then modifying
+@code{@var{state}->argv[@var{state}->next]} to be the option that should
+be reexamined.
+
+@item unsigned flags
+The flags supplied to @code{argp_parse}.  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 is the number of the current arg, starting at
+0, and incremented after each such call returns.  At all other times,
+this is the number of such 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 (which prevents anything following being
+interpreted as an option).  Only set once 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
+Values to pass to child parsers.  This vector will be the same length as
+the number of children in the current parser, and 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 that is
+unavailable.
+
+@item FILE *err_stream
+@itemx FILE *out_stream
+Stdio streams used when argp prints something; error messages are
+printed to @code{err_stream}, and all other output (such as
+@samp{--help} output) to @code{out_stream}.  These are initialized to
+@code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}).
+
+@item void *pstate
+Private, for use by the argp implementation.
+@end table
+@end deftp
+
+@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} allows other argp
+parsers to be combined with the referencing one to parse a single set of
+arguments.  It should point to a vector of @code{struct argp_child},
+terminated by an entry having a value of zero in the @code{argp} field.
+
+Where conflicts between combined parsers arise (for instance, if two
+specify an option with the same name), they are resolved in favor of
+the parent argp parsers, or earlier 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 the list.
+
+@item int flags
+Flags for this child.
+
+@item const char *header
+If non-zero, an optional header to be printed in 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 value conventionally has
+@samp{:} as the last character.  @xref{Argp Option Vectors}.
+
+@item int group
+Where to group the child options 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} (@pxref{Argp Option
+Vectors}), but 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 at all, but rather merged with
+the parent options (merging the child's grouping levels with the
+parents).
+@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}.  Normally (and always 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} (on the assumption that silent exiting upon errors
+is bad behaviour).
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_ARGS
+Don't parse any non-option args.  Normally non-option args are parsed by
+calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the
+actual arg as the value.  This flag needn't normally be set, as the
+normal behavior is to stop parsing as soon as some argument isn't
+accepted by a parsing function.  @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)} called.
+
+@comment argp.h
+@comment GNU
+@item ARGP_NO_EXIT
+Don't exit on errors (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.
+
+@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 a @code{struct argp} is a pointer to a
+function to filter 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 (@pxref{Argp Option Vectors}), or one of the
+special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing
+which other help text @var{text} is (@pxref{Argp Help Filter Keys}).
+
+The function should return either @var{text}, if it should be used
+as-is, a replacement string, which should be allocated using
+@code{malloc}, and will be freed by argp, or zero, meaning `print
+nothing'.  The value of @var{text} supplied is @emph{after} any
+translation has been done, so if any of the replacement text also needs
+translation, that should be done by the filter function.  @var{input} is
+either the input supplied to @code{argp_parse}, or 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, and specify which help text the @var{text} argument contains:
+
+@vtable @code
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_PRE_DOC
+Help text preceding options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_POST_DOC
+Help text following options.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_HEADER
+Option header string.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_EXTRA
+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 emitted when duplicate option arguments have been
+suppressed.
+
+@comment argp.h
+@comment GNU
+@item ARGP_KEY_HELP_ARGS_DOC
+The argument doc string (the @code{args_doc} field from the argp parser;
+@pxref{Argp Parsers}).
+@end vtable
+
+@node Argp Help, Argp Examples, Argp Flags, Argp
+@subsection The @code{argp_help} Function
+
+Normally programs using argp need not worry too much about printing
+argument-usage-type help messages, because the standard @samp{--help}
+option is handled automatically by argp, and the typical error cases can
+be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp
+Helper Functions}).
+
+However, if it's desirable to print a standard 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}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{char *@var{name}})
+Output a help message for the argp parser @var{argp} to @var{stream}.
+What sort of messages is printed is 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 better 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}), exactly what is
+output is determined by the @var{flags} argument, which 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 only 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 understood along
+with its documentation string.
+
+@item ARGP_HELP_PRE_DOC
+The part of the argp parser doc string that precedes the verbose option help.
+
+@item ARGP_HELP_POST_DOC
+The part of the argp parser doc string that follows the verbose option help.
+
+@item ARGP_HELP_DOC
+@code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
+
+@item ARGP_HELP_BUG_ADDR
+A message saying where to report bugs for this program, if the
+@code{argp_program_bug_address} variable contains one.
+
+@item ARGP_HELP_LONG_ONLY
+Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode.
+@end vtable
+
+The following flags are only understood when used with
+@code{argp_state_help}, and control whether the function returns after
+printing its output, or terminates the program:
+
+@vtable @code
+@item ARGP_HELP_EXIT_ERR
+Terminate the program with @code{exit (argp_err_exit_status)}.
+
+@item ARGP_HELP_EXIT_OK
+Terminate the program with @code{exit (0)}.
+@end vtable
+
+The following flags are combinations of the basic ones for printing
+standard messages:
+
+@vtable @code
+@item ARGP_HELP_STD_ERR
+Assuming an error message for a parsing error has already printed,
+prints a note on how to get help, and terminates the program with an
+error.
+
+@item ARGP_HELP_STD_USAGE
+Prints a standard usage message and terminates the program with an
+error.  This is used when no more specific error message is appropriate.
+
+@item ARGP_HELP_STD_HELP
+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 (probably) the smallest possible program that uses argp.
+It won't do much except give an error messages and exit when there are any
+arguments, and print 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, but uses argp to be
+compliant with the GNU standard command line format.
+
+In addition to making sure no arguments are given, and implementing a
+@samp{--help} option, this example will have a @samp{--version} option,
+and 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 usually used, but not in
+this small program).  There are also two global variables that argp
+knows about defined here, @code{argp_program_version} and
+@code{argp_program_bug_address} (they are global variables because they
+will almost always be constant for a given program, even if it uses
+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, and adds user options
+and arguments.
+
+We now use the first four fields in @code{argp} (@pxref{Argp Parsers}),
+and specifies @code{parse_opt} as the parser function (@pxref{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} (@pxref{Argp}), and is
+retrieved by @code{parse_opt} through the @code{input} field in its
+@code{state} argument (@pxref{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 somewhat more structure in the @samp{--help} output.  It also shows
+how you can `steal' the remainder of the input arguments past a certain
+point, for programs that accept a list of items, and the special
+@var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no
+non-option arguments were supplied to the program (@pxref{Argp Special
+Keys}).
+
+For structuring the help output, two features are used: @emph{headers},
+which are entries in the options vector (@pxref{Argp Option Vectors})
+with the first four fields being zero, and a two part documentation
+string (in the variable @code{doc}), which allows documentation both
+before and after the options (@pxref{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 just a short string saying what the program does,
+and that afterwards 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.
+All documentation strings are also 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 way 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 (whitespace is ignored)
+of the following tokens:
+
+@table @samp
+@item dup-args
+@itemx no-dup-args
+Turn @dfn{duplicate-argument-mode} on or off.  In duplicate argument
+mode, if an option which accepts an argument has multiple names, the
+argument is shown for each name; otherwise, it is only shown for the
+first long option, and a note is emitted later so the user knows that it
+applies to the 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
+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}
+Show the first short option in column @var{n} (default 2).
+
+@item long-opt-col=@var{n}
+Show the first long option in column @var{n} (default 6).
+
+@item doc-opt-col=@var{n}
+Show `documentation options' (@pxref{Argp Option Flags}) in column
+@var{n} (default 2).
+
+@item opt-doc-col=@var{n}
+Show the documentation for options starting in column @var{n} (default 29).
+
+@item header-col=@var{n}
+Indent group headers (which document groups of options) to column
+@var{n} (default 1).
+
+@item usage-indent=@var{n}
+Indent continuation lines in @samp{Usage:} messages to column @var{n}
+(default 12).
+
+@item rmargin=@var{n}
+Word wrap help output at or before column @var{n} (default 79).
+@end table