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 <[EMAIL PROTECTED]>
* 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 @[EMAIL PROTECTED](abcde, 3, 2)}} as input:
[EMAIL PROTECTED] ignore
@example
define(`x', `substr(ab')
[EMAIL PROTECTED]
define(`y', `cde, 3, 2)')
[EMAIL PROTECTED]
x`'y
[EMAIL PROTECTED]
@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)
[EMAIL PROTECTED]
[EMAIL PROTECTED]
+define(1, 0)1
[EMAIL PROTECTED]
@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'))
[EMAIL PROTECTED]
changeword(`_[_a-zA-Z0-9]*')
[EMAIL PROTECTED]
esyscmd(foo)
-_indir(`esyscmd', `ls')
[EMAIL PROTECTED](foo)
+_indir(`esyscmd', `echo hi')
[EMAIL PROTECTED]
[EMAIL PROTECTED]
@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)
[EMAIL PROTECTED]
+#esyscmd(`echo foo')
[EMAIL PROTECTED]
@end example
@code{m4} now requires a @samp{#} mark at the beginning of every
@@ -1960,8 +1971,9 @@ First, the @TeX{} version:
[EMAIL PROTECTED]@[EMAIL PROTECTED]@}
\catcode`\@@=0
\catcode`\\=12
[EMAIL PROTECTED]@@a
[EMAIL PROTECTED]@@bye
+@@a
+@@bye
[EMAIL PROTECTED]
@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]*\)')
[EMAIL PROTECTED]@@a
+@@a
[EMAIL PROTECTED](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{}
[EMAIL PROTECTED]:2: m4: Cannot open no-such-file: No such file or directory
-sinclude(`no-such-file')
[EMAIL PROTECTED]: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.
+
[EMAIL PROTECTED]
+define(`text', `TEXT')
[EMAIL PROTECTED]
+divert(`1')`diverted text.'
+divert
[EMAIL PROTECTED]
+m4wrap(`Wrapped text preceeds ')
[EMAIL PROTECTED]
+^D
[EMAIL PROTECTED] TEXT preceeds diverted text.
[EMAIL PROTECTED] 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))
[EMAIL PROTECTED] string "The brown fox jumped over the lazy dog" is 38
characters long
+format(`The string "%s" uses %d characters', foo, len(foo))
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]
[EMAIL PROTECTED] FIXME: POSIX requires maketemp to replace the trailing XXX
with the
[EMAIL PROTECTED] process id, without creating the file; meaning you only get
one
[EMAIL PROTECTED] string no matter how many times you use maketemp. Instead,
we treat
[EMAIL PROTECTED] it like mkstemp(), and create a unique file every invocation.
+
[EMAIL PROTECTED] This test makes sure maketemp gets testsuite coverage, but is
[EMAIL PROTECTED] somewhat complex for use in the manual.
[EMAIL PROTECTED]
+define(`file1', maketemp(`./fooXXXXXX'))dnl
+define(`file2', maketemp(`./fooXXXXXX'))dnl
+ifelse(file1, file2, `same', `different')
[EMAIL PROTECTED]
+syscmd(`rm 'file1 file2)
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
[EMAIL PROTECTED] 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')
[EMAIL PROTECTED]: m4.input: 5: fatal error: This is a BAD one, buster
[EMAIL PROTECTED]: 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.
[EMAIL PROTECTED]
+m4wrap(`This text is lost to `m4exit'.')
[EMAIL PROTECTED]
+divert(`1') And so is this.
+divert
[EMAIL PROTECTED]
+m4exit
[EMAIL PROTECTED] example
+
@node Frozen files, Compatibility, Miscellaneous, Top
@chapter Fast loading of frozen states
_______________________________________________
M4-patches mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/m4-patches
