Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      06/07/13 13:38:20

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.38
retrieving revision 1.1.1.1.2.39
diff -u -b -r1.1.1.1.2.38 -r1.1.1.1.2.39
--- doc/m4.texinfo      12 Jul 2006 13:27:26 -0000      1.1.1.1.2.38
+++ doc/m4.texinfo      13 Jul 2006 13:38:20 -0000      1.1.1.1.2.39
@@ -418,7 +418,8 @@
 @item -Q
 @itemx --quiet
 @itemx --silent
-Suppress warnings about missing or superfluous arguments in macro calls.
+Suppress warnings, such as missing or superfluous arguments in macro
+calls, or treating the empty string as zero.
 
 @item -W @var{REGEXP}
 @itemx address@hidden
@@ -553,7 +554,7 @@
 scripts.
 
 @table @code
address@hidden address@hidden
address@hidden address@hidden
 @itemx address@hidden
 Set the debug-level according to the flags @var{FLAGS}.  The debug-level
 controls the format and amount of information presented by the debugging
@@ -644,6 +645,7 @@
 @error{}and an error message
 @end example
 
+The sequence @samp{^D} in an example indicates the end of the input file.
 The majority of these examples are self-contained, and you can run them
 with similar results by invoking @kbd{m4 -d}.  In fact, the testsuite
 that is bundled in the GNU M4 package consists of the examples in this
@@ -658,8 +660,15 @@
 regexp(@var{string}, @var{regexp}, opt @var{replacement})
 @end example
 
-All macro arguments in @code{m4} are strings, but some are given special
-interpretation, e.g., as numbers, file names, regular expressions, etc.
+All macro arguments in @code{m4} are strings, but some are given
+special interpretation, e.g., as numbers, file names, regular
+expressions, etc.  The documentation for each macro will state how the
+parameters are interpreted, and what happens if the argument cannot be
+parsed according to the desired interpretation.  Unless specified
+otherwise, a parameter specified to be a number is parsed as a decimal,
+even if the argument has leading zeros; and parsing the empty string as
+a number results in 0 rather than an error, although a warning will be
+issued.
 
 The @samp{opt} before the third argument shows that this argument is
 optional---if it is left out, it is taken to be the empty string.  An
@@ -1638,6 +1647,9 @@
 @result{}
 ifdef(`foo', ``foo' is defined', ``foo' is not defined')
 @result{}foo is defined
+ifdef(`no_such_macro', `yes', `no', `extra argument')
address@hidden:4: m4: Warning: excess arguments to builtin `ifdef' ignored
address@hidden
 @end example
 
 The macro @code{ifdef} is recognized only with parameters.
@@ -2649,7 +2661,8 @@
 
 @noindent
 where @var{number} is the diversion to be used.  If @var{number} is left
-out, it is assumed to be zero.
+out or empty, it is assumed to be zero.  If @var{number} cannot be
+parsed, the diversion is unchanged.
 
 The expansion of @code{divert} is void.
 
@@ -3007,7 +3020,8 @@
 which expands to the substring of @var{string}, which starts at index
 @var{from}, and extends for @var{length} characters, or to the end of
 @var{string}, if @var{length} is omitted.  The starting index of a string
-is always 0.
+is always 0.  The expansion is empty if there is an error parsing
address@hidden or @var{length}.
 
 @example
 substr(`gnus, gnats, and armadillos', `6')
@@ -3233,13 +3247,20 @@
 
 @noindent
 which expand to the numerical value of @var{number}, incremented,
-or decremented, respectively, by one.
+or decremented, respectively, by one.  Except for the empty string, the
+expansion is empty if @var{number} could not be parsed.
 
 @example
 incr(`4')
 @result{}5
 decr(`7')
 @result{}6
+incr()
address@hidden:3: m4: empty string treated as 0 in builtin `incr'
address@hidden
+decr()
address@hidden:4: m4: empty string treated as 0 in builtin `decr'
address@hidden
 @end example
 
 The builtin macros @code{incr} and @code{decr} are recognized only when
@@ -3260,7 +3281,8 @@
 @end example
 
 @noindent
-which expands to the value of @var{expression}.
+which expands to the value of @var{expression}.  The expansion is empty
+if an error is encountered while parsing the arguments.
 
 Expressions can contain the following operators, listed in order of
 decreasing precedence.
@@ -3305,12 +3327,15 @@
 version to match @acronym{POSIX}, so use parentheses to force the
 desired precedence.
 
-Numbers without special prefix are given decimal.  A simple @samp{0}
+Within @var{expression}, (but not @var{radix} or @var{width}),
+numbers without a special prefix are decimal.  A simple @samp{0}
 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,
-then the digits making the number.  For any radix, the digits are
+then the digits making the number.  For radix 1, leading zeros are
+ignored and all remaining digits must be @samp{1}; for all other
+radices, the digits are
 @samp{0}, @samp{1}, @samp{2}, @dots{}.  Beyond @samp{9}, the digits are
 @samp{a}, @samp{b} @dots{} up to @samp{z}.  Lower and upper case letters
 can be used interchangeably in numbers prefixes and as number digits.
@@ -3326,6 +3351,8 @@
 @result{}-15
 eval(index(`Hello world', `llo') >= 0)
 @result{}1
+eval(`0r1:0111 + 0b100 + 0r3:12')
address@hidden
 define(`square', `eval(`('$1`)**2')')
 @result{}
 square(`9')
@@ -3335,7 +3362,7 @@
 define(`foo', `666')
 @result{}
 eval(`foo/6')
address@hidden:7: m4: bad expression in eval: foo/6
address@hidden:8: m4: bad expression in eval: foo/6
 @result{}
 eval(foo/6)
 @result{}111
@@ -3365,10 +3392,15 @@
 @end example
 
 If @var{radix} is specified, it specifies the radix to be used in the
-expansion.  The default radix is 10.  The result of @code{eval} is
-always taken to be signed.  The @var{width} argument specifies a minimum
-output width.  The result is zero-padded to extend the expansion to the
-requested width.
+expansion.  The default radix is 10; this is also the case if
address@hidden is the empty string.  It is an error if the radix is outside
+the range of 1 through 36, inclusive.  The result of @code{eval} is
+always taken to be signed.  No radix prefix is output, and for radices
+greater than 10, the digits are lower case.  The @var{width} argument
+specifies the minimum output width, excluding any negative sign.  The
+result is zero-padded to extend the expansion to the requested width.
+It is an error if the width is negative.  On error, the expansion of
address@hidden is empty.
 
 @example
 eval(`666', `10')
@@ -3380,11 +3412,15 @@
 eval(`666', `6', `10')
 @result{}0000003030
 eval(`-666', `6', `10')
address@hidden
address@hidden
+eval(`10', `', `0')
address@hidden
+`0r1:'eval(`10', `1', `11')
address@hidden:01111111111
+eval(`10', `16')
address@hidden
 @end example
 
-Take note that @var{radix} cannot be larger than 36.
-
 The builtin macro @code{eval} is recognized only when given arguments.
 
 @node Shell commands
@@ -4209,6 +4245,11 @@
 @code{m4} treats the shift operators @samp{<<} and @samp{>>} as
 well-defined on signed integers (even though they are not in C), and
 adds the exponentiation operator @samp{**}.
+
address@hidden
address@hidden requires @code{translit} (@pxref{Translit}) to treat
+each character of the second and third arguments literally, but GNU
address@hidden treats @samp{-} as a range operator.
 @end itemize
 
 @node Other Incompatibilities