Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      07/05/31 13:26:40

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.105
retrieving revision 1.106
diff -u -b -r1.105 -r1.106
--- doc/m4.texinfo      30 May 2007 13:36:58 -0000      1.105
+++ doc/m4.texinfo      31 May 2007 13:26:39 -0000      1.106
@@ -5008,11 +5008,17 @@
 @cindex files, diverting output to
 Output is diverted using @code{divert}:
 
address@hidden {Builtin (m4)} divert (@dvar{number, 0})
address@hidden {Builtin (m4)} divert (@dvar{number, 0}, @ovar{text})
 The current diversion is changed to @var{number}.  If @var{number} is left
 out or empty, it is assumed to be zero.  If @var{number} cannot be
 parsed, the diversion is unchanged.
 
address@hidden @acronym{GNU} extensions
+As a @acronym{GNU} extension, if optional @var{text} is supplied and
address@hidden was valid, then @var{text} is immediately output to the
+new diversion, regardless of whether the expansion of @code{divert}
+occurred while collecting arguments for another macro.
+
 The expansion of @code{divert} is void.
 @end deffn
 
@@ -5076,6 +5082,44 @@
 @result{}world
 @end example
 
+The ability to immediately output extra text is a @acronym{GNU}
+extension, but it can prove useful for ensuring that text goes to a
+particular diversion no matter how many pending macro expansions are in
+progress.  For a demonstration of why this is useful, it is important to
+understand in the example below why @samp{one} is output in diversion 2,
+not diversion 1, while @samp{three} and @samp{five} both end up in the
+correctly numbered diversion.  The key point is that when @code{divert}
+is executed unquoted as part of the argument collection of another
+macro, the side effect takes place immediately, but the text @samp{one}
+is not passed to any diversion until after the @samp{divert(`2')} and
+the enclosing @code{echo} have also taken place.  The example with
address@hidden shows how following the quoting rule of thumb delays the
+invocation of @code{divert} until it is not nested in any argument
+collection context, while the example with @samp{five} shows the use of
+the optional argument to speed up the output process.
+
address@hidden
+define(`echo', `$1')
address@hidden
+echo(divert(`1')`one'divert(`2'))`'dnl
+echo(`divert(`3')three`'divert(`4')')`'dnl
+echo(divert(`5', `five')divert(`6'))`'dnl
+divert
address@hidden
+undivert(`1')
address@hidden
+undivert(`2')
address@hidden
+undivert(`3')
address@hidden
+undivert(`4')
address@hidden
+undivert(`5')
address@hidden
+undivert(`6')
address@hidden
address@hidden example
+
 Note that @code{divert} is an English word, but also an active macro
 without arguments.  When processing plain text, the word might appear in
 normal text and be unintentionally swallowed as a macro invocation.  One