Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/10/04 03:57:01

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -b -r1.57 -r1.58
--- doc/m4.texinfo      29 Sep 2006 18:20:12 -0000      1.57
+++ doc/m4.texinfo      4 Oct 2006 03:57:00 -0000       1.58
@@ -3790,19 +3790,24 @@
 @result{}
 @end example
 
-Assume in the following that the file @file{incl.m4} contains the lines:
address@hidden file: incl.m4
+This section assumes that the current directory is
address@hidden@value{VERSION}/@/tests}, and uses the file
address@hidden@value{VERSION}/@/examples/@/incl.m4} included in the
address@hidden M4 package.  The file @file{incl.m4} contains the lines:
address@hidden ignore
 @example
 Include file start
 foo
 Include file end
 @end example
address@hidden
+
 Normally file inclusion is used to insert the contents of a file
 into the input stream.  The contents of the file will be read by
 @code{m4} and macro calls in the file will be expanded:
 
address@hidden options: -I"$abs_top_srcdir"/examples
 @example
+$ @kbd{m4 -I ../examples}
 define(`foo', `FOO')
 @result{}
 include(`incl.m4')
@@ -3817,7 +3822,9 @@
 Here is an example, which defines @samp{bar} to expand to the contents
 of @file{incl.m4}:
 
address@hidden options: -I"$abs_top_srcdir"/examples
 @example
+$ @kbd{m4 -I ../examples}
 define(`bar', include(`incl.m4'))
 @result{}
 This is `bar':  >>bar<<
@@ -5050,21 +5057,68 @@
 @node Location
 @section Printing current location
 
-To make it possible to specify the location of the error, two
+To make it possible to specify the location of the error, three
 utility builtins exist:
 
 @deffn {Builtin (gnu)} __file__
 @deffnx {Builtin (gnu)} __line__
-These expand to the @emph{quoted} name of the current input file, and
-the current input line number in that file.
address@hidden {Builtin (gnu)} __program__
+Expand to the quoted name of the current input file, the
+current input line number in that file, and the quoted name of the
+current invocation of @code{m4}.
address@hidden deffn
 
 @example
-errprint(`m4:'__file__:__line__: `Input error
+errprint(__program__:__file__:__line__: `input error
 ')
address@hidden:stdin:1: Input error
address@hidden:stdin:1: input error
 @result{}
 @end example
address@hidden deffn
+
+Line numbers start at 1 for each file.  If the file was found due to the
address@hidden option or @env{M4PATH} environment variable, that is
+reflected in the file name.  Synclines, via @code{syncoutput}
+(@pxref{Syncoutput}) or the command line option @option{--synclines}
+(or @option{-s}, @pxref{Invoking m4}), and the
address@hidden and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
+also use this notion of current file and line.  Redefining the three
+location macros has no effect on syncline, debug, warning, or error
+message output.
+
+This example assumes that the current directory is
address@hidden@value{VERSION}/@/tests}, and reuses the file
address@hidden@value{VERSION}/@/examples/@/incl.m4} mentioned earlier
+(@pxref{Include}):
+
address@hidden options: -I"$abs_top_srcdir"/examples
address@hidden
+$ @kbd{m4 -I ../examples}
+define(`foo', ``$0' called at __file__:__line__')
address@hidden
+foo
address@hidden called at stdin:2
+include(`incl.m4')
address@hidden file start
address@hidden called at ../examples/incl.m4:2
address@hidden file end
address@hidden
address@hidden 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 @code{__program__} macro behaves like @samp{$0} in shell
+terminology.  If you invoke @code{m4} through an absolute path or a link
+with a different spelling, rather than by relying on a @env{PATH} search
+for plain @samp{m4}, it will affect how @code{__program__} expands.  The
+intent is that you can use it to produce error messages with the same
+formatting that @code{m4} produces internally.  It can also be used
+within @code{syscmd} (@pxref{Syscmd}) to pick the same version of
address@hidden that is currently running, rather than whatever version of
address@hidden happens to be first in @env{PATH}.
 
 @node M4exit
 @section Exiting from @code{m4}