Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/12/27 14:14:27

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.86
retrieving revision 1.87
diff -u -b -r1.86 -r1.87
--- doc/m4.texinfo      26 Dec 2006 21:05:53 -0000      1.86
+++ doc/m4.texinfo      27 Dec 2006 14:14:27 -0000      1.87
@@ -5269,7 +5269,7 @@
 @var{substring} does not occur in @var{string}, @code{index} expands to
 @samp{-1}.
 
-The builtin macro @code{index} is recognized only when given arguments.
+The macro @code{index} is recognized only with parameters.
 @end deffn
 
 @example
@@ -5392,21 +5392,36 @@
 
 @cindex extracting substrings
 @cindex substrings, extracting
+Substrings are extracted with @code{substr}:
+
 @deffn {Builtin (m4)} substr (@var{string}, @var{from}, @ovar{length})
-Substrings are extracted with @code{substr}, 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
address@hidden is omitted.  The starting index of a string is always 0.
+Expands to the substring of @var{string}, which starts at index
address@hidden, and extends for @var{length} characters, or to the end of
address@hidden, if @var{length} is omitted.  The starting index of a
+is always 0.  The expansion is empty if there is an error parsing
address@hidden or @var{length}, if @var{from} is beyond the end of
address@hidden, or if @var{length} is negative.
+
+The macro @code{substr} is recognized only with parameters.
address@hidden deffn
 
 @example
-substr(`gnus, gnats, and armadillos', 6)
+substr(`gnus, gnats, and armadillos', `6')
 @result{}gnats, and armadillos
-substr(`gnus, gnats, and armadillos', 6, 5)
+substr(`gnus, gnats, and armadillos', `6', `5')
 @result{}gnats
 @end example
 
-The builtin macro @code{substr} is recognized only when given arguments.
address@hidden deffn
+Omitting @var{from} evokes a warning, but still produces output.
+
address@hidden
+substr(`abc')
address@hidden:stdin:1: Warning: substr: too few arguments: 1 < 2
address@hidden
+substr(`abc',)
address@hidden:stdin:2: Warning: substr: empty string treated as 0
address@hidden
address@hidden example
 
 @node Translit
 @section Translating characters
@@ -5415,7 +5430,7 @@
 @cindex characters, translating
 Character translation is done with @code{translit}:
 
address@hidden {Builtin (m4)} translit (@var{string}, @var{chars}, 
@var{replacement})
address@hidden {Builtin (m4)} translit (@var{string}, @var{chars}, 
@ovar{replacement})
 Expands to @var{string}, with each character that occurs in
 @var{chars} translated into the character from @var{replacement} with
 the same index.
@@ -5481,17 +5496,20 @@
 @cindex regular expressions
 @cindex pattern substitution
 @cindex substitution by regular expression
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
+Global substitution in a string is done by @code{patsubst}:
+
 @deffn {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @
   @ovar{replacement}, @ovar{resyntax})
-Global substitution in a string is done by @code{patsubst}, which
-searches @var{string} for matches of @var{regexp}, and substitutes
+Searches @var{string} for matches of @var{regexp}, and substitutes
 @var{replacement} for each match.
 
-If @var{resyntax} is given, the particular flavor of regular
-expression understood with respect to @var{regexp} can be changed from
-the current default.  @xref{Changeresyntax}, for details of the values
-that can be given for this parameter.
+If @var{resyntax} is given, the particular flavor of regular expression
+understood with respect to @var{regexp} can be changed from the current
+default.  @xref{Changeresyntax}, for details of the values that can be
+given for this argument.  Unlike @var{regexp}, if exactly three
+arguments given, the third argument is always treated as
address@hidden, even if it matches a known syntax name.
 
 The parts of @var{string} that are not covered by any match of
 @var{regexp} are copied to the expansion.  Whenever a match is found, the
@@ -5502,18 +5520,21 @@
 
 When a replacement is to be made, @var{replacement} is inserted into
 the expansion, with @address@hidden substituted by the text matched by
-the @var{n}th parenthesized sub-expression of @var{regexp}, @samp{\&}
-being the text the entire regular expression matched.
+the @var{n}th parenthesized sub-expression of @var{patsubst}, for up to
+nine sub-expressions.  The escape @samp{\&} is replaced by the text of
+the entire regular expression matched.  For all other characters,
address@hidden treats the next character literally.  A warning is issued if
+there were fewer sub-expressions than the @address@hidden requested, or
+if there is a trailing @samp{\}.
 
 The @var{replacement} argument can be omitted, in which case the text
 matched by @var{regexp} is deleted.
 
-The builtin macro @code{patsubst} is recognized only when given
-arguments.
+The macro @code{patsubst} is recognized only with parameters.
 @end deffn
 
-When used with two arguments, while @code{regexp} returns the position
-of the match, @code{patsubst} deletes it:
+When used with two arguments, @code{regexp} returns the position of the
+match, but @code{patsubst} deletes the match:
 
 @example
 patsubst(`GNUs not Unix', `^', `OBS: ')
@@ -5526,12 +5547,24 @@
 @result{}(GNUs) (not) (Unix)
 patsubst(`GNUs not Unix', `[A-Z][a-z]+')
 @result{}GN address@hidden }
+patsubst(`GNUs not Unix', `not', `NOT\')
address@hidden:stdin:6: Warning: patsubst: trailing \ ignored in replacement
address@hidden NOT Unix
 @end example
 
 Here is a slightly more realistic example, which capitalizes individual
 words or whole sentences, by substituting calls of the macros
 @code{upcase} and @code{downcase} into the strings.
 
address@hidden Composite upcase (@var{text})
address@hidden Composite downcase (@var{text})
address@hidden Composite capitalize (@var{text})
+Expand to @var{text}, but with capitalization changed: @code{upcase}
+changes all letters to upper case, @code{downcase} changes all letters
+to lower case, and @code{capitalize} changes the first character of each
+word to upper case and the remaining characters to lower case.
address@hidden deffn
+
 @example
 define(`upcase',   `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
@@ -5559,7 +5592,7 @@
 
 While @code{regexp} replaces the whole input with the replacement as
 soon as there is a match, @code{patsubst} replaces each
address@hidden of a match and preserves non matching pieces:
address@hidden of a match and preserves non-matching pieces:
 
 @example
 define(`patreg',
@@ -5573,6 +5606,14 @@
 @result{}bab
 @end example
 
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+patsubst(`abc')
address@hidden:stdin:1: Warning: patsubst: too few arguments: 1 < 2
address@hidden
address@hidden example
+
 @node Format
 @section Formatting strings (printf-like)