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>      07/08/09 13:39:10

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.132
retrieving revision 1.1.1.1.2.133
diff -u -b -r1.1.1.1.2.132 -r1.1.1.1.2.133
--- doc/m4.texinfo      15 Jul 2007 04:11:10 -0000      1.1.1.1.2.132
+++ doc/m4.texinfo      9 Aug 2007 13:39:09 -0000       1.1.1.1.2.133
@@ -2023,16 +2023,20 @@
 It is possible to rename an already defined macro.  To do this, you need
 the builtin @code{defn}:
 
address@hidden Builtin defn (@var{name})
-Expands to the @emph{quoted definition} of @var{name}.  If the
-argument is not a defined macro, the expansion is void.
address@hidden Builtin defn (@address@hidden)
+Expands to the @emph{quoted definition} of each @var{name}.  If an
+argument is not a defined macro, the expansion for that argument is
+empty.
 
 If @var{name} is a user-defined macro, the quoted definition is simply
-the quoted expansion text.  If, instead, @var{name} is a builtin, the
+the quoted expansion text.  If, instead, there is only one @var{name}
+and it is a builtin, the
 expansion is a special token, which points to the builtin's internal
 definition.  This token is only meaningful as the second argument to
 @code{define} (and @code{pushdef}), and is silently converted to an
-empty string in most other contexts.
+empty string in most other contexts.  Combining a builtin with anything
+else is not supported; a warning is issued and the builtin is omitted
+from the final expansion.
 
 The macro @code{defn} is recognized only with parameters.
 @end deffn
@@ -2103,6 +2107,34 @@
 @result{}AA'
 @end example
 
+On the other hand, it is possible to exploit the fact that @code{defn}
+can concatenate multiple macros prior to the rescanning phase, in order
+to join the definitions of macros that, in isolation, have unbalanced
+quotes.  In the example below, note how the use of @code{defn} on
address@hidden in isolation opens a string, which is not closed until the next
+line; but used on @code{l} and @code{r} together results in nested
+quoting.  Also note that @code{defn} with multiple arguments can only
+join text macros, not builtins, although a future version of
address@hidden M4 may lift this restriction.
+
address@hidden
+define(`l', `<[>')define(`r', `<]>')
address@hidden
+changequote(`[', `]')
address@hidden
+defn([l])defn([r])
+])
address@hidden<[>]defn([r])
address@hidden)
+defn([l], [r])
address@hidden<[>][<]>
+define([a], [A])
address@hidden
+defn([a], [defn], [a])
address@hidden:stdin:7: Warning: cannot concatenate builtin `defn'
address@hidden
address@hidden example
+
 @cindex builtins, special tokens
 @cindex tokens, builtin macro
 Using @code{defn} to generate special tokens for builtin macros outside
@@ -6167,18 +6199,21 @@
 
 @itemize @bullet
 @item
-System V @code{m4} supports multiple arguments to @code{defn}, and
address@hidden requires it.  This is not yet implemented in @acronym{GNU}
address@hidden  Unfortunately, this means it is not possible to mix builtins
-and other text into a single macro; a helper macro is required.
address@hidden requires support for multiple arguments to @code{defn},
+without any clarification on how @code{defn} behaves when one of the
+multiple arguments names a builtin.  System V @code{m4} and some other
+implementations allow mixing builtins and text macros into a single
+macro.  @acronym{GNU} @code{m4} only supports joining multiple text
+arguments, although a future implementation may lift this restriction to
+behave more like System V.  The only portable way to join text macros
+with builtins is via helper macros and implicit concatenation of macro
+results.
 
 @item
 @acronym{POSIX} requires an application to exit with non-zero status if
 it wrote an error message to stderr.  This has not yet been consistently
 implemented for the various builtins that are required to issue an error
-(such as @code{include} (@pxref{Include}) when a file is unreadable,
address@hidden (@pxref{Eval}) when an argument cannot be parsed, or using
address@hidden (@pxref{M4exit}) with a non-numeric argument).
+(such as @code{eval} (@pxref{Eval}) when an argument cannot be parsed).
 
 @item
 Some traditional implementations only allow reading standard input
@@ -6234,12 +6269,12 @@
 @code{pushdef(`f',`1')}.  @acronym{POSIX} allows either behavior.
 
 @item
address@hidden requires @code{syscmd} (@pxref{Syscmd}) to evaluate
-command output for macro expansion, but this appears to be a mistake
-in @acronym{POSIX} since traditional implementations did not do this.
address@hidden @code{m4} follows traditional behavior in @code{syscmd}, and
-provides the extension @code{esyscmd} that provides the @acronym{POSIX}
-semantics.
address@hidden 2001 requires @code{syscmd} (@pxref{Syscmd}) to evaluate
+command output for macro expansion, but this was a mistake that is
+anticipated to be corrected in the next version of @acronym{POSIX}.
address@hidden @code{m4} follows traditional behavior in @code{syscmd}
+where output is not rescanned, and provides the extension @code{esyscmd}
+that does scan the output.
 
 @item
 At one point, @acronym{POSIX} required @code{changequote(@var{arg})}
@@ -6270,8 +6305,8 @@
 comments when parsing, meaning that if the start delimiter given to
 @code{changecom} (@pxref{Changecom}) starts with a macro name, comments
 are effectively disabled.  @acronym{POSIX} does not specify what the
-precedence is, so the @acronym{GNU} @code{m4} parser recognizes
-comments, then macros, then quoted strings.
+precedence is, so this version of @acronym{GNU} @code{m4} parser
+recognizes comments, then macros, then quoted strings.
 
 @item
 Traditional implementations allow argument collection, but not string
@@ -6315,9 +6350,11 @@
 implementations allowed it as an alias for @samp{==}.
 
 @item
address@hidden requires @code{translit} (@pxref{Translit}) to treat
-each character of the second and third arguments literally, but @acronym{GNU}
address@hidden treats @samp{-} as a range operator.
address@hidden 2001 requires @code{translit} (@pxref{Translit}) to
+treat each character of the second and third arguments literally.
+However, it is anticipated that the next version of @acronym{POSIX} will
+allow the @acronym{GNU} @code{m4} behavior of treating @samp{-} as a
+range operator.
 
 @item
 @acronym{POSIX} requires @code{m4} to honor the locale environment