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
+