texinfo automatically capitalizes the contents of @var{...}, and recommends
using @var{a-b} over @var{a_b} when multi-word meta-syntactic names are needed
(m4 didn't use any multi-word names, but searching for @var{[^}]_ found a bug
in using @var incorrectly on a non-meta-syntactic name). This cleans up the
branch-1.4 manual; I'm applying similar patches on the other branches.
From: Eric Blake <[email protected]>
Date: Mon, 22 Dec 2008 08:51:00 -0700
Subject: [PATCH] Use @var correctly.
* doc/m4.texinfo (Operation modes, Preprocessor features)
(Limits control, Frozen state, Debugging options): Use lower case
names in @var.
(Improved copy): Use @code, not @var, as appropriate.
Signed-off-by: Eric Blake <[email protected]>
---
ChangeLog | 6 +++
doc/m4.texinfo | 108 ++++++++++++++++++++++++++++----------------------------
2 files changed, 60 insertions(+), 54 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index b094064..392058a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
2008-12-22 Eric Blake <[email protected]>
+ Use @var correctly.
+ * doc/m4.texinfo (Operation modes, Preprocessor features)
+ (Limits control, Frozen state, Debugging options): Use lower case
+ names in @var.
+ (Improved copy): Use @code, not @var, as appropriate.
+
Make --debugfile argument optional.
* src/builtin.c (m4_debugfile): Make error message consistent.
* src/m4.c (long_options): Make the argument optional, to allow
diff --git a/doc/m4.texinfo b/doc/m4.texinfo
index a76df90..de4710a 100644
--- a/doc/m4.texinfo
+++ b/doc/m4.texinfo
@@ -620,12 +620,12 @@ Operation modes
Suppress warnings, such as missing or superfluous arguments in macro
calls, or treating the empty string as zero.
-...@item --warn-macro-seque...@r{[}=@var{rege...@r{]}
-Issue a warning if the regular expression @var{REGEXP} has a non-empty
+...@item --warn-macro-seque...@r{[}=@var{rege...@r{]}
+Issue a warning if the regular expression @var{regexp} has a non-empty
match in any macro definition (either by @code{define} or
@code{pushdef}). Empty matches are ignored; therefore, supplying the
-empty string as @var{REGEXP} disables any warning. If the optional
-...@var{regexp} is not supplied, then the default regular expression is
+empty string as @var{regexp} disables any warning. If the optional
+...@var{regexp} is not supplied, then the default regular expression is
@samp{\$\(@{...@}]*@}\|[0-9][0-9]+\)} (a literal @samp{$} followed by
multiple digits or by an open brace), since these sequences will
change semantics in the default operation of @acronym{GNU} M4 2.0 (due
@@ -634,9 +634,9 @@ Operation modes
expression can provide a useful reverse lookup feature of finding
where a macro is defined to have a given definition.
-...@item -W @var{REGEXP}
-...@itemx --word-rege...@var{regexp}
-Use @var{REGEXP} as an alternative syntax for macro names. This
+...@item -W @var{regexp}
+...@itemx --word-rege...@var{regexp}
+Use @var{regexp} as an alternative syntax for macro names. This
experimental option will not be present in all @acronym{GNU} @code{m4}
implementations (@pxref{Changeword}).
@end table
@@ -653,18 +653,18 @@ Preprocessor features
input came from. These features occur with the following options:
@table @code
-...@item -D @var{na...@r{[}=@var{val...@r{]}
-...@itemx --defi...@var{name}@r{...@var{value}@r{]}
-This enters @var{NAME} into the symbol table. If @sam...@var{value}} is
-missing, the value is taken to be the empty string. The @var{VALUE} can
+...@item -D @var{na...@r{[}=@var{val...@r{]}
+...@itemx --defi...@var{name}@r{...@var{value}@r{]}
+This enters @var{name} into the symbol table. If @sam...@var{value}} is
+missing, the value is taken to be the empty string. The @var{value} can
be any string, and the macro can be defined to take arguments, just as
if it was defined from within the input. This option may be given more
than once; order with respect to file names is significant, and
-redefining the same @var{NAME} loses the previous value.
+redefining the same @var{name} loses the previous value.
-...@item -I @var{DIRECTORY}
-...@itemx --inclu...@var{directory}
-Make @code{m4} search @var{DIRECTORY} for included files that are not
+...@item -I @var{directory}
+...@itemx --inclu...@var{directory}
+Make @code{m4} search @var{directory} for included files that are not
found in the current working directory. @xref{Search Path}, for more
details. This option may be given more than once.
@@ -724,11 +724,11 @@ Preprocessor features
@result{}goodbye
@end example
-...@item -U @var{NAME}
-...@itemx --undefi...@var{name}
-This deletes any predefined meaning @var{NAME} might have. Obviously,
+...@item -U @var{name}
+...@itemx --undefi...@var{name}
+This deletes any predefined meaning @var{name} might have. Obviously,
only predefined macros can be deleted in this way. This option may be
-given more than once; undefining a @var{NAME} that does not have a
+given more than once; undefining a @var{name} that does not have a
definition is silently ignored. Order is significant with respect to
file names.
@end table
@@ -765,18 +765,18 @@ Limits control
Suppress all the extensions made in this implementation, compared to the
System V version. @xref{Compatibility}, for a list of these.
-...@item -H @var{NUM}
-...@itemx --hashsi...@var{num}
-Make the internal hash table for symbol lookup be @var{NUM} entries big.
+...@item -H @var{num}
+...@itemx --hashsi...@var{num}
+Make the internal hash table for symbol lookup be @var{num} entries big.
For better performance, the number should be prime, but this is not
checked. The default is 509 entries. It should not be necessary to
increase this value, unless you define an excessive number of macros.
-...@item -L @var{NUM}
-...@itemx --nesting-lim...@var{num}
+...@item -L @var{num}
+...@itemx --nesting-lim...@var{num}
@cindex nesting limit
@cindex limit, nesting
-Artificially limit the nesting of macro calls to @var{NUM} levels,
+Artificially limit the nesting of macro calls to @var{num} levels,
stopping program execution if this limit is ever exceeded. When not
specified, nesting defaults to unlimited on platforms that can detect
stack overflow, and to 1024 levels otherwise. A value of zero means
@@ -801,15 +801,15 @@ Limits control
system to detect and diagnose endless loops: it is a quite @emph{hard}
problem in general, if not undecidable!
-...@item -B @var{NUM}
-...@itemx -S @var{NUM}
-...@itemx -T @var{NUM}
+...@item -B @var{num}
+...@itemx -S @var{num}
+...@itemx -T @var{num}
These options are present for compatibility with System V @code{m4}, but
do nothing in this implementation. They may disappear in future
releases, and issue a warning to that effect.
-...@item -N @var{NUM}
-...@itemx --diversio...@var{num}
+...@item -N @var{num}
+...@itemx --diversio...@var{num}
These options are present only for compatibility with previous
versions of @acronym{GNU} @code{m4}, and were controlling the number of
possible diversions which could be used at the same time. They do nothing,
@@ -825,16 +825,16 @@ Frozen state
execution when reusing a common initialization script.
@table @code
-...@item -F @var{FILE}
-...@itemx --freeze-sta...@var{file}
+...@item -F @var{file}
+...@itemx --freeze-sta...@var{file}
Once execution is finished, write out the frozen state on the specified
-...@var{file}. It is conventional, but not required, for @var{FILE} to end
+...@var{file}. It is conventional, but not required, for @var{file} to end
in @samp{.m4f}.
-...@item -R @var{FILE}
-...@itemx --reload-sta...@var{file}
+...@item -R @var{file}
+...@itemx --reload-sta...@var{file}
Before execution starts, recover the internal state from the specified
-frozen @var{FILE}. The options @option{-D}, @option{-U}, and
+frozen @var{file}. The options @option{-D}, @option{-U}, and
@option{-t} take effect after state is reloaded, but before the input
files are read.
@end table
@@ -846,21 +846,21 @@ Debugging options
scripts.
@table @code
-...@item -...@r{[}@var{fla...@r{]}
-...@itemx --de...@r{[}=@var{fla...@r{]}
-Set the debug-level according to the flags @var{FLAGS}. The debug-level
+...@item -...@r{[}@var{fla...@r{]}
+...@itemx --de...@r{[}=@var{fla...@r{]}
+Set the debug-level according to the flags @var{flags}. The debug-level
controls the format and amount of information presented by the debugging
functions. @xref{Debug Levels}, for more details on the format and
-meaning of @var{FLAGS}. If omitted, @var{FLAGS} defaults to @samp{aeq}.
+meaning of @var{flags}. If omitted, @var{flags} defaults to @samp{aeq}.
-...@item --debugf...@r{[}=@var{fi...@r{]}
-...@itemx -o @var{FILE}
-...@itemx --error-outp...@var{file}
+...@item --debugf...@r{[}=@var{fi...@r{]}
+...@itemx -o @var{file}
+...@itemx --error-outp...@var{file}
Redirect @code{dumpdef} output, debug messages, and trace output to the
-named @var{FILE}. Warnings, error messages, and @code{errprint} output
+named @var{file}. Warnings, error messages, and @code{errprint} output
are still printed to standard error. If these options are not used, or
-if @var{FILE} is unspecified (only possible for @option{--debugfile}),
-debug output goes to standard error; if @var{FILE} is the empty string,
+if @var{file} is unspecified (only possible for @option{--debugfile}),
+debug output goes to standard error; if @var{file} is the empty string,
debug output is discarded. @xref{Debug Output}, for more details. The
option @option{--debugfile} may be given more than once, and order is
significant with respect to file names. The spellings @option{-o} and
@@ -886,16 +886,16 @@ Debugging options
@end example
@end ignore
-...@item -l @var{NUM}
-...@itemx --argleng...@var{num}
-Restrict the size of the output generated by macro tracing to @var{NUM}
+...@item -l @var{num}
+...@itemx --argleng...@var{num}
+Restrict the size of the output generated by macro tracing to @var{num}
characters per trace line. If unspecified or zero, output is
unlimited. @xref{Debug Levels}, for more details.
-...@item -t @var{NAME}
-...@itemx --tra...@var{name}
-This enables tracing for the macro @var{NAME}, at any point where it is
-defined. @var{NAME} need not be defined when this option is given.
+...@item -t @var{name}
+...@itemx --tra...@var{name}
+This enables tracing for the macro @var{name}, at any point where it is
+defined. @var{name} need not be defined when this option is given.
This option may be given more than once, and order is significant with
respect to file names. @xref{Trace}, for more details.
@end table
@@ -8200,7 +8200,7 @@ Improved copy
directly reference the stack definitions without a macro call, by
leaving @var{pre} and @var{post} empty. The new macro also adds a
separator that is only output after the first iteration of the helper
-...@var{_stack_reverse_sep}, implemented by prepending the original
+...@code{_stack_reverse_sep}, implemented by prepending the original
@var{sep} to @var{pre} and omitting a @var{sep} argument in subsequent
iterations. As an added bonus, using @code{stack_foreach_sep} to
implement @code{copy} performs fewer macro invocations. The improved
--
1.6.0.4
_______________________________________________
M4-patches mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/m4-patches
