Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/10/12 21:14:50

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -b -r1.62 -r1.63
--- doc/m4.texinfo      12 Oct 2006 02:44:26 -0000      1.62
+++ doc/m4.texinfo      12 Oct 2006 21:14:49 -0000      1.63
@@ -266,6 +266,12 @@
 * Incompatibilities::           Other incompatibilities
 * Experiments::                 Experimental features in @acronym{GNU} M4
 
+Correct version of some examples
+
+* Improved foreach::            Solution for @code{foreach}
+* Improved cleardivert::        Solution for @code{cleardivert}
+* Improved fatal_error::        Solution for @code{fatal_error}
+
 How to make copies of this manual
 
 * GNU Free Documentation License::  License for copying this manual
@@ -378,7 +384,7 @@
 Then in 2005 Gary V. Vaughan collected together the many
 patches to @acronym{GNU} @code{m4} 1.4 that were floating around the net and
 released 1.4.3 and 1.4.4.  And in 2006, Eric Blake joined the team and
-prepared patches for the release of 1.4.5, 1.4.6, and 1.4.7.
+prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.
 
 Meanwhile, development was underway for new features for @code{m4},
 such as dynamic module loading and additional builtins, practically
@@ -1325,7 +1331,7 @@
 @result{}hello world
 define(
 ^D
address@hidden:stdin:1: end of file in argument list
address@hidden:stdin:2: end of file in argument list
 @end example
 
 @node Quoting Arguments
@@ -3229,13 +3235,13 @@
 warning is issued and dnl stops consuming input.
 
 @example
-define(`hi', `HI')
address@hidden
 m4wrap(`m4wrap(`2 hi
 ')0 hi dnl 1 hi')
 @result{}
+define(`hi', `HI')
address@hidden
 ^D
address@hidden: Warning: dnl: end of file treated as newline
address@hidden:stdin:1: Warning: dnl: end of file treated as newline
 @result{}0 HI 2 HI
 @end example
 
@@ -5161,11 +5167,34 @@
 @result{}
 @end example
 
-Currently, all text wrapped with @code{m4wrap} (@pxref{M4wrap}) behaves
-as though it came from line 0 of the file ``''.  It is hoped that a
-future release of @code{m4} can overcome this limitation and remember
-which file invoked the call to @code{m4wrap}.
address@hidden FIXME - make m4wrap remember line locations.
+The location of macros invoked during the rescanning of macro expansion
+text corresponds to the location in the file where the expansion was
+triggered, regardless of how many newline characters the expansion text
+contains.  As of @acronym{GNU} M4 1.4.8, the location of text wrapped
+with @code{m4wrap} (@pxref{M4wrap}) is the point at which the
address@hidden was invoked.  Previous versions, however, behaved as
+though wrapped text came from line 0 of the file ``''.
+
address@hidden
+define(`echo', `$@@')
address@hidden
+define(`foo', `echo(__line__
+__line__)')
address@hidden
+echo(__line__
+__line__)
address@hidden
address@hidden
+m4wrap(`foo
+')
address@hidden
+foo
address@hidden
address@hidden
+^D
address@hidden
address@hidden
address@hidden example
 
 The @code{__program__} macro behaves like @samp{$0} in shell
 terminology.  If you invoke @code{m4} through an absolute path or a link
@@ -5175,7 +5204,8 @@
 formatting that @code{m4} produces internally.  It can also be used
 within @code{syscmd} (@pxref{Syscmd}) to pick the same version of
 @code{m4} that is currently running, rather than whatever version of
address@hidden happens to be first in @env{PATH}.
address@hidden happens to be first in @env{PATH}.  It was first introduced
+in @acronym{GNU} M4 1.4.6.
 
 @node M4exit
 @section Exiting from @code{m4}
@@ -5644,8 +5674,18 @@
 @node Answers
 @chapter Correct version of some examples
 
-Some of the examples in this manuals are buggy.  Correctly working
-macros are presented here.
+Some of the examples in this manuals are buggy or not very robust, for
+demonstration purposes.  Improved versions of these composite macros are
+presented here.
+
address@hidden
+* Improved foreach::            Solution for @code{foreach}
+* Improved cleardivert::        Solution for @code{cleardivert}
+* Improved fatal_error::        Solution for @code{fatal_error}
address@hidden menu
+
address@hidden Improved foreach
address@hidden Solution for @code{foreach}
 
 The @code{foreach} macro (@pxref{Foreach}) as presented required the
 user to use parentheses to delineate the list.  This approach is
@@ -5724,6 +5764,9 @@
 @result{}
 @end example
 
address@hidden Improved cleardivert
address@hidden 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:
@@ -5739,6 +5782,34 @@
 If called without arguments, it will call undivert without argument,
 otherwise they will be passed to undivert().
 
address@hidden Improved fatal_error
address@hidden Solution for @code{fatal_error}
+
+The @code{fatal_error} macro (@pxref{M4exit}) is not robust to versions
+of @acronym{GNU} M4 earlier than 1.4.8, where invoking @code{__file__}
+(@pxref{Location}) inside @code{m4wrap} would result in an empty string,
+and @code{__line__} resulted in @samp{0} even though all files start at
+line 1.  Furthermore, versions earlier than 1.4.6 did not support the
address@hidden macro.  If you want @code{fatal_error} to work across
+the entire 1.4.x release series, a better implementation would be:
+
address@hidden status: 1
address@hidden
+define(`fatal_error',
+  `errprint(ifdef(`__program', `__program__', ``m4'')'dnl
+`:ifelse(__line__, `0', `',
+    `__file__:__line__:')` fatal error: $*
+')m4exit(`1')')
address@hidden
+m4wrap(`divnum(`demo of internal message')
+fatal_error(`inside wrapped text')')
address@hidden
+^D
address@hidden:stdin:6: Warning: divnum: extra arguments ignored: 1 > 0
address@hidden
address@hidden:stdin:6: fatal error: inside wrapped text
address@hidden example
+
 @c ========================================================== Appendices
 
 @node Copying This Manual