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.

13 files changed, 1506 insertions, 284 deletions

diff --git a/ChangeLog b/ChangeLog
index 0d9a0825a7..6d0fd8d049 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,44 @@
+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.
+
 1997-06-04 20:57  Ulrich Drepper  <drepper@cygnus.com>
 
 	* manual/string.texi: Add comments to discourage use of index and
diff --git a/argp/argp-help.c b/argp/argp-help.c
index 2120ab1526..0d944414cb 100644
--- a/argp/argp-help.c
+++ b/argp/argp-help.c
@@ -1499,7 +1499,7 @@ _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
       do
 	{
 	  int old_lm;
-	  int old_wm = __argp_fmtstream_set_wmargin (fs, USAGE_INDENT);
+	  int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
 	  char *levels = pattern_levels;
 
 	  __argp_fmtstream_printf (fs, "%s %s",
@@ -1508,7 +1508,7 @@ _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
 
 	  /* We set the lmargin as well as the wmargin, because hol_usage
 	     manually wraps options with newline to avoid annoying breaks.  */
-	  old_lm = __argp_fmtstream_set_lmargin (fs, USAGE_INDENT);
+	  old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
 
 	  if (flags & ARGP_HELP_SHORT_USAGE)
 	    /* Just show where the options go.  */
diff --git a/manual/.cvsignore b/manual/.cvsignore
index 146fd188bf..51a9a04ef2 100644
--- a/manual/.cvsignore
+++ b/manual/.cvsignore
@@ -8,5 +8,5 @@ glibc-*
 *.toc *.aux *.log
 *.cp *.cps *.fn *.fns *.vr *.vrs *.tp *.tps *.ky *.kys *.pg *.pgs
 
-chapters chapters-incl summary.texi stamp-*
+chapters chapters-incl1 chapters-incl2 summary.texi stamp-*
 distinfo
diff --git a/manual/Makefile b/manual/Makefile
index 94cc59c891..5f05524049 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -39,11 +39,20 @@ endif
 chapters: libc.texinfo
 	$(find-includes)
 ifdef chapters
--include chapters-incl
-chapters-incl: $(chapters)
+# @includes in chapter files
+-include chapters-incl1
+chapters-incl1: $(chapters)
 	$(find-includes)
-chapters-incl := $(filter-out summary.texi,$(chapters-incl))
+chapters-incl1 := $(filter-out summary.texi,$(chapters-incl1))
 endif
+ifdef chapters-incl1
+# @includes in files included by chapter files, if any
+-include chapters-incl2
+chapters-incl2: $(chapters-incl1)
+	$(find-includes)
+endif
+
+chapters-incl := $(chapters-incl1) $(chapters-incl2)
 
 define find-includes
 (echo '$(@F) :=' \\	;\
@@ -75,7 +84,7 @@ dir-add.texi: xtract-typefun.awk $(chapters)
 	sed -e 's,[{}],@&,g'				\
 	    -e 's,/\*\(@.*\)\*/,\1,g'			\
 	    -e 's,/\*  *,/* @r{,g' -e 's,  *\*/,} */,'	\
-	    -e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/'\
+	    -e 's/\(@[a-z][a-z]*\)@{\([^}]*\)@}/\1{\2}/g'\
 	    $< | expand > $@.new
 	mv -f $@.new $@
 
diff --git a/manual/argp.texi b/manual/argp.texi
new file mode 100644
index 0000000000..53a405e93f
--- /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
diff --git a/manual/getopt.texi b/manual/getopt.texi
new file mode 100644
index 0000000000..8e1102f911
--- /dev/null
+++ b/manual/getopt.texi
@@ -0,0 +1,257 @@
+@node Getopt, Argp, , Parsing Program Arguments
+@section Parsing program options using @code{getopt}
+
+The @code{getopt} and @code{getopt_long} functions automate some of the
+chore involved in parsing typical unix command line options.
+
+@menu
+* Using Getopt::                Using the @code{getopt} function.
+* Example of Getopt::           An example of parsing options with @code{getopt}.
+* Getopt Long Options::         GNU suggests utilities accept long-named
+                                 options; here is one way to do.
+* Getopt Long Option Example::  An example of using @code{getopt_long}.
+@end menu
+
+@node Using Getopt, Example of Getopt, , Getopt
+@subsection Using the @code{getopt} function
+
+Here are the details about how to call the @code{getopt} function.  To
+use this facility, your program must include the header file
+@file{unistd.h}.
+@pindex unistd.h
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int opterr
+If the value of this variable is nonzero, then @code{getopt} prints an
+error message to the standard error stream if it encounters an unknown
+option character or an option with a missing required argument.  This is
+the default behavior.  If you set this variable to zero, @code{getopt}
+does not print any messages, but it still returns the character @code{?}
+to indicate an error.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optopt
+When @code{getopt} encounters an unknown option character or an option
+with a missing required argument, it stores that option character in
+this variable.  You can use this for providing your own diagnostic
+messages.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar int optind
+This variable is set by @code{getopt} to the index of the next element
+of the @var{argv} array to be processed.  Once @code{getopt} has found
+all of the option arguments, you can use this variable to determine
+where the remaining non-option arguments begin.  The initial value of
+this variable is @code{1}.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypevar {char *} optarg
+This variable is set by @code{getopt} to point at the value of the
+option argument, for those options that accept arguments.
+@end deftypevar
+
+@comment unistd.h
+@comment POSIX.2
+@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
+The @code{getopt} function gets the next option argument from the
+argument list specified by the @var{argv} and @var{argc} arguments.
+Normally these values come directly from the arguments received by
+@code{main}.
+
+The @var{options} argument is a string that specifies the option
+characters that are valid for this program.  An option character in this
+string can be followed by a colon (@samp{:}) to indicate that it takes a
+required argument.
+
+If the @var{options} argument string begins with a hyphen (@samp{-}), this
+is treated specially.  It permits arguments that are not options to be
+returned as if they were associated with option character @samp{\0}.
+
+The @code{getopt} function returns the option character for the next
+command line option.  When no more option arguments are available, it
+returns @code{-1}.  There may still be more non-option arguments; you
+must compare the external variable @code{optind} against the @var{argc}
+parameter to check this.
+
+If the option has an argument, @code{getopt} returns the argument by
+storing it in the variable @var{optarg}.  You don't ordinarily need to
+copy the @code{optarg} string, since it is a pointer into the original
+@var{argv} array, not into a static area that might be overwritten.
+
+If @code{getopt} finds an option character in @var{argv} that was not
+included in @var{options}, or a missing option argument, it returns
+@samp{?} and sets the external variable @code{optopt} to the actual
+option character.  If the first character of @var{options} is a colon
+(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
+indicate a missing option argument.  In addition, if the external
+variable @code{opterr} is nonzero (which is the default), @code{getopt}
+prints an error message.
+@end deftypefun
+
+@node Example of Getopt
+@subsection Example of Parsing Arguments with @code{getopt}
+
+Here is an example showing how @code{getopt} is typically used.  The
+key points to notice are:
+
+@itemize @bullet
+@item
+Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
+@code{-1}, indicating no more options are present, the loop terminates.
+
+@item
+A @code{switch} statement is used to dispatch on the return value from
+@code{getopt}.  In typical use, each case just sets a variable that
+is used later in the program.
+
+@item
+A second loop is used to process the remaining non-option arguments.
+@end itemize
+
+@smallexample
+@include testopt.c.texi
+@end smallexample
+
+Here are some examples showing what this program prints with different
+combinations of arguments:
+
+@smallexample
+% testopt
+aflag = 0, bflag = 0, cvalue = (null)
+
+% testopt -a -b
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -ab
+aflag = 1, bflag = 1, cvalue = (null)
+
+% testopt -c foo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt -cfoo
+aflag = 0, bflag = 0, cvalue = foo
+
+% testopt arg1
+aflag = 0, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -a arg1
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument arg1
+
+% testopt -c foo arg1
+aflag = 0, bflag = 0, cvalue = foo
+Non-option argument arg1
+
+% testopt -a -- -b
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -b
+
+% testopt -a -
+aflag = 1, bflag = 0, cvalue = (null)
+Non-option argument -
+@end smallexample
+
+@node Getopt Long Options
+@subsection Parsing Long Options with @code{getopt_long}
+
+To accept GNU-style long options as well as single-character options,
+use @code{getopt_long} instead of @code{getopt}.  This function is
+declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
+program accept long options if it uses any options, for this takes
+little extra work and helps beginners remember how to use the program.
+
+@comment getopt.h
+@comment GNU
+@deftp {Data Type} {struct option}
+This structure describes a single long option name for the sake of
+@code{getopt_long}.  The argument @var{longopts} must be an array of
+these structures, one for each long option.  Terminate the array with an
+element containing all zeros.
+
+The @code{struct option} structure has these fields:
+
+@table @code
+@item const char *name
+This field is the name of the option.  It is a string.
+
+@item int has_arg
+This field says whether the option takes an argument.  It is an integer,
+and there are three legitimate values: @w{@code{no_argument}},
+@code{required_argument} and @code{optional_argument}.
+
+@item int *flag
+@itemx int val
+These fields control how to report or act on the option when it occurs.
+
+If @code{flag} is a null pointer, then the @code{val} is a value which
+identifies this option.  Often these values are chosen to uniquely
+identify particular long options.
+
+If @code{flag} is not a null pointer, it should be the address of an
+@code{int} variable which is the flag for this option.  The value in
+@code{val} is the value to store in the flag to indicate that the option
+was seen.
+@end table
+@end deftp
+
+@comment getopt.h
+@comment GNU
+@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
+Decode options from the vector @var{argv} (whose length is @var{argc}).
+The argument @var{shortopts} describes the short options to accept, just as
+it does in @code{getopt}.  The argument @var{longopts} describes the long
+options to accept (see above).
+
+When @code{getopt_long} encounters a short option, it does the same
+thing that @code{getopt} would do: it returns the character code for the
+option, and stores the options argument (if it has one) in @code{optarg}.
+
+When @code{getopt_long} encounters a long option, it takes actions based
+on the @code{flag} and @code{val} fields of the definition of that
+option.
+
+If @code{flag} is a null pointer, then @code{getopt_long} returns the
+contents of @code{val} to indicate which option it found.  You should
+arrange distinct values in the @code{val} field for options with
+different meanings, so you can decode these values after
+@code{getopt_long} returns.  If the long option is equivalent to a short
+option, you can use the short option's character code in @code{val}.
+
+If @code{flag} is not a null pointer, that means this option should just
+set a flag in the program.  The flag is a variable of type @code{int}
+that you define.  Put the address of the flag in the @code{flag} field.
+Put in the @code{val} field the value you would like this option to
+store in the flag.  In this case, @code{getopt_long} returns @code{0}.
+
+For any long option, @code{getopt_long} tells you the index in the array
+@var{longopts} of the options definition, by storing it into
+@code{*@var{indexptr}}.  You can get the name of the option with
+@code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
+long options either by the values in their @code{val} fields or by their
+indices.  You can also distinguish in this way among long options that
+set flags.
+
+When a long option has an argument, @code{getopt_long} puts the argument
+value in the variable @code{optarg} before returning.  When the option
+has no argument, the value in @code{optarg} is a null pointer.  This is
+how you can tell whether an optional argument was supplied.
+
+When @code{getopt_long} has no more options to handle, it returns
+@code{-1}, and leaves in the variable @code{optind} the index in
+@var{argv} of the next remaining argument.
+@end deftypefun
+
+@node Getopt Long Option Example
+@subsection Example of Parsing Long Options with @code{getopt_long}
+
+@smallexample
+@include longopt.c.texi
+@end smallexample
diff --git a/manual/libc.texinfo b/manual/libc.texinfo
index aa72be16e3..e821807a17 100644
--- a/manual/libc.texinfo
+++ b/manual/libc.texinfo
@@ -745,11 +745,14 @@ Process Startup and Termination
 Program Arguments
 
 * Argument Syntax::             By convention, options start with a hyphen.
-* Parsing Options::             The @code{getopt} function.
-* Example of Getopt::           An example of parsing options with @code{getopt}.
-* Long Options::                GNU utilities should accept long-named options.
-                                 Here is how to do that.
-* Long Option Example::         An example of using @code{getopt_long}.
+* Parsing Program Arguments::   Ways to parse program options and arguments.
+
+Parsing Program Arguments
+
+* Getopt::                      Parsing program options using @code{getopt}.
+* Argp::                        Parsing program options using @code{argp_parse}.
+* Suboptions::                  Some programs need more detailed options.
+* Suboptions Example::          This shows how it could be done for @code{mount}.
 
 Environment Variables
 
diff --git a/manual/maint.texi b/manual/maint.texi
index 9c542a3ce3..654182e6e1 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -902,6 +902,10 @@ David Mosberger-Tang contributed the port to Linux/Alpha
 (@code{alpha-@var{anything}-linux}).
 
 @item
+Miles Bader wrote the argp argument-parsing package, and the argz/envz
+interfaces.
+
+@item
 Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
 
 @item
diff --git a/manual/startup.texi b/manual/startup.texi
index db6a4c8e32..e61a755456 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -64,12 +64,6 @@ is this null pointer.
 For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
 three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
 
-If the syntax for the command line arguments to your program is simple
-enough, you can simply pick the arguments off from @var{argv} by hand.
-But unless your program takes a fixed number of arguments, or all of the
-arguments are interpreted in the same way (as file names, for example),
-you are usually better off using @code{getopt} to do the parsing.
-
 In Unix systems you can define @code{main} a third way, using three arguments:
 
 @smallexample
@@ -84,13 +78,7 @@ allow this three-argument form, so to be portable it is best to write
 
 @menu
 * Argument Syntax::             By convention, options start with a hyphen.
-* Parsing Options::             The @code{getopt} function.
-* Example of Getopt::           An example of parsing options with @code{getopt}.
-* Long Options::                GNU suggests utilities accept long-named options.
-			   Here is how to do that.
-* Long Option Example::         An example of using @code{getopt_long}.
-* Suboptions::                  Some programs need more detailed options.
-* Suboptions Example::          This shows how it could be done for @code{mount}.
+* Parsing Program Arguments::   Ways to parse program options and arguments.
 @end menu
 
 @node Argument Syntax
@@ -100,7 +88,8 @@ allow this three-argument form, so to be portable it is best to write
 @cindex command argument syntax
 
 POSIX recommends these conventions for command line arguments.
-@code{getopt} (@pxref{Parsing Options}) makes it easy to implement them.
+@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
+it easy to implement them.
 
 @itemize @bullet
 @item
@@ -127,14 +116,14 @@ other words, the whitespace separating them is optional.)  Thus,
 @item
 Options typically precede other non-option arguments.
 
-The implementation of @code{getopt} in the GNU C library normally makes
-it appear as if all the option arguments were specified before all the
-non-option arguments for the purposes of parsing, even if the user of
-your program intermixed option and non-option arguments.  It does this
-by reordering the elements of the @var{argv} array.  This behavior is
-nonstandard; if you want to suppress it, define the
-@code{_POSIX_OPTION_ORDER} environment variable.  @xref{Standard
-Environment}.
+The implementations of @code{getopt} and @code{argp_parse} in the GNU C
+library normally make it appear as if all the option arguments were
+specified before all the non-option arguments for the purposes of
+parsing, even if the user of your program intermixed option and
+non-option arguments.  They do this by reordering the elements of the
+@var{argv} array.  This behavior is nonstandard; if you want to suppress
+it, define the @code{_POSIX_OPTION_ORDER} environment variable.
+@xref{Standard Environment}.
 
 @item
 The argument @samp{--} terminates all options; any following arguments
@@ -164,255 +153,41 @@ accept an argument that is itself optional.
 Eventually, the GNU system will provide completion for long option names
 in the shell.
 
-@node Parsing Options
-@subsection Parsing Program Options
+@node Parsing Program Arguments
+@subsection Parsing Program Arguments
+
 @cindex program arguments, parsing
 @cindex command arguments, parsing
 @cindex parsing program arguments
+If the syntax for the command line arguments to your program is simple
+enough, you can simply pick the arguments off from @var{argv} by hand.
+But unless your program takes a fixed number of arguments, or all of the
+arguments are interpreted in the same way (as file names, for example),
+you are usually better off using @code{getopt} (@pxref{Getopt}) or
+@code{argp_parse} (@pxref{Argp}) to do the parsing.
 
-Here are the details about how to call the @code{getopt} function.  To
-use this facility, your program must include the header file
-@file{unistd.h}.
-@pindex unistd.h
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int opterr
-If the value of this variable is nonzero, then @code{getopt} prints an
-error message to the standard error stream if it encounters an unknown
-option character or an option with a missing required argument.  This is
-the default behavior.  If you set this variable to zero, @code{getopt}
-does not print any messages, but it still returns the character @code{?}
-to indicate an error.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optopt
-When @code{getopt} encounters an unknown option character or an option
-with a missing required argument, it stores that option character in
-this variable.  You can use this for providing your own diagnostic
-messages.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optind
-This variable is set by @code{getopt} to the index of the next element
-of the @var{argv} array to be processed.  Once @code{getopt} has found
-all of the option arguments, you can use this variable to determine
-where the remaining non-option arguments begin.  The initial value of
-this variable is @code{1}.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar {char *} optarg
-This variable is set by @code{getopt} to point at the value of the
-option argument, for those options that accept arguments.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
-The @code{getopt} function gets the next option argument from the
-argument list specified by the @var{argv} and @var{argc} arguments.
-Normally these values come directly from the arguments received by
-@code{main}.
-
-The @var{options} argument is a string that specifies the option
-characters that are valid for this program.  An option character in this
-string can be followed by a colon (@samp{:}) to indicate that it takes a
-required argument.
-
-If the @var{options} argument string begins with a hyphen (@samp{-}), this
-is treated specially.  It permits arguments that are not options to be
-returned as if they were associated with option character @samp{\0}.
-
-The @code{getopt} function returns the option character for the next
-command line option.  When no more option arguments are available, it
-returns @code{-1}.  There may still be more non-option arguments; you
-must compare the external variable @code{optind} against the @var{argc}
-parameter to check this.
-
-If the option has an argument, @code{getopt} returns the argument by
-storing it in the variable @var{optarg}.  You don't ordinarily need to
-copy the @code{optarg} string, since it is a pointer into the original
-@var{argv} array, not into a static area that might be overwritten.
-
-If @code{getopt} finds an option character in @var{argv} that was not
-included in @var{options}, or a missing option argument, it returns
-@samp{?} and sets the external variable @code{optopt} to the actual
-option character.  If the first character of @var{options} is a colon
-(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
-indicate a missing option argument.  In addition, if the external
-variable @code{opterr} is nonzero (which is the default), @code{getopt}
-prints an error message.
-@end deftypefun
-
-@node Example of Getopt
-@subsection Example of Parsing Arguments with @code{getopt}
-
-Here is an example showing how @code{getopt} is typically used.  The
-key points to notice are:
-
-@itemize @bullet
-@item
-Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
-@code{-1}, indicating no more options are present, the loop terminates.
-
-@item
-A @code{switch} statement is used to dispatch on the return value from
-@code{getopt}.  In typical use, each case just sets a variable that
-is used later in the program.
-
-@item
-A second loop is used to process the remaining non-option arguments.
-@end itemize
-
-@smallexample
-@include testopt.c.texi
-@end smallexample
-
-Here are some examples showing what this program prints with different
-combinations of arguments:
-
-@smallexample
-% testopt
-aflag = 0, bflag = 0, cvalue = (null)
-
-% testopt -a -b
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -ab
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -c foo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt -cfoo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt arg1
-aflag = 0, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -a arg1
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -c foo arg1
-aflag = 0, bflag = 0, cvalue = foo
-Non-option argument arg1
-
-% testopt -a -- -b
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -b
-
-% testopt -a -
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -
-@end smallexample
-
-@node Long Options
-@subsection Parsing Long Options
-
-To accept GNU-style long options as well as single-character options,
-use @code{getopt_long} instead of @code{getopt}.  This function is
-declared in @file{getopt.h}, not @file{unistd.h}.  You should make every
-program accept long options if it uses any options, for this takes
-little extra work and helps beginners remember how to use the program.
-
-@comment getopt.h
-@comment GNU
-@deftp {Data Type} {struct option}
-This structure describes a single long option name for the sake of
-@code{getopt_long}.  The argument @var{longopts} must be an array of
-these structures, one for each long option.  Terminate the array with an
-element containing all zeros.
-
-The @code{struct option} structure has these fields:
+@code{getopt} is more standard (the short-option only version of it is a
+part of the POSIX standard), but using @code{argp_parse} is often
+easier, both for very simple and very complex option structures, because
+it does more of the dirty work for you.
 
-@table @code
-@item const char *name
-This field is the name of the option.  It is a string.
-
-@item int has_arg
-This field says whether the option takes an argument.  It is an integer,
-and there are three legitimate values: @w{@code{no_argument}},
-@code{required_argument} and @code{optional_argument}.
-
-@item int *flag
-@itemx int val
-These fields control how to report or act on the option when it occurs.
-
-If @code{flag} is a null pointer, then the @code{val} is a value which
-identifies this option.  Often these values are chosen to uniquely
-identify particular long options.
-
-If @code{flag} is not a null pointer, it should be the address of an
-@code{int} variable which is the flag for this option.  The value in
-@code{val} is the value to store in the flag to indicate that the option
-was seen.
-@end table
-@end deftp
-
-@comment getopt.h
-@comment GNU
-@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
-Decode options from the vector @var{argv} (whose length is @var{argc}).
-The argument @var{shortopts} describes the short options to accept, just as
-it does in @code{getopt}.  The argument @var{longopts} describes the long
-options to accept (see above).
-
-When @code{getopt_long} encounters a short option, it does the same
-thing that @code{getopt} would do: it returns the character code for the
-option, and stores the options argument (if it has one) in @code{optarg}.
-
-When @code{getopt_long} encounters a long option, it takes actions based
-on the @code{flag} and @code{val} fields of the definition of that
-option.
-
-If @code{flag} is a null pointer, then @code{getopt_long} returns the
-contents of @code{val} to indicate which option it found.  You should
-arrange distinct values in the @code{val} field for options with
-different meanings, so you can decode these values after
-@code{getopt_long} returns.  If the long option is equivalent to a short
-option, you can use the short option's character code in @code{val}.
-
-If @code{flag} is not a null pointer, that means this option should just
-set a flag in the program.  The flag is a variable of type @code{int}
-that you define.  Put the address of the flag in the @code{flag} field.
-Put in the @code{val} field the value you would like this option to
-store in the flag.  In this case, @code{getopt_long} returns @code{0}.
-
-For any long option, @code{getopt_long} tells you the index in the array
-@var{longopts} of the options definition, by storing it into
-@code{*@var{indexptr}}.  You can get the name of the option with
-@code{@var{longopts}[*@var{indexptr}].name}.  So you can distinguish among
-long options either by the values in their @code{val} fields or by their
-indices.  You can also distinguish in this way among long options that
-set flags.
-
-When a long option has an argument, @code{getopt_long} puts the argument
-value in the variable @code{optarg} before returning.  When the option
-has no argument, the value in @code{optarg} is a null pointer.  This is
-how you can tell whether an optional argument was supplied.
-
-When @code{getopt_long} has no more options to handle, it returns
-@code{-1}, and leaves in the variable @code{optind} the index in
-@var{argv} of the next remaining argument.
-@end deftypefun
+@menu
+* Getopt::                      Parsing program options using @code{getopt}.
+* Argp::                        Parsing program options using @code{argp_parse}.
+* Suboptions::                  Some programs need more detailed options.
+* Suboptions Example::          This shows how it could be done for @code{mount}.
+@end menu
 
-@node Long Option Example
-@subsection Example of Parsing Long Options
+@c Getopt and argp start at the @section level so that there's
+@c enough room for their internal hierarchy (mostly a problem with
+@c argp).         -Miles
 
-@smallexample
-@include longopt.c.texi
-@end smallexample
+@include getopt.texi
+@include argp.texi
 
-@node Suboptions
-@subsection Parsing of Suboptions
+@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
+@c This is a @section so that it's at the same level as getopt and argp
+@section Parsing of Suboptions
 
 Having a single level of options is sometimes not enough.  There might
 be too many options which have to be available or a set of options is
@@ -452,7 +227,7 @@ possible value is returned in @var{valuep} and the return value of the
 function is @samp{-1}.
 @end deftypefun
 
-@node Suboptions Example
+@node Suboptions Example, , Suboptions, Parsing Program Arguments
 @subsection Parsing of Suboptions Example
 
 The code which might appear in the @code{mount}(8) program is a perfect
@@ -699,7 +474,8 @@ This specifies what locale to use for formatting date/time values.
 @cindex _POSIX_OPTION_ORDER environment variable.
 
 If this environment variable is defined, it suppresses the usual
-reordering of command line arguments by @code{getopt}.  @xref{Argument Syntax}.
+reordering of command line arguments by @code{getopt} and
+@code{argp_parse}.  @xref{Argument Syntax}.
 
 @c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
 @end table
diff --git a/manual/summary.awk b/manual/summary.awk
index d997a2080f..3d4d19ea4a 100644
--- a/manual/summary.awk
+++ b/manual/summary.awk
@@ -1,6 +1,6 @@
 # awk script to create summary.texinfo from the library texinfo files.
 
-# Copyright (C) 1992, 1993 Free Software Foundation, Inc.
+# Copyright (C) 1992, 1993, 1997 Free Software Foundation, Inc.
 # This file is part of the GNU C Library.
 
 # The GNU C Library is free software; you can redistribute it and/or
@@ -86,7 +86,8 @@ print "@c This file is generated by summary.awk from the Texinfo sources."
 $1 == "@node" { node=$2;
 		for (i = 3; i <= NF; ++i)
 		 { node=node " " $i; if ( $i ~ /,/ ) break; }
-	      } 
+		sub (/,[, ]*$/, "", node);
+	      }
 
 $1 == "@comment" && $2 ~ /\.h$/ { header="@file{" $2 "}";
 				  for (i = 3; i <= NF; ++i)
diff --git a/manual/texinfo.tex b/manual/texinfo.tex
index e5982dc386..95c825389d 100644
--- a/manual/texinfo.tex
+++ b/manual/texinfo.tex
@@ -1,5 +1,5 @@
 %% TeX macros to handle Texinfo files.
-%% $Id: texinfo.tex,v 2.200 1997/05/26 22:19:32 drepper Exp $
+%% $Id: texinfo.tex,v 2.201 1997/06/05 11:28:54 drepper Exp $
 
 %  Copyright (C) 1985, 86, 88, 90, 91, 92, 93,
 %                94, 95, 96, 97 Free Software Foundation, Inc.
@@ -36,7 +36,7 @@
 
 % This automatically updates the version number based on RCS.
 \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}}
-\deftexinfoversion$Revision: 2.200 $
+\deftexinfoversion$Revision: 2.201 $
 \message{Loading texinfo package [Version \texinfoversion]:}
 
 % If in a .fmt file, print the version number
@@ -1041,8 +1041,9 @@ where each line of input produces a line of output.}
 % We don't need math for this one.
 \def\ttsl{\tenttsl}
 
