branch-1_4 improve doc example

[Eric Blake]

I'm checking this in as an example of reducing double quoting needed
by clients of a macro.

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

        * doc/m4.texinfo (Arguments): Hint at better exch macro.
        (Answers): Provide a better definiton.

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.63
diff -u -p -r1.1.1.1.2.63 m4.texinfo
--- doc/m4.texinfo      9 Aug 2006 12:28:00 -0000       1.1.1.1.2.63
+++ doc/m4.texinfo      12 Aug 2006 12:53:47 -0000
@@ -1231,6 +1231,8 @@ macro
 @end example
 
 @xref{Quoting Arguments}, for an explanation of the double quotes.
+(You should try and improve this example so that clients of exch do not
+have to double quote.  @pxref{Answers})
 
 @cindex @acronym{GNU} extensions
 @acronym{GNU} @code{m4} allows the number following the @samp{$} to
@@ -4707,6 +4709,21 @@ in traditional programming languages.
 Some of the examples in this manuals are buggy, for demonstration
 purposes.  Correctly working macros are presented here.
 
+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
+
 The @code{cleardivert} macro (@pxref{Cleardiv}) cannot, as it stands, be
 called without arguments to clear all pending diversions.  That is
 because using undivert with an empty string for an argument is different