FYI: doc formatting, new tests

[Eric Blake]

I noticed some `a' vs. `an' errors, and silenced some overfull hbox
warnings from texi2dvi.  Then I noticed that several of the commented
examples were not consistent with existing examples, and that our
testsuite didn't exercise maketemp.

I'm not sure if it is worth trying to make the testsuite check that
changeword works as advertised when m4 is configured with
--enable-changeword, since CVS head dropped this experimental
feature.

I also found another POSIX incompatibility - Solaris m4 follows
POSIX on maketemp, and replaces the trailing XXX with the process
id without creating a file (meaning that multiple uses of maketemp
on the same string give the same result), whereas we are
treating it more like mkstemp and actually creating a secure
file with a unique name each time.  Perhaps, for POSIX compliance,
we should make maketemp match Solaris behavior, and add a new
macro makestemp that does the current maketemp behavior.  Should
we be documenting known incompatibilities with POSIX in the
1.4.x branch, or just wait for 2.0 to worry about them?

2006-05-27  Eric Blake  <address@hidden>

        * doc/m4.texinfo: Fix usage of a vs. an.
        (Loops, Include, Cleardiv, Patsubst, Format, M4exit): Kill
        overfull hbox warnings.
        (Inhibiting Invocation, Divert, Maketemp, M4exit): Add new tests.

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.11
diff -u -p -r1.1.1.1.2.11 m4.texinfo
--- doc/m4.texinfo      26 May 2006 04:13:27 -0000      1.1.1.1.2.11
+++ doc/m4.texinfo      28 May 2006 03:31:52 -0000
@@ -329,7 +329,7 @@ Print the version number of the program 
 immediately exit @code{m4} without reading any @var{input-files}.
 
 @item --help
-Print an help summary on standard output, then immediately exit
+Print a help summary on standard output, then immediately exit
 @code{m4} without reading any @var{input-files}.
 
 @item -G
@@ -771,11 +771,13 @@ The output of macro evaluations is alway
 example would yield the string @samp{de}, exactly as if @code{m4}
 has been given @address@hidden(abcde, 3, 2)}} as input:
 
