Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/10/14 14:16:23

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -b -r1.64 -r1.65
--- doc/m4.texinfo      13 Oct 2006 16:46:47 -0000      1.64
+++ doc/m4.texinfo      14 Oct 2006 14:16:23 -0000      1.65
@@ -268,6 +268,7 @@
 
 Correct version of some examples
 
+* Improved exch::               Solution for @code{exch}
 * Improved foreach::            Solution for @code{foreach}
 * Improved cleardivert::        Solution for @code{cleardivert}
 * Improved fatal_error::        Solution for @code{fatal_error}
@@ -5706,11 +5707,30 @@
 presented here.
 
 @menu
+* Improved exch::               Solution for @code{exch}
 * Improved foreach::            Solution for @code{foreach}
 * Improved cleardivert::        Solution for @code{cleardivert}
 * Improved fatal_error::        Solution for @code{fatal_error}
 @end menu
 
address@hidden Improved exch
address@hidden Solution for @code{exch}
+
+The @code{exch} macro (@pxref{Arguments}) as presented requires clients
+to double quote their arguments.  A nicer definition, which lets
+clients follow the rule of thumb of one level of quoting per level of
+parentheses, involves adding quotes in the definition of @code{exch}, as
+follows:
+
address@hidden
+define(`exch', ``$2', `$1'')
address@hidden
+define(exch(`expansion text', `macro'))
address@hidden
+macro
address@hidden text
address@hidden example
+
 @node Improved foreach
 @section Solution for @code{foreach}
 
@@ -5795,20 +5815,36 @@
 @section Solution for @code{cleardivert}
 
 The @code{cleardivert} macro (@pxref{Cleardiv}) cannot, as it stands, be
-called without arguments to clear all pending diversions.  A macro that
-achieves that as well is:
+called without arguments to clear all pending diversions.  That is
+because using undivert with an empty string for an argument is different
+than using it with no arguments at all.  Compare the earlier definition
+with one that takes the number of arguments into account:
 
address@hidden ignore
 @example
 define(`cleardivert',
-`pushdef(`_num', divnum)divert(-1)ifelse($#, 0,
+  `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
address@hidden
+divert(`1')one
+divert
address@hidden
+cleardivert
address@hidden
+undivert
address@hidden
address@hidden
+define(`cleardivert',
+  `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
   `undivert`'', `undivert($@@)')divert(_num)popdef(`_num')')
address@hidden
+divert(`2')two
+divert
address@hidden
+cleardivert
address@hidden
+undivert
address@hidden
 @end example
 
address@hidden
-If called without arguments, it will call undivert without argument,
-otherwise they will be passed to undivert().
-
 @node Improved fatal_error
 @section Solution for @code{fatal_error}
 
@@ -5823,7 +5859,7 @@
 @comment status: 1
 @example
 define(`fatal_error',
-  `errprint(ifdef(`__program', `__program__', ``m4'')'dnl
+  `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
 `:ifelse(__line__, `0', `',
     `__file__:__line__:')` fatal error: $*
 ')m4exit(`1')')