Update.

1998-08-09  Geoff Keating  <geoffk@ozemail.com.au>

	* sysdeps/powerpc/Makefile [subdir=elf]: Add new files split out of
	dl-machine.h.
	* sysdeps/powerpc/dl-machine.c: New file.
	* sysdeps/powerpc/dl-machine.h: Move much stuff into separate
	files.  Revise ELF_PREFERRED_ADDRESS to take account of
	the new mapping information (fixes bug involving huge bloated
	web browser).  Set ELF_MACHINE_PLTREL_OVERLAP.
	* sysdeps/powerpc/dl-start.S: New file.

	* elf/dl-load.c (_dl_map_object_from_fd): Initialise l_map_start,
	l_map_end.
	* elf/do-rel.h: Call elf_machine_rel only once (to save space).
	* elf/dynamic-link.h: Allow PLT relocs to be in the middle of the
	others.  Call elf_dynamic_do_##reloc only once (to save even more
	space).
	* elf/link.h: Add new members l_map_start and l_map_end to keep
	track of the memory map.
	* elf/rtld.c (_dl_start): Initialise l_map_start for ld.so and
	the executable.

1998-09-01 11:53  Ulrich Drepper  <drepper@cygnus.com>

	* debug/Makefile (catchsegv): We need not rewrite SOVER anymore.
	Reported by Andreas Jaeger.

	* posix/glob.h: Use __size_t instead of size_t in definitions and
	make sure this is defined.

	* manual/locale.texi: Almost complete rewrite.  Document more functions

5 files changed, 104 insertions, 5 deletions

diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c
index c87ebbb..50ac0ed 100644
--- a/manual/examples/argp-ex1.c
+++ b/manual/examples/argp-ex1.c
@@ -1,5 +1,10 @@
 /* Argp example #1 -- 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) messages for --help.  */
+
 #include <argp.h>
 
 int main (int argc, char **argv)
diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c
index d1b149b..55f59f2 100644
--- a/manual/examples/argp-ex2.c
+++ b/manual/examples/argp-ex2.c
@@ -1,11 +1,30 @@
 /* Argp example #2 -- a pretty minimal program using argp */
 
+/* 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 --help option, this example will have a
+   --version option, and will put the given documentation string
+   and bug address in the --help output, as per GNU standards.
+
+   The variable ARGP contains the argument parser specification;
+   adding fields to this structure is the way most parameters are
+   passed to 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,
+   ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
+   global variables becuase they will almost always be constant
+   for a given program, even if it uses different argument
+   parsers for various tasks).  */
+
 #include <argp.h>
 
 const char *argp_program_version =
   "argp-ex2 1.0";
 const char *argp_program_bug_address =
-  "<bug-gnu-utils@@prep.ai.mit.edu>";
+  "<bug-gnu-utils@@gnu.org>";
 
 /* Program documentation.  */
 static char doc[] =
diff --git a/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c
index 363ee59..87d993f 100644
--- a/manual/examples/argp-ex3.c
+++ b/manual/examples/argp-ex3.c
@@ -1,11 +1,63 @@
 /* Argp example #3 -- a program with options and arguments using argp */
 
