another doc update

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

It's been a while since I've done some patching (I've been tied up with
other things, such as experimenting with git, now that gnulib is
considering moving to git.)  But here's another round of doc merges from
the branch.

I'm liking git, from what I've seen of it over the past two weeks.  If the
gnulib transition from CVS to git is successful (where git becomes the
only writable gnulib repository on savannah, but it remains possible to
check out from a read-only CVS mirror), would it be worth converting m4 to
git as well?

2006-12-04  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Undivert, Divnum, Cleardivert): Merge more doc
        sections.
        (Modules): Make style consistent.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFdCih84KuGfSFAYARAiEZAJ9//CIvrhirRghWJNsDpxuxvwopCACeMZWD
6mapwNPzU7+8JYNQgvx+i7c=
=j3g9
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.80
diff -u -p -r1.80 m4.texinfo
--- doc/m4.texinfo      16 Nov 2006 14:42:37 -0000      1.80
+++ doc/m4.texinfo      4 Dec 2006 13:49:51 -0000
@@ -4483,26 +4483,30 @@ We decided to divert the stream for irri
 @node Undivert
 @section Undiverting output
 
address@hidden {Builtin (m4)} undivert (@address@hidden)
 Diverted text can be undiverted explicitly using the builtin
address@hidden,  which reinserts the diverted output given by the
-arguments into the current output stream, in the order given.  If no
-arguments are supplied, all diversions are undiverted, in numerical
-order.
address@hidden:
 
address@hidden FIXME: Explain what happens when undiverting all to else than 0.
address@hidden {Builtin (m4)} undivert (@address@hidden)
+Undiverts the numeric @var{diversions} given by the arguments, in the
+order given.  If no arguments are supplied, all diversions are
+undiverted, in numerical order.
+
address@hidden @acronym{GNU} extensions
+As a @acronym{GNU} extension, @var{diversions} may contain non-numeric
+strings, which are treated as the names of files to copy into the output
+without expansion.  A warning is issued if a file could not be opened.
 
 The expansion of @code{undivert} is void.
 @end deffn
 
 @example
