m4-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Changes to m4/doc/m4.texinfo,v


From: Eric Blake
Subject: Changes to m4/doc/m4.texinfo,v
Date: Mon, 04 Dec 2006 13:57:25 +0000

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/12/04 13:57:22

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.80
retrieving revision 1.81
diff -u -b -r1.80 -r1.81
--- doc/m4.texinfo      16 Nov 2006 14:42:37 -0000      1.80
+++ doc/m4.texinfo      4 Dec 2006 13:57:22 -0000       1.81
@@ -4483,26 +4483,30 @@
 @node Undivert
 @section Undiverting output
 
address@hidden {Builtin (m4)} undivert (@address@hidden)
 Diverted text can be undiverted explicitly using the builtin
address@hidden,  which reinserts the diverted output given by the
-arguments into the current output stream, in the order given.  If no
-arguments are supplied, all diversions are undiverted, in numerical
-order.
address@hidden:
 
address@hidden FIXME: Explain what happens when undiverting all to else than 0.
address@hidden {Builtin (m4)} undivert (@address@hidden)
+Undiverts the numeric @var{diversions} given by the arguments, in the
+order given.  If no arguments are supplied, all diversions are
+undiverted, in numerical order.
+
address@hidden @acronym{GNU} extensions
+As a @acronym{GNU} extension, @var{diversions} may contain non-numeric
+strings, which are treated as the names of files to copy into the output
+without expansion.  A warning is issued if a file could not be opened.
 
 The expansion of @code{undivert} is void.
 @end deffn
 
 @example
-divert(1)
+divert(`1')
 This text is diverted.
 divert
 @result{}
 This text is not diverted.
 @result{}This text is not diverted.
-undivert(1)
+undivert(`1')
 @result{}
 @result{}This text is diverted.
 @result{}
@@ -4514,36 +4518,69 @@
 
 When diverted text is undiverted, it is @emph{not} reread by @code{m4},
 but rather copied directly to the current output, and it is therefore
-not an error to undivert into a diversion.
+not an error to undivert into a diversion.  Undiverting the empty string
+is the same as specifying diversion 0; in either case nothing happens
+since the output has already been flushed.
+
address@hidden
+divert(`1')diverted text
+divert
address@hidden
+undivert()
address@hidden
+undivert(`0')
address@hidden
+undivert
address@hidden text
address@hidden
address@hidden example
 
 When a diversion has been undiverted, the diverted text is discarded,
 and it is not possible to bring back diverted text more than once.
 
 @example
-divert(1)
+divert(`1')
 This text is diverted first.
-divert(0)undivert(1)dnl
+divert(`0')undivert(`1')dnl
 @result{}
 @result{}This text is diverted first.
-undivert(1)
+undivert(`1')
 @result{}
-divert(1)
+divert(`1')
 This text is also diverted but not appended.
-divert(0)undivert(1)dnl
+divert(`0')undivert(`1')dnl
 @result{}
 @result{}This text is also diverted but not appended.
 @end example
 
-Attempts to undivert the current diversion are silently ignored.
+Attempts to undivert the current diversion are silently ignored.  Thus,
+when the current diversion is not 0, the current diversion does not get
+rearranged among the other diversions.
 
address@hidden GNU extensions
address@hidden
+divert(`1')one
+divert(`2')two
+divert(`3')three
+divert(`4')four
+divert(`5')five
+divert(`2')undivert(`5', `2', `4')dnl
+undivert`'dnl effectively undivert(`1', `2', `3', `4', `5')
+divert`'undivert`'dnl
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden example
+
address@hidden @acronym{GNU} extensions
 @cindex file inclusion
 @cindex inclusion, of files
-GNU @code{m4} allows named files to be undiverted.  Given a non-numeric
-argument, the contents of the file named will be copied, uninterpreted, to
-the current output.  This complements the builtin @code{include}
-(@pxref{Include}).  To illustrate the difference, assume the file
address@hidden contains:
address@hidden @code{m4} allows named files to be undiverted.  Given a
+non-numeric argument, the contents of the file named will be copied,
+uninterpreted, to the current output.  This complements the builtin
address@hidden (@pxref{Include}).  To illustrate the difference, assume
+the file @file{foo} contains:
 
 @comment file: foo
 @example
@@ -4565,21 +4602,38 @@
 @result{}
 @end example
 
+If the file is not found (or cannot be read), an error message is
+issued, and the expansion is void.  It is possible to intermix files
+and diversion numbers.
+
address@hidden
+divert(`1')diversion one
+divert(`2')undivert(`foo')dnl
+divert(`3')diversion three
+divert`'dnl
+undivert(`1', `2', `foo', `3')dnl
address@hidden one
address@hidden
address@hidden
address@hidden three
address@hidden example
+
 @node Divnum
 @section Diversion numbers
 
 @cindex diversion numbers
+The current diversion is tracked by the builtin @code{divnum}:
+
 @deffn {Builtin (m4)} divnum
-The builtin @code{divnum} expands to the number of the current
-diversion.
+Expands to the number of the current diversion.
 @end deffn
 
 @example
 Initial divnum
 @result{}Initial 0
-divert(1)
+divert(`1')
 Diversion one: divnum
-divert(2)
+divert(`2')
 Diversion two: divnum
 divert
 @result{}
@@ -4590,9 +4644,6 @@
 @result{}Diversion two: 2
 @end example
 
-The last call of @code{divert} without arguments is necessary because the
-undiverted text would otherwise be diverted itself.
-
 @node Cleardivert
 @section Discarding diverted text
 
@@ -4603,14 +4654,14 @@
 on the main output stream when the end of input is seen, a method of
 discarding a diversion is needed.  If all diversions should be
 discarded, the easiest is to end the input to @code{m4} with
address@hidden(-1)} followed by an explicit @samp{undivert}:
address@hidden(`-1')} followed by an explicit @samp{undivert}:
 
 @example
-divert(1)
+divert(`1')
 Diversion one: divnum
-divert(2)
+divert(`2')
 Diversion two: divnum
-divert(-1)
+divert(`-1')
 undivert
 ^D
 @end example
@@ -4620,6 +4671,10 @@
 
 Clearing selected diversions can be done with the following macro:
 
address@hidden Composite cleardivert (@address@hidden)
+Discard the contents of each of the listed numeric @var{diversions}.
address@hidden deffn
+
 @example
 define(`cleardivert',
 `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
@@ -4642,14 +4697,14 @@
 a custom M4 installation.
 
 Starting with release 2.0, M4 uses Libtool's @code{libltdl} facilities
-(@pxref{Using libltdl, ,libltdl ,libtool , The GNU Libtool Manual})
+(@pxref{Using libltdl, , libltdl, libtool, The GNU Libtool Manual})
 to move all of M4's builtins out to pluggable modules.  Unless compile
 time options are set to change the default build, the installed M4 2.0
 binary is virtually identical to 1.4.x, supporting the same builtins.
 However, an optional module can be loaded into the running M4 interpreter
 to provide a new @code{load} builtin.  This facilitates runtime
 extension of the M4 builtin macro list using compiled C code linked
-against a new @file{libm4.so}.
+against a new shared library, typically named @file{libm4.so}.
 
 For example, you might want to add a @code{setenv} builtin to M4, to
 use before invoking @code{esyscmd}.  We might write a @file{setenv.c}
@@ -4662,11 +4717,11 @@
 M4BUILTIN(setenv);
 
 m4_builtin m4_builtin_table[] =
-  @{
-    /* name     handler         macros blind minargs maxargs */
-    @{ "setenv", builtin_setenv, false, false,   3,     4 @},
address@hidden
+  /* name      handler         flags             minargs maxargs */
+  @{ "setenv", builtin_setenv, M4_BUILTIN_BLIND, 2,      3 @},
 
-    @{ NULL,     NULL,           false, false,    0,     0 @}
+  @{ NULL,     NULL,           0,                0,      0 @}
 @};
 
 /**
@@ -4689,9 +4744,11 @@
 
 @comment ignore
 @example
-$ M4MODPATH=`pwd` m4 --load-module=setenv
+$ @kbd{M4MODPATH=`pwd` m4 --load-module=setenv}
 setenv(`PATH', `/sbin:/bin:/usr/sbin:/usr/bin')
-esyscmd(`ifconfig -a')
address@hidden
+esyscmd(`ifconfig -a')dnl
address@hidden@dots{}
 @end example
 
 Or instead of loading the module from the M4 invocation, you can use
@@ -4699,9 +4756,11 @@
 
 @comment ignore
 @example
-$ M4MODPATH=`pwd` m4 --load-module=load
+$ @kbd{M4MODPATH=`pwd` m4 --load-module=load}
 load(`setenv')
address@hidden
 setenv(`PATH', `/sbin:/bin:/usr/sbin:/usr/bin')
address@hidden
 @end example
 
 Also, at build time, you can choose which modules to build into
@@ -4712,13 +4771,13 @@
 
 We hinted earlier that the @code{m4} and @code{gnu} modules are
 preloaded into the installed M4 binary, but it is possible to install
-a @emph{thinner} binary minus GNU extensions, for example, by
-configuring the distribution with @samp{./configure
+a @emph{thinner} binary; for example, omitting the @acronym{GNU}
+extensions by configuring the distribution with @kbd{./configure
 --with-modules=m4}.  For a binary built with that option to understand
-code that uses @acronym{GNU} extensions, you must then run @samp{m4
+code that uses @acronym{GNU} extensions, you must then run @kbd{m4
 --load-module=gnu}.  It is also possible to build a @emph{fatter}
 binary with additional modules preloaded: adding, say, the @code{load}
-builtin using @samp{./configure --with-modules="m4 gnu load"}.
+builtin using @kbd{./configure --with-modules="m4 gnu load"}.
 
 @acronym{GNU} M4 now has a facility for defining additional builtins without
 recompiling the sources.  In actual fact, all of the builtins provided




reply via email to

[Prev in Thread] Current Thread [Next in Thread]