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}:
[EMAIL PROTECTED] {Builtin (m4)} divert (@dvar{number, 0})
[EMAIL PROTECTED] {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.
[EMAIL PROTECTED] @acronym{GNU} extensions
+As a @acronym{GNU} extension, if optional @var{text} is supplied and
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
+define(`echo', `$1')
[EMAIL PROTECTED]
+echo(divert(`1')`one'divert(`2'))`'dnl
+echo(`divert(`3')three`'divert(`4')')`'dnl
+echo(divert(`5', `five')divert(`6'))`'dnl
+divert
[EMAIL PROTECTED]
+undivert(`1')
[EMAIL PROTECTED]
+undivert(`2')
[EMAIL PROTECTED]
+undivert(`3')
[EMAIL PROTECTED]
+undivert(`4')
[EMAIL PROTECTED]
+undivert(`5')
[EMAIL PROTECTED]
+undivert(`6')
[EMAIL PROTECTED]
[EMAIL PROTECTED] 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