address@hidden ignore
 @example
 define(`x', `substr(ab')
address@hidden
 define(`y', `cde, 3, 2)')
address@hidden
 x`'y
address@hidden
 @end example
 
 Unquoted strings on either side of a quoted string are subject to
@@ -953,7 +955,7 @@ The macro @code{define} is recognized on
 @cindex Arguments to macros
 Macros can have arguments.  The @var{n}th argument is denoted by
 @code{$n} in the expansion text, and is replaced by the @var{n}th actual
-argument, when the macro is expanded.  Here is a example of a macro with
+argument, when the macro is expanded.  Here is an example of a macro with
 two arguments.  It simply exchanges the order of the two arguments.
 
 @example
@@ -1501,10 +1503,10 @@ Here is the actual implementation of @co
 @comment ignore
 @example
 define(`forloop',
-       `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
+       `pushdef(`$1', `$2')_forloop(`$1',`$2',`$3',`$4')popdef(`$1')')
 define(`_forloop',
        `$4`'ifelse($1, `$3', ,
-                  `define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')
+                  `define(`$1', incr($1))_forloop(`$1',`$2',`$3',`$4')')')
 @end example
 
 Notice the careful use of quotes.  Only three macro arguments are
@@ -1913,8 +1915,9 @@ apply translations to a file of numbers:
 @comment ignore
 @example
 changeword(`[_a-zA-Z0-9]+')
-define(1, 0)
address@hidden
address@hidden
+define(1, 0)1
address@hidden
 @end example
 
 Tightening the lexical rules is less useful, because it will generally
@@ -1924,9 +1927,14 @@ accidental call of builtins, for example
 @comment ignore
 @example
 define(`_indir', defn(`indir'))
address@hidden
 changeword(`_[_a-zA-Z0-9]*')
address@hidden
 esyscmd(foo)
-_indir(`esyscmd', `ls')
address@hidden(foo)
+_indir(`esyscmd', `echo hi')
address@hidden
address@hidden
 @end example
 
 Because @code{m4} constructs its words a character at a time, there
@@ -1935,14 +1943,17 @@ is a restriction on the regular expressi
 @samp{foo}, it must also accept @samp{f} and @samp{fo}.
 
 @code{changeword} has another function.  If the regular expression
-supplied contains any bracketed subexpressions, then text outside
+supplied contains any grouped subexpressions, then text outside
 the first of these is discarded before symbol lookup.  So:
 
 @comment ignore
 @example
-changecom(`/*', `*/')
+changecom(`/*', `*/')dnl
+define(`foo', `bar')dnl
 changeword(`#\([_a-zA-Z0-9]*\)')
-#esyscmd(ls)
address@hidden
+#esyscmd(`echo foo')
address@hidden
 @end example
 
 @code{m4} now requires a @samp{#} mark at the beginning of every
@@ -1960,8 +1971,9 @@ First, the @TeX{} version:
 address@hidden@address@hidden@}
 \catcode`\@@=0
 \catcode`\\=12
address@hidden@@a
address@hidden@@bye
+@@a
+@@bye
address@hidden
 @end example
 
 @noindent
@@ -1969,9 +1981,10 @@ Then, the @code{m4} version:
 
 @comment ignore
 @example
-define(a, `errprint(`Hello')')
+define(a, `errprint(`Hello')')dnl
 changeword(`@@\([_a-zA-Z0-9]*\)')
address@hidden@@a
+@@a
address@hidden(Hello)
 @end example
 
 In the @TeX{} example, the first line defines a macro @code{a} to
@@ -2072,10 +2085,10 @@ be used to include a file, if it exists,
 does not.
 
 @example
-include(`no-such-file')
+include(`none')
 @result{}
address@hidden:2: m4: Cannot open no-such-file: No such file or directory
-sinclude(`no-such-file')
address@hidden:2: m4: Cannot open none: No such file or directory
+sinclude(`none')
 @result{}
 @end example
 
@@ -2207,7 +2220,20 @@ This text is not diverted.
 @end example
 
 Several calls of @code{divert} with the same argument do not overwrite
-the previous diverted text, but append to it.
+the previous diverted text, but append to it.  Diversions are printed
+after any wrapped text is expanded.
+
address@hidden
+define(`text', `TEXT')
address@hidden
+divert(`1')`diverted text.'
+divert
address@hidden
+m4wrap(`Wrapped text preceeds ')
address@hidden
+^D
address@hidden TEXT preceeds diverted text.
address@hidden example
 
 If output is diverted to a non-existent diversion, it is simply
 discarded.  This can be used to suppress unwanted output.  A common
@@ -2369,7 +2395,7 @@ Clearing selected diversions can be done
 
 @example
 define(`cleardivert',
-`pushdef(`_num', divnum)divert(-1)undivert($@@)divert(_num)popdef(`_num')')
+`pushdef(`_n', divnum)divert(-1)undivert($@@)divert(_n)popdef(`_n')')
 @result{}
 @end example
 
@@ -2626,9 +2652,10 @@ word or whole sentences, by substituting
 define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
 define(`capitalize1',
-     `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
+       `regexp(`$1', `^\(\w\)\(\w*\)',
+               `upcase(`\1')`'downcase(`\2')')')dnl
 define(`capitalize',
-     `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
+       `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
 capitalize(`GNUs not Unix')
 @result{}Gnus Not Unix
 @end example
@@ -2660,8 +2687,8 @@ Its use is best described by a few examp
 @example
 define(`foo', `The brown fox jumped over the lazy dog')
 @result{}
-format(`The string "%s" is %d characters long', foo, len(foo))
address@hidden string "The brown fox jumped over the lazy dog" is 38 characters 
long
+format(`The string "%s" uses %d characters', foo, len(foo))
address@hidden string "The brown fox jumped over the lazy dog" uses 38 
characters
 @end example
 
 Using the @code{forloop} macro defined in @xref{Loops}, this
@@ -2794,7 +2821,7 @@ bitwise exclusive-or.  GNU @code{m4} cha
 exponentiate for @samp{^}, it now computes the bitwise exclusive-or.
 
 Numbers without special prefix are given decimal.  A simple @samp{0}
-prefix introduces an octal number.  @samp{0x} introduces an hexadecimal
+prefix introduces an octal number.  @samp{0x} introduces a hexadecimal
 number.  @samp{0b} introduces a binary number.  @samp{0r} introduces a
 number expressed in any radix between 1 and 36: the prefix should be
 immediately followed by the decimal expression of the radix, a colon,
@@ -2995,6 +3022,26 @@ maketemp(`/tmp/fooXXXXXX')
 @result{}/tmp/fooa07346
 @end example
 
address@hidden
address@hidden FIXME: POSIX requires maketemp to replace the trailing XXX with 
the
address@hidden process id, without creating the file; meaning you only get one
address@hidden string no matter how many times you use maketemp.  Instead, we 
treat
address@hidden it like mkstemp(), and create a unique file every invocation.
+
address@hidden This test makes sure maketemp gets testsuite coverage, but is
address@hidden somewhat complex for use in the manual.
address@hidden
+define(`file1', maketemp(`./fooXXXXXX'))dnl
+define(`file2', maketemp(`./fooXXXXXX'))dnl
+ifelse(file1, file2, `same', `different')
address@hidden
+syscmd(`rm 'file1 file2)
address@hidden
+sysval
address@hidden
address@hidden example
address@hidden ignore
+
 The builtin macro @code{maketemp} is recognized only when given
 arguments.
 
@@ -3077,11 +3124,12 @@ which causes @code{m4} to exit, with exi
 @var{code} is left out, the exit code is zero.
 
 @example
-define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
+define(`fatal_error',
+       `errprint(`m4: '__file__: __line__`: fatal error: $*
 ')m4exit(1)')
 @result{}
 fatal_error(`This is a BAD one, buster')
address@hidden: m4.input: 5: fatal error: This is a BAD one, buster
address@hidden: m4.input: 6: fatal error: This is a BAD one, buster
 @end example
 
 After this macro call, @code{m4} will exit with exit code 1.  This macro
@@ -3089,6 +3137,15 @@ is only intended for error exits, since 
 not followed, e.g., diverted text is not undiverted, and saved text
 (@pxref{M4wrap}) is not reread.
 
address@hidden
+m4wrap(`This text is lost to `m4exit'.')
address@hidden
+divert(`1') And so is this.
+divert
address@hidden
+m4exit
address@hidden example
+
 @node Frozen files, Compatibility, Miscellaneous, Top
 @chapter Fast loading of frozen states