-divert(1)
+divert(`1')
 This text is diverted.
 divert
 @result{}
 This text is not diverted.
 @result{}This text is not diverted.
-undivert(1)
+undivert(`1')
 @result{}
 @result{}This text is diverted.
 @result{}
@@ -4514,36 +4518,69 @@ following @code{undivert}, the other fro
 
 When diverted text is undiverted, it is @emph{not} reread by @code{m4},
 but rather copied directly to the current output, and it is therefore
-not an error to undivert into a diversion.
+not an error to undivert into a diversion.  Undiverting the empty string
+is the same as specifying diversion 0; in either case nothing happens
+since the output has already been flushed.
+
address@hidden
+divert(`1')diverted text
+divert
address@hidden
+undivert()
address@hidden
+undivert(`0')
address@hidden
+undivert
address@hidden text
address@hidden
address@hidden example
 
 When a diversion has been undiverted, the diverted text is discarded,
 and it is not possible to bring back diverted text more than once.
 
 @example
-divert(1)
+divert(`1')
 This text is diverted first.
-divert(0)undivert(1)dnl
+divert(`0')undivert(`1')dnl
 @result{}
 @result{}This text is diverted first.
-undivert(1)
+undivert(`1')
 @result{}
-divert(1)
+divert(`1')
 This text is also diverted but not appended.
-divert(0)undivert(1)dnl
+divert(`0')undivert(`1')dnl
 @result{}
 @result{}This text is also diverted but not appended.
 @end example
 
-Attempts to undivert the current diversion are silently ignored.
+Attempts to undivert the current diversion are silently ignored.  Thus,
+when the current diversion is not 0, the current diversion does not get
+rearranged among the other diversions.
 
address@hidden GNU extensions
address@hidden
+divert(`1')one
+divert(`2')two
+divert(`3')three
+divert(`4')four
+divert(`5')five
+divert(`2')undivert(`5', `2', `4')dnl
+undivert`'dnl effectively undivert(`1', `2', `3', `4', `5')
+divert`'undivert`'dnl
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden example
+
address@hidden @acronym{GNU} extensions
 @cindex file inclusion
 @cindex inclusion, of files
-GNU @code{m4} allows named files to be undiverted.  Given a non-numeric
-argument, the contents of the file named will be copied, uninterpreted, to
-the current output.  This complements the builtin @code{include}
-(@pxref{Include}).  To illustrate the difference, assume the file
address@hidden contains:
address@hidden @code{m4} allows named files to be undiverted.  Given a
+non-numeric argument, the contents of the file named will be copied,
+uninterpreted, to the current output.  This complements the builtin
address@hidden (@pxref{Include}).  To illustrate the difference, assume
+the file @file{foo} contains:
 
 @comment file: foo
 @example
@@ -4565,21 +4602,38 @@ include(`foo')
 @result{}
 @end example
 
+If the file is not found (or cannot be read), an error message is
+issued, and the expansion is void.  It is possible to intermix files
+and diversion numbers.
+
address@hidden
+divert(`1')diversion one
+divert(`2')undivert(`foo')dnl
+divert(`3')diversion three
+divert`'dnl
+undivert(`1', `2', `foo', `3')dnl
address@hidden one
address@hidden
address@hidden
address@hidden three
address@hidden example
+
 @node Divnum
 @section Diversion numbers
 
 @cindex diversion numbers
+The current diversion is tracked by the builtin @code{divnum}:
+
 @deffn {Builtin (m4)} divnum
-The builtin @code{divnum} expands to the number of the current
-diversion.
+Expands to the number of the current diversion.
 @end deffn
 
 @example
 Initial divnum
 @result{}Initial 0
-divert(1)
+divert(`1')
 Diversion one: divnum
-divert(2)
+divert(`2')
 Diversion two: divnum
 divert
 @result{}
@@ -4590,9 +4644,6 @@ divert
 @result{}Diversion two: 2
 @end example
 
-The last call of @code{divert} without arguments is necessary because the
-undiverted text would otherwise be diverted itself.
-
 @node Cleardivert
 @section Discarding diverted text
 
@@ -4603,14 +4654,14 @@ text is actually needed.  Since all non-
 on the main output stream when the end of input is seen, a method of
 discarding a diversion is needed.  If all diversions should be
 discarded, the easiest is to end the input to @code{m4} with
address@hidden(-1)} followed by an explicit @samp{undivert}:
address@hidden(`-1')} followed by an explicit @samp{undivert}:
 
 @example
-divert(1)
+divert(`1')
 Diversion one: divnum
-divert(2)
+divert(`2')
 Diversion two: divnum
-divert(-1)
+divert(`-1')
 undivert
 ^D
 @end example
@@ -4620,6 +4671,10 @@ No output is produced at all.
 
 Clearing selected diversions can be done with the following macro:
 
address@hidden Composite cleardivert (@address@hidden)
+Discard the contents of each of the listed numeric @var{diversions}.
address@hidden deffn
+
 @example
 define(`cleardivert',
 `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
@@ -4642,14 +4697,14 @@ extreme by hacking the sources and recom
 a custom M4 installation.
 
 Starting with release 2.0, M4 uses Libtool's @code{libltdl} facilities
-(@pxref{Using libltdl, ,libltdl ,libtool , The GNU Libtool Manual})
+(@pxref{Using libltdl, , libltdl, libtool, The GNU Libtool Manual})
 to move all of M4's builtins out to pluggable modules.  Unless compile
 time options are set to change the default build, the installed M4 2.0
 binary is virtually identical to 1.4.x, supporting the same builtins.
 However, an optional module can be loaded into the running M4 interpreter
 to provide a new @code{load} builtin.  This facilitates runtime
 extension of the M4 builtin macro list using compiled C code linked
-against a new @file{libm4.so}.
+against a new shared library, typically named @file{libm4.so}.
 
 For example, you might want to add a @code{setenv} builtin to M4, to
 use before invoking @code{esyscmd}.  We might write a @file{setenv.c}
@@ -4662,11 +4717,11 @@ something like this:
 M4BUILTIN(setenv);
 
 m4_builtin m4_builtin_table[] =
-  @{
-    /* name     handler         macros blind minargs maxargs */
-    @{ "setenv", builtin_setenv, false, false,   3,     4 @},
address@hidden
+  /* name      handler         flags             minargs maxargs */
+  @{ "setenv", builtin_setenv, M4_BUILTIN_BLIND, 2,      3 @},
 
-    @{ NULL,     NULL,           false, false,    0,     0 @}
+  @{ NULL,     NULL,           0,                0,      0 @}
 @};
 
 /**
@@ -4689,9 +4744,11 @@ M4 code:
 
 @comment ignore
 @example
-$ M4MODPATH=`pwd` m4 --load-module=setenv
+$ @kbd{M4MODPATH=`pwd` m4 --load-module=setenv}
 setenv(`PATH', `/sbin:/bin:/usr/sbin:/usr/bin')
-esyscmd(`ifconfig -a')
address@hidden
+esyscmd(`ifconfig -a')dnl
address@hidden@dots{}
 @end example
 
 Or instead of loading the module from the M4 invocation, you can use
@@ -4699,9 +4756,11 @@ the new @code{load} builtin:
 
 @comment ignore
 @example
-$ M4MODPATH=`pwd` m4 --load-module=load
+$ @kbd{M4MODPATH=`pwd` m4 --load-module=load}
 load(`setenv')
address@hidden
 setenv(`PATH', `/sbin:/bin:/usr/sbin:/usr/bin')
address@hidden
 @end example
 
 Also, at build time, you can choose which modules to build into
@@ -4712,13 +4771,13 @@ module @samp{load} and so on.
 
 We hinted earlier that the @code{m4} and @code{gnu} modules are
 preloaded into the installed M4 binary, but it is possible to install
-a @emph{thinner} binary minus GNU extensions, for example, by
-configuring the distribution with @samp{./configure
+a @emph{thinner} binary; for example, omitting the @acronym{GNU}
+extensions by configuring the distribution with @kbd{./configure
 --with-modules=m4}.  For a binary built with that option to understand
-code that uses @acronym{GNU} extensions, you must then run @samp{m4
+code that uses @acronym{GNU} extensions, you must then run @kbd{m4
 --load-module=gnu}.  It is also possible to build a @emph{fatter}
 binary with additional modules preloaded: adding, say, the @code{load}
-builtin using @samp{./configure --with-modules="m4 gnu load"}.
+builtin using @kbd{./configure --with-modules="m4 gnu load"}.
 
 @acronym{GNU} M4 now has a facility for defining additional builtins without
 recompiling the sources.  In actual fact, all of the builtins provided