Re: another doc update

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 12/4/2006 6:54 AM:
> It's been a while since I've done some patching (I've been tied up with
> other things, such as experimenting with git, now that gnulib is
> considering moving to git.)  But here's another round of doc merges from
> the branch.

Still more progress.  The regexp tests are beefed up to catch more
regression scenarios.

2006-12-21  Eric Blake  <address@hidden>

        * doc/m4.texinfo (Len, Index macro, Regexp): More section merging
        from branch.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFipcA84KuGfSFAYARAjc5AJ9NNf3Z7cExrzwgv5m7FJcdnE+RrQCg1d+Q
fjNIOcu5aJ8dadA1ycSsjlg=
=rbL0
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.82
diff -u -p -r1.82 m4.texinfo
--- doc/m4.texinfo      9 Dec 2006 16:53:28 -0000       1.82
+++ doc/m4.texinfo      21 Dec 2006 14:14:46 -0000
@@ -4936,11 +4936,12 @@ various ways, extracting substrings, sea
 
 @cindex length of strings
 @cindex strings, length of
+The length of a string can be calculated by @code{len}:
+
 @deffn {Builtin (m4)} len (@var{string})
-The length of a string can be calculated by @code{len},
-which expands to the length of @var{string}, as a decimal number.
+Expands to the length of @var{string}, as a decimal number.
 
-The builtin macro @code{len} is recognized only when given arguments.
+The macro @code{len} is recognized only with parameters.
 @end deffn
 
 @example
@@ -4953,9 +4954,10 @@ len(`abcdef')
 @node Index macro
 @section Searching for substrings
 
+Searching for substrings is done with @code{index}:
+
 @deffn {Builtin (m4)} index (@var{string}, @var{substring})
-Searching for substrings is done with @code{index},
-which expands to the index of the first occurrence of @var{substring} in
+Expands to the index of the first occurrence of @var{substring} in
 @var{string}.  The first character in @var{string} has index 0.  If
 @var{substring} does not occur in @var{string}, @code{index} expands to
 @samp{-1}.
@@ -4970,30 +4972,49 @@ index(`gnus, gnats, and armadillos', `da
 @result{}-1
 @end example
 
+Omitting @var{substring} evokes a warning, but still produces output.
+
address@hidden
+index(`abc')
address@hidden:stdin:1: Warning: index: too few arguments: 1 < 2
address@hidden
address@hidden example
+
 @node Regexp
 @section Searching for regular expressions
 
 @cindex regular expressions
address@hidden GNU extensions
address@hidden @acronym{GNU} extensions
+Searching for regular expressions is done with the builtin
address@hidden:
+
 @deffn {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @var{resyntax})
 @deffnx {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @
   @ovar{replacement}, @ovar{resyntax})
-Searching for regular expressions is done with the builtin
address@hidden, which searches for @var{regexp} in @var{string}.  The
-syntax of regular expressions is similar to that of Perl, @acronym{GNU} Awk
-and Egrep: so called ``Extended Regular Expression''.
+Searches for @var{regexp} in @var{string}.
+
+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.  If exactly three arguments given, then the
+third argument is treated as @var{resyntax} only if it matches a known
+syntax name, otherwise it is treated as @var{replacement}.
 
 If @var{replacement} is omitted, @code{regexp} expands to the index of
-the first match of @var{regexp} in @var{string}.  If @var{replacement}
-is specified and matches, then it expands into @var{replacement}. If
address@hidden does not match anywhere in @var{string}, it expands to -1.
+the first match of @var{regexp} in @var{string}.  If @var{regexp} does
+not match anywhere in @var{string}, it expands to -1.
 
-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.
+If @var{replacement} is supplied, and there was a match, @code{regexp}
+changes the expansion to this argument, with @address@hidden substituted
+by the text matched by the @var{n}th parenthesized sub-expression of
address@hidden, up to nine sub-expressions.  The escape @samp{\&} is
+replaced by the text of the entire regular expression matched.  For
+all other characters, @samp{\} treats the next character literally.  A
+warning is issued if there were fewer sub-expressions than the
address@hidden@var{n}} requested, or if there is a trailing @samp{\}.  If there
+was no match, @code{regexp} expands to the empty string.
 
-The builtin macro @code{regexp} is recognized only when given arguments.
+The macro @code{regexp} is recognized only with parameters.
 @end deffn
 
 @example
@@ -5001,16 +5022,34 @@ regexp(`GNUs not Unix', `\<[a-z]\w+')
 @result{}5
 regexp(`GNUs not Unix', `\<Q\w*')
 @result{}-1
+regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
address@hidden Unix *** nix ***
+regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
address@hidden
 @end example
 
-If @var{replacement} is supplied, @code{regexp} changes the expansion
-to this argument, with @address@hidden substituted by the text
-matched by the @var{n}th parenthesized sub-expression of @var{regexp},
address@hidden&} being the text the entire regular expression matched.
+Here are some more examples on the handling of backslash:
 
 @example
-regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
address@hidden Unix *** nix ***
+regexp(`abc', `\(b\)', `\\\10\a')
address@hidden
+regexp(`abc', `b', `\1\')
address@hidden:stdin:2: Warning: regexp: sub-expression 1 not present
address@hidden:stdin:2: Warning: regexp: trailing \ ignored in replacement
address@hidden
+regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
address@hidden:stdin:3: Warning: regexp: sub-expression 4 not present
address@hidden:stdin:3: Warning: regexp: sub-expression 5 not present
address@hidden:stdin:3: Warning: regexp: sub-expression 6 not present
address@hidden
address@hidden example
+
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+regexp(`abc')
address@hidden:stdin:1: Warning: regexp: too few arguments: 1 < 2
address@hidden
 @end example
 
 If @var{resyntax} is given, @var{regexp} must be given according to
@@ -5021,16 +5060,24 @@ remains unchanged for other invocations:
 regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***',
        `POSIX_EXTENDED')
 @result{}*** Unix *** nix ***
+regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***')
address@hidden
 @end example
 
-Occasionally, you might want to pass an @var{resyntax} argument
-without wishing to give @var{replacement}.  If the @strong{last}
-argument is a valid @var{resyntax} it is used as such whether
-or not a @var{replacement} argument is also given:
+Occasionally, you might want to pass an @var{resyntax} argument without
+wishing to give @var{replacement}.  If there are exactly three
+arguments, and the last argument is a valid @var{resyntax}, it is used
+as such, rather than as a replacement.
 
 @example
 regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED')
 @result{}9
+regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED', `POSIX_EXTENDED')
address@hidden
+regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED', `')
address@hidden
+regexp(`GNUs not Unix', `\w\(\w+\)$', `POSIX_EXTENDED', `')
address@hidden
 @end example
 
 @node Substr