Changes to m4/doc/m4.texinfo,v [branch-1_4]

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Branch:         branch-1_4
Changes by:     Eric Blake <ericb>      06/10/11 23:34:22

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.81
retrieving revision 1.1.1.1.2.82
diff -u -b -r1.1.1.1.2.81 -r1.1.1.1.2.82
--- doc/m4.texinfo      11 Oct 2006 17:07:03 -0000      1.1.1.1.2.81
+++ doc/m4.texinfo      11 Oct 2006 23:34:21 -0000      1.1.1.1.2.82
@@ -248,6 +248,12 @@
 * Incompatibilities::           Facilities in System V m4 not in GNU M4
 * Other Incompatibilities::     Other incompatibilities
 
+Correct version of some examples
+
+* Improved exch::               Solution for @code{exch}
+* 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
@@ -360,7 +366,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 has continued on new features for @code{m4}, such
 as dynamic module loading and additional builtins.  When complete,
@@ -2464,13 +2470,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: end of file treated as newline
address@hidden:stdin:1: Warning: end of file treated as newline
 @result{}0 HI 2 HI
 @end example
 
@@ -2879,6 +2885,41 @@
 @result{}bar
 @end example
 
address@hidden
address@hidden One more test of including newline in a macro name; but this
address@hidden does not need to be displayed in the manual.  This ensures
address@hidden that line numbering is correct when dnl cuts across include
address@hidden file boundaries, and when __file__ or __line__ is the last
address@hidden token in an include file.
+
address@hidden
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+define(`bar
+', defn(`dnl'))dnl
+changeword(`\([_a-zA-Z][_a-zA-Z0-9]*\|bar
+\)')
address@hidden
+__file__:__line__
address@hidden:7
+include(`foo') still ignored
+__file__:__line__
address@hidden:9
+define(`bar
+', defn(`__file__'))
address@hidden
+include(`foo')
address@hidden/examples/foo
+define(`bar
+', defn(`__line__'))
address@hidden
+include(`foo')
address@hidden
+__file__:__line__
address@hidden:16
address@hidden example
address@hidden ignore
+
 @code{changeword} has another function.  If the regular expression
 supplied contains any grouped subexpressions, then text outside
 the first of these is discarded before symbol lookup.  So:
@@ -3032,7 +3073,7 @@
 m4wrap(`m4wrap(`)')len(abc')
 @result{}
 ^D
address@hidden: ERROR: end of file in argument list
address@hidden:stdin:1: ERROR: end of file in argument list
 @end example
 
 @node File Inclusion
@@ -4427,10 +4468,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}.
+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
@@ -4440,7 +4505,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}
@@ -4457,6 +4523,15 @@
 input is read, and all wrapped and diverted text is discarded.
 @end deffn
 
address@hidden
+m4wrap(`This text is lost due to `m4exit'.')
address@hidden
+divert(`1') So is this.
+divert
address@hidden
+m4exit And this is never read.
address@hidden example
+
 A common use of this is to abort processing:
 
 @deffn Composite fatal_error (@var{message})
@@ -4477,22 +4552,13 @@
 After this macro call, @code{m4} will exit with exit status 1.  This macro
 is only intended for error exits, since the normal exit procedures are
 not followed, e.g., diverted text is not undiverted, and saved text
-(@pxref{M4wrap}) is not reread.  (This macro has a subtle bug, when
-invoked from wrapped text.  You should try to see if you can find it and
-correct it.  @pxref{Answers})
-
address@hidden
-m4wrap(`This text is lost to `m4exit'.')
address@hidden
-divert(`1') And so is this.
-divert
address@hidden
-m4exit
address@hidden example
+(@pxref{M4wrap}) is not reread.  (This macro could be made more robust
+to earlier versions of @code{m4}.  You should try to see if you can find
+weaknesses and correct them.  @pxref{Answers})
 
 Note that it is still possible for the exit status to be different than
 what was requested by @code{m4exit}.  If @code{m4} detects some other
-error, such as a write error on standard out, the exit status will be
+error, such as a write error on standard output, the exit status will be
 non-zero even if @code{m4exit} requested zero.
 
 If standard input is seekable, then the file will be positioned at the
@@ -5017,8 +5083,18 @@
 @node Answers
 @chapter Correct version of some examples
 
-Some of the examples in this manuals are buggy, for demonstration
-purposes.  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 exch::               Solution for @code{exch}
+* Improved cleardivert::        Solution for @code{cleardivert}
+* Improved fatal_error::        Solution for @code{fatal_error}
address@hidden 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
@@ -5035,6 +5111,9 @@
 @result{}expansion text
 @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.  That is
 because using undivert with an empty string for an argument is different
@@ -5066,17 +5145,21 @@
 @result{}
 @end example
 
-The @code{fatal_error} macro (@pxref{M4exit}) does not quite match the
-format of internal error messages when invoked inside wrapped text, due
-to the current limitations of @code{__file__} (@pxref{Location}) when
-invoked inside @code{m4wrap}.  Since @code{m4} omits the file and line
-number from its warning messages when there is no current file (or
-equivalently, when the current line is 0, since all files start at line
-1), a better implementation would be:
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:
 
 @example
 define(`fatal_error',
-  `errprint(__program__:ifelse(__line__, `0', `',
+  `errprint(ifdef(`__program', `__program__', ``m4'')'dnl
+`:ifelse(__line__, `0', `',
     `__file__:__line__:')` fatal error: $*
 ')m4exit(`1')')
 @result{}
@@ -5084,9 +5167,9 @@
 fatal_error(`inside wrapped text')')
 @result{}
 ^D
address@hidden: Warning: excess arguments to builtin `divnum' ignored
address@hidden:stdin:6: Warning: excess arguments to builtin `divnum' ignored
 @result{}0
address@hidden: fatal error: inside wrapped text
address@hidden:stdin:6: fatal error: inside wrapped text
 @end example
 
 @c ========================================================== Appendices