-%% Try out Computer Modern fonts at \magstephalf
-\let\mainmagstep=\magstephalf
+% Use Computer Modern fonts at \magstephalf (11pt).
+\newcount\mainmagstep
+\mainmagstep=\magstephalf
 
 % Set the font macro #1 to the font named #2, adding on the
 % specified font prefix (normally `cm').
@@ -1337,8 +1338,9 @@ where each line of input produces a line of output.}
 \else{\tclose{\ttsl\look}}\fi
 \else{\tclose{\ttsl\look}}\fi}
 
-% @url, @email.  Quotes do not seem necessary.
+% @url, @uref, @email.  Quotes do not seem necessary.
 \let\url=\code % perhaps include a hypertex \special eventually
+\let\uref=\code
 % rms does not like the angle brackets --karl, 17may97.
 %\def\email#1{$\langle${\tt #1}$\rangle$}
 \let\email=\code
diff --git a/monetary.h b/monetary.h
new file mode 100644
index 0000000000..4735dc6c8a
--- /dev/null
+++ b/monetary.h
@@ -0,0 +1 @@
+#include <stdlib/monetary.h>
diff --git a/sysexits.h b/sysexits.h
new file mode 100644
index 0000000000..139e3cfa13
--- /dev/null
+++ b/sysexits.h
@@ -0,0 +1 @@
+#include <misc/sysexits.h>