[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

FYI: doc formatting, new tests

From: Eric Blake
Subject: FYI: doc formatting, new tests
Date: Sun, 28 May 2006 03:32:35 +0000

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

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
diff -u -p -r1. m4.texinfo
--- doc/m4.texinfo      26 May 2006 04:13:27 -0000
+++ 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
 define(`x', `substr(ab')
 define(`y', `cde, 3, 2)')
 @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.
@@ -1501,10 +1503,10 @@ Here is the actual implementation of @co
 @comment ignore
-       `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
+       `pushdef(`$1', `$2')_forloop(`$1',`$2',`$3',`$4')popdef(`$1')')
        `$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
-define(1, 0)
+define(1, 0)1
 @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
 define(`_indir', defn(`indir'))
-_indir(`esyscmd', `ls')
+_indir(`esyscmd', `echo hi')
 @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
-changecom(`/*', `*/')
+changecom(`/*', `*/')dnl
+define(`foo', `bar')dnl
+#esyscmd(`echo foo')
 @end example
 @code{m4} now requires a @samp{#} mark at the beginning of every
@@ -1960,8 +1971,9 @@ First, the @TeX{} version:
 @end example
@@ -1969,9 +1981,10 @@ Then, the @code{m4} version:
 @comment ignore
-define(a, `errprint(`Hello')')
+define(a, `errprint(`Hello')')dnl
 @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.
address@hidden:2: m4: Cannot open no-such-file: No such file or directory
address@hidden:2: m4: Cannot open none: No such file or directory
 @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.
+define(`text', `TEXT')
+divert(`1')`diverted text.'
+m4wrap(`Wrapped text preceeds ')
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
-`pushdef(`_num', divnum)divert(-1)undivert($@@)divert(_num)popdef(`_num')')
+`pushdef(`_n', divnum)divert(-1)undivert($@@)divert(_n)popdef(`_n')')
 @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
-     `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
+       `regexp(`$1', `^\(\w\)\(\w*\)',
+               `upcase(`\1')`'downcase(`\2')')')dnl
-     `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
 define(`foo', `The brown fox jumped over the lazy dog')
-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 
+format(`The string "%s" uses %d characters', foo, len(foo))
address@hidden string "The brown fox jumped over the lazy dog" uses 38 
 @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')
 @end example
address@hidden FIXME: POSIX requires maketemp to replace the trailing XXX with 
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 
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.
+define(`file1', maketemp(`./fooXXXXXX'))dnl
+define(`file2', maketemp(`./fooXXXXXX'))dnl
+ifelse(file1, file2, `same', `different')
+syscmd(`rm 'file1 file2)
address@hidden example
address@hidden ignore
 The builtin macro @code{maketemp} is recognized only when given
@@ -3077,11 +3124,12 @@ which causes @code{m4} to exit, with exi
 @var{code} is left out, the exit code is zero.
-define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
+       `errprint(`m4: '__file__: __line__`: fatal error: $*
 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.
+m4wrap(`This text is lost to `m4exit'.')
+divert(`1') And so is this.
address@hidden example
 @node Frozen files, Compatibility, Miscellaneous, Top
 @chapter Fast loading of frozen states

reply via email to

[Prev in Thread] Current Thread [Next in Thread]