+/* This program uses the same features as example 2, and uses options and
+   arguments.
+
+   We now use the first four fields in ARGP, so here's a description of them:
+     OPTIONS  -- A pointer to a vector of struct argp_option (see below)
+     PARSER   -- A function to parse a single option, called by argp
+     ARGS_DOC -- A string describing how the non-option arguments should look
+     DOC      -- A descriptive string about this program; if it contains a
+                 vertical tab character (\v), the part after it will be
+                 printed *following* the options
+
+   The function PARSER takes the following arguments:
+     KEY  -- An integer specifying which option this is (taken
+             from the KEY field in each struct argp_option), or
+             a special key specifying something else; the only
+             special keys we use here are ARGP_KEY_ARG, meaning
+             a non-option argument, and ARGP_KEY_END, meaning
+             that all argumens have been parsed
+     ARG  -- For an option KEY, the string value of its
+             argument, or NULL if it has none
+     STATE-- A pointer to a struct argp_state, containing
+             various useful information about the parsing state; used here
+             are the INPUT field, which reflects the INPUT argument to
+             argp_parse, and the ARG_NUM field, which is the number of the
+             current non-option argument being parsed
+   It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
+   given KEY wasn't recognized, or an errno value indicating some other
+   error.
+
+   Note that in this example, main uses a structure to communicate with the
+   parse_opt function, a pointer to which it passes in the INPUT argument to
+   argp_parse.  Of course, it's also possible to use global variables
+   instead, but this is somewhat more flexible.
+
+   The OPTIONS field contains a pointer to a vector of struct argp_option's;
+   that structure has the following fields (if you assign your option
+   structures using array initialization like this example, unspecified
+   fields will be defaulted to 0, and need not be specified):
+     NAME   -- The name of this option's long option (may be zero)
+     KEY    -- The KEY to pass to the PARSER function when parsing this option,
+               *and* the name of this option's short option, if it is a
+               printable ascii character
+     ARG    -- The name of this option's argument, if any
+     FLAGS  -- Flags describing this option; some of them are:
+                 OPTION_ARG_OPTIONAL -- The argument to this option is optional
+                 OPTION_ALIAS        -- This option is an alias for the
+                                        previous option
+                 OPTION_HIDDEN       -- Don't show this option in --help output
+     DOC    -- A documentation string for this option, shown in --help output
+
+   An options vector should be terminated by an option with all fields zero. */
+
 #include <argp.h>
 
 const char *argp_program_version =
   "argp-ex3 1.0";
 const char *argp_program_bug_address =
-  "<bug-gnu-utils@@prep.ai.mit.edu>";
+  "<bug-gnu-utils@@gnu.org>";
 
 /* Program documentation.  */
 static char doc[] =
diff --git a/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c
index 24dd417..fa5a8d0 100644
--- a/manual/examples/argp-ex4.c
+++ b/manual/examples/argp-ex4.c
@@ -1,5 +1,28 @@
 /* Argp example #4 -- a program with somewhat more complicated options */
 
+/* This program uses the same features as example 3, but has more
+   options, and somewhat more structure in the -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.  It also shows the special argp KEY value
+   ARGP_KEY_NO_ARGS, which is only given if no non-option
+   arguments were supplied to the program.
+
+   For structuring the help output, two features are used,
+   *headers* which are entries in the options vector with the
+   first four fields being zero, and a two part documentation
+   string (in the variable DOC), which allows documentation both
+   before and after the options; the two parts of DOC are
+   separated by a vertical-tab character ('\v', or '\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 documenation strings are also passed to
+   the `gettext' function, for possible translation into the
+   current locale.  */
+
 #include <stdlib.h>
 #include <error.h>
 #include <argp.h>
diff --git a/manual/startup.texi b/manual/startup.texi
index dd21c89..bea6c39 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -82,7 +82,7 @@ allow this three-argument form, so to be portable it is best to write
 * Parsing Program Arguments::   Ways to parse program options and arguments.
 @end menu
 
-@node Argument Syntax
+@node Argument Syntax, Parsing Program Arguments, , Program Arguments
 @subsection Program Argument Syntax Conventions
 @cindex program argument syntax
 @cindex syntax, for program arguments
@@ -154,7 +154,7 @@ accept an argument that is itself optional.
 Eventually, the GNU system will provide completion for long option names
 in the shell.
 
-@node Parsing Program Arguments
+@node Parsing Program Arguments, , Argument Syntax, Program Arguments
 @subsection Parsing Program Arguments
 
 @cindex program arguments, parsing
@@ -188,7 +188,7 @@ it does more of the dirty work for you.
 
 @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
+@subsubsection 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