head - more doc cleanups

Index: src/builtin.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/builtin.c,v
retrieving revision 1.1.1.1.2.43
diff -u -p -r1.1.1.1.2.43 builtin.c
--- src/builtin.c	13 Oct 2006 22:25:32 -0000	1.1.1.1.2.43
+++ src/builtin.c	14 Oct 2006 14:09:50 -0000
@@ -1092,7 +1092,9 @@ m4_undivert (struct obstack *obs, int ar
 	    if (fp != NULL)
 	      {
 		insert_file (fp);
-		fclose (fp);
+		if (fclose (fp) == EOF)
+		  M4ERROR ((warning_status, errno,
+			    "error undiverting `%s'", ARG (i)));
 	      }
 	    else
 	      M4ERROR ((warning_status, errno,

Index: modules/m4.c
===================================================================
RCS file: /sources/m4/m4/modules/m4.c,v
retrieving revision 1.82
diff -u -p -r1.82 m4.c
--- modules/m4.c	12 Oct 2006 21:14:50 -0000	1.82
+++ modules/m4.c	14 Oct 2006 14:10:22 -0000
@@ -560,28 +560,35 @@ M4BUILTIN_HANDLER (divnum)
 M4BUILTIN_HANDLER (undivert)
 {
   int i = 0;
+  const char *me = M4ARG (0);
 
   if (argc == 1)
     m4_undivert_all (context);
   else
-    {
-      if (sscanf (M4ARG (1), "%d", &i) == 1)
-	m4_insert_diversion (context, i);
-      else if (m4_get_posixly_correct_opt (context))
-	m4_numeric_arg (context, argc, argv, 1, &i);
-      else
-	{
-	  FILE *fp = m4_path_search (context, M4ARG (1), (char **) NULL);
-	  if (fp != NULL)
-	    {
-	      m4_insert_file (context, fp);
-	      fclose (fp);
-	    }
-	  else
-	    m4_error (context, 0, errno, _("%s: cannot undivert `%s'"),
-		      M4ARG (0), M4ARG (1));
-	}
-    }
+    for (i = 1; i < argc; i++)
+      {
+	const char *str = M4ARG (i);
+	char *endp;
+	int diversion = strtol (str, &endp, 10);
+	if (*endp == '\0' && !isspace ((unsigned char) *str))
+	  m4_insert_diversion (context, diversion);
+	else if (m4_get_posixly_correct_opt (context))
+	  m4_numeric_arg (context, argc, argv, i, &diversion);
+	else
+	  {
+	    FILE *fp = m4_path_search (context, str, NULL);
+	    if (fp != NULL)
+	      {
+		m4_insert_file (context, fp);
+		if (fclose (fp) == EOF)
+		  m4_error (context, 0, errno, _("%s: error undiverting `%s'"),
+			    me, str);
+	      }
+	    else
+	      m4_error (context, 0, errno, _("%s: cannot undivert `%s'"),
+			me, str);
+	  }
+      }
 }
 
 
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.64
diff -u -p -r1.64 m4.texinfo
--- doc/m4.texinfo	13 Oct 2006 16:46:47 -0000	1.64
+++ doc/m4.texinfo	14 Oct 2006 14:10:23 -0000
@@ -268,6 +268,7 @@ Compatibility with other versions of @co
 
 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 @@ demonstration purposes.  Improved versio
 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
 
+@node Improved exch
+@section 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:
+
+@example
+define(`exch', ``$2', `$1'')
+@result{}
+define(exch(`expansion text', `macro'))
+@result{}
+macro
+@result{}expansion text
+@end example
+
 @node Improved foreach
 @section Solution for @code{foreach}
 
@@ -5795,20 +5815,36 @@ foreach(`a', ``1',`2',`3'', `a
 @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:
 
-@comment ignore
 @example
 define(`cleardivert',
-`pushdef(`_num', divnum)divert(-1)ifelse($#, 0,
-  `undivert`'', `undivert($@@)')divert(_num)popdef(`_num')')
+  `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
+@result{}
+divert(`1')one
+divert
+@result{}
+cleardivert
+@result{}
+undivert
+@result{}one
+@result{}
+define(`cleardivert',
+  `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
+    `undivert`'', `undivert($@@)')divert(_num)popdef(`_num')')
+@result{}
+divert(`2')two
+divert
+@result{}
+cleardivert
+@result{}
+undivert
+@result{}
 @end example
 
-@noindent
-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 @@ the entire 1.4.x release series, a bette
 @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')')