CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/08/15 13:51:47
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.65
retrieving revision 1.1.1.1.2.66
diff -u -b -r1.1.1.1.2.65 -r1.1.1.1.2.66
--- doc/m4.texinfo 14 Aug 2006 13:07:14 -0000 1.1.1.1.2.65
+++ doc/m4.texinfo 15 Aug 2006 13:51:47 -0000 1.1.1.1.2.66
@@ -903,7 +903,8 @@
specific provision.
There is also a command line option (@option{--prefix-builtins}, or
[EMAIL PROTECTED]) which requires all builtin macro names to be prefixed
[EMAIL PROTECTED], @pxref{Invoking m4}) which requires all builtin macro names
+to be prefixed
by @samp{m4_} for them to be recognized. The option has no effect
whatsoever on user defined macros. For example, with this option,
one has to write @code{m4_dnl} and even @code{m4_m4exit}.
@@ -1010,8 +1011,8 @@
Normally @code{m4} will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
-the @option{-Q} command line option. For user defined macros, there is no
-check of the number of arguments given.
+the @option{-Q} command line option (@pxref{Invoking m4}). For user
+defined macros, there is no check of the number of arguments given.
Macros are expanded normally during argument collection, and whatever
commas, quotes and parentheses that might show up in the resulting
@@ -1847,11 +1848,13 @@
@deffn Builtin shift (@dots{})
Takes any number of arguments, and expands to all but the first
argument, separated by commas, with each argument quoted.
+
+The macro @code{shift} is recognized only with parameters.
@end deffn
@example
shift
[EMAIL PROTECTED]
[EMAIL PROTECTED]
shift(`bar')
@result{}
shift(`foo', `bar', `baz')
@@ -2061,7 +2064,7 @@
of the time, signifying an expansion at the outermost level, but it
increases when macro arguments contain unquoted macro calls. The
maximum number that will appear between dashes is controlled by the
-option @option{--nesting-limit}.
+option @option{--nesting-limit} (@pxref{Invoking m4}).
Tracing by name is an attribute that is preserved whether the macro is
defined or not. This allows the @option{-t} option to select macros to
@@ -2123,8 +2126,9 @@
@cindex controlling debugging output
@cindex debugging output, controlling
-The @option{-d} option to @code{m4} controls the amount of details
-presented, when using the macros described in the preceding sections.
+The @option{-d} option to @code{m4} (@pxref{Invoking m4}) controls the
+amount of details presented, when using the macros described in the
+preceding sections.
The @var{flags} following the option can be one or more of the
following:
@@ -2224,7 +2228,8 @@
@cindex output, saving debugging
@cindex @acronym{GNU} extensions
Debug and tracing output can be redirected to files using either the
[EMAIL PROTECTED] option to @code{m4}, or with the builtin macro
@code{debugfile}:
[EMAIL PROTECTED] option to @code{m4} (@pxref{Invoking m4}), or with the
+builtin macro @code{debugfile}:
@deffn Builtin debugfile (@ovar{file})
Sends all further debug and trace output to @var{file}. If
@@ -2711,9 +2716,8 @@
@end example
@code{m4} now requires a @samp{#} mark at the beginning of every
-macro invocation, so one can use @code{m4} to preprocess shell
-scripts without getting @code{shift} commands swallowed, and plain
-text without losing various common words.
+macro invocation, so one can use @code{m4} to preprocess plain
+text without losing various words like @samp{divert}.
In @code{m4}, macro substitution is based on text, while in @TeX{}, it
is based on tokens. @code{changeword} can throw this difference into
@@ -2781,6 +2785,7 @@
concatenated with a space to the @var{string}.
The expansion of @code{m4wrap} is void.
+The macro @code{m4wrap} is recognized only with parameters.
@end deffn
@example
@@ -2896,9 +2901,9 @@
@end example
The rest of this section assumes that @code{m4} is invoked with the
[EMAIL PROTECTED] option pointing to the @file{examples} directory shipped as
-part of the @acronym{GNU} @code{m4} package. The file
[EMAIL PROTECTED]/@/incl.m4} in the distribution contains the lines:
[EMAIL PROTECTED] option (@pxref{Invoking m4}) pointing to the @file{examples}
+directory shipped as part of the @acronym{GNU} @code{m4} package. The
+file @file{examples/@/incl.m4} in the distribution contains the lines:
@comment ignore
@example
Include file start
@@ -2956,7 +2961,8 @@
If a file is not found in the current working directory, and the file
name is not absolute, the file will be looked for in a specified search
path. First, the directories specified with the @option{-I} option will
-be searched, in the order found on the command line. Second, if the
+be searched, in the order found on the command line (@pxref{Invoking
+m4}). Second, if the
@env{M4PATH} environment variable is set, it is expected to contain a
colon-separated list of directories, which will be searched in order.
@@ -3054,6 +3060,26 @@
This is a common programming idiom in @code{m4}.
+Note that @code{divert} is an English word, but also an active macro
+without arguments. When processing plain text, the word might appear in
+normal text and be unintentionally swallowed as a macro invocation. One
+way to avoid this is to use the @option{-P} option to rename all
+builtins (@pxref{Invoking m4}). Another is to write a wrapper that
+requires a parameter to be recognized.
+
[EMAIL PROTECTED]
+We decided to divert the stream for irrigation.
[EMAIL PROTECTED] decided to the stream for irrigation.
+define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@@)')')
[EMAIL PROTECTED]
+divert(-1)
+Ignored text.
+divert(0)
[EMAIL PROTECTED]
+We decided to divert the stream for irrigation.
[EMAIL PROTECTED] decided to divert the stream for irrigation.
[EMAIL PROTECTED] example
+
@node Undivert
@section Undiverting output
@@ -3822,8 +3848,8 @@
@end deffn
When @acronym{GNU} extensions are in effect (that is, when you did not use the
[EMAIL PROTECTED] option), @acronym{GNU} @code{m4} will define the macro
[EMAIL PROTECTED] to expand to the empty string.
[EMAIL PROTECTED] option, @pxref{Invoking m4}), @acronym{GNU} @code{m4} will
+define the macro @code{__gnu__} to expand to the empty string.
@example
__gnu__
@@ -4070,6 +4096,7 @@
standard error output, separated by spaces.
The expansion of @code{errprint} is void.
+The macro @code{errprint} is recognized only with parameters.
@end deffn
@example
@@ -4108,7 +4135,8 @@
Line numbers start at 1 for each file. If the file was found due to the
@option{-I} option or @env{M4PATH} environment variable, that is
-reflected in the file name. The syncline option (@option{-s}), and the
+reflected in the file name. The syncline option (@option{-s},
[EMAIL PROTECTED] m4}), and the
@samp{f} 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, or warning message
@@ -4406,8 +4434,8 @@
@cindex @acronym{GNU} extensions
This version of @code{m4} contains a few facilities that do not exist
in System V @code{m4}. These extra facilities are all suppressed by
-using the @option{-G} command line option, unless overridden by other
-command line options.
+using the @option{-G} command line option (@pxref{Invoking m4}), unless
+overridden by other command line options.
@itemize @bullet
@item
