CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/10/06 15:24:10
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -b -r1.58 -r1.59
--- doc/m4.texinfo 4 Oct 2006 03:57:00 -0000 1.58
+++ doc/m4.texinfo 6 Oct 2006 15:24:10 -0000 1.59
@@ -191,8 +191,9 @@
* Dumpdef:: Displaying macro definitions
* Trace:: Tracing macro calls
-* Debug Levels:: Controlling debugging output
-* Debug Output:: Saving debugging output
+* Debugmode:: Controlling debugging options
+* Debuglen:: Limiting debug output
+* Debugfile:: Saving debugging output
Input control
@@ -496,7 +497,7 @@
@item --safer
Cripple the builtins @code{maketemp} (@pxref{Maketemp}),
[EMAIL PROTECTED] (@pxref{Debug Output}), @code{syscmd} (@pxref{Syscmd}),
[EMAIL PROTECTED] (@pxref{Debugfile}), @code{syscmd} (@pxref{Syscmd}),
and @code{esyscmd} (@pxref{Esyscmd}), since they can perform potentially
unsafe actions. An attempt to use these macros will result in an error.
This option is intended to make it safer to preprocess an input file of
@@ -679,7 +680,7 @@
@itemx [EMAIL PROTECTED]@[EMAIL PROTECTED]
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
+functions. @xref{Debugmode}, for more details on the format and
meaning of @var{FLAGS}. If omitted, @var{FLAGS} defaults to
@samp{aeq}. When the option is presented multiple times, if later
@var{FLAGS} starts with @samp{-} or @samp{+}, they are cumulative,
@@ -692,22 +693,25 @@
error messages, and the output of @code{errprint} and @code{dumpdef},
are still printed to standard error. If this option is not given, debug
output goes to standard error; if @var{FILE} is the empty string, debug
-output is discarded. @xref{Debug Output}, for more details. The
+output is discarded. @xref{Debugfile}, for more details. The
spellings @option{-o} and @option{--error-output} are misleading and
inconsistent with other @acronym{GNU} tools; using those spellings will
evoke a warning, and they may be withdrawn or change semantics in a
future release.
@item -l @var{NUM}
[EMAIL PROTECTED] [EMAIL PROTECTED]
@itemx [EMAIL PROTECTED]
Restrict the size of the output generated by macro tracing or by
@code{dumpdef} to @var{NUM} characters per string. If unspecified or
-zero, output is unlimited. @xref{Debug Levels}, for more details.
[EMAIL PROTECTED] can have an optional scaling suffix.
[EMAIL PROTECTED] FIXME - should we add a debuglen macro that can alter this
[EMAIL PROTECTED] setting on the fly? Also, should we add an option that
[EMAIL PROTECTED] controls whether output strings are sanitized with escape
[EMAIL PROTECTED] sequences, so that dumpdef is truly one line per macro?
+zero, output is unlimited. @xref{Debuglen}, for more details.
[EMAIL PROTECTED] can have an optional scaling suffix. The spelling
[EMAIL PROTECTED] is deprecated, since it does not match the
[EMAIL PROTECTED] macro; using it will evoke a warning, and it may be
+withdrawn in a future release.
[EMAIL PROTECTED] FIXME - Should we add an option that controls whether output
[EMAIL PROTECTED] strings are sanitized with escape sequences, so that dumpdef
is
[EMAIL PROTECTED] truly one line per macro?
@comment FIXME - see comment on --nesting-limit about NUM.
@item -t @var{NAME}
@@ -2596,8 +2600,9 @@
@menu
* Dumpdef:: Displaying macro definitions
* Trace:: Tracing macro calls
-* Debug Levels:: Controlling debugging output
-* Debug Output:: Saving debugging output
+* Debugmode:: Controlling debugging options
+* Debuglen:: Limiting debug output
+* Debugfile:: Saving debugging output
@end menu
@node Dumpdef
@@ -2650,12 +2655,12 @@
@result{}f1
@end example
[EMAIL PROTECTED] Levels}, for information on how the @samp{m}, @samp{q}, and
[EMAIL PROTECTED], for information on how the @samp{m}, @samp{q}, and
@samp{s} flags affect the details of the display. Remember, the
@samp{q} flag is implied when the @option{--debug} option (@option{-d},
@pxref{Invoking m4}) is used in the command line without arguments.
-Also, the @option{--arglength} option (@option{-l}) can affect output,
-by truncating longer strings.
+Also, @code{--debuglen} (@pxref{Debuglen}) can affect output, by
+truncating longer strings.
@comment options: -ds -l3
@example
@@ -2691,7 +2696,7 @@
@deffnx {Builtin (m4)} traceoff (@[EMAIL PROTECTED])
When called without any arguments, @code{traceon} and @code{traceoff}
will turn tracing on and off, respectively, for all macros, identical to
-using the @samp{t} flag of @code{debugmode} (@pxref{Debug Levels}).
+using the @samp{t} flag of @code{debugmode} (@pxref{Debugmode}).
When called with arguments, only the named macros are affected, whether
or not they are currently defined. A macro's expansion will be traced
if global tracing is on, or if the individual macro tracing flag is
@@ -2704,8 +2709,8 @@
Whenever a traced macro is called and the arguments have been collected,
the call is displayed. If the expansion of the macro call is not void,
the expansion can be displayed after the call. The output is printed
-to the current debug file (defaulting to standard error, @pxref{Debug
-Output}).
+to the current debug file (defaulting to standard error,
[EMAIL PROTECTED]).
@example
$ @kbd{m4 -d}
@@ -2882,11 +2887,11 @@
@result{}1 2
@end example
[EMAIL PROTECTED] Levels}, for information on controlling the details of the
[EMAIL PROTECTED], for information on controlling the details of the
display.
[EMAIL PROTECTED] Debug Levels
[EMAIL PROTECTED] Controlling debugging output
[EMAIL PROTECTED] Debugmode
[EMAIL PROTECTED] Controlling debugging options
@cindex controlling debugging output
@cindex debugging output, controlling
@@ -2906,8 +2911,7 @@
@item a
In trace output, show the actual arguments that were collected before
invoking the macro. Arguments are subject to length truncation
-specified by the command line option @option{--arglength}
-(@option{-l}).
+specified by @code{debuglen} (@pxref{Debuglen}).
@item c
In trace output, show several trace lines for each macro call. A line
@@ -2917,8 +2921,8 @@
@item e
In trace output, show the expansion of each macro call, if it is not
-void. The expansion is subject to length truncation specified by the
-command line option @option{--arglength} (@option{-l}).
+void. The expansion is subject to length truncation specified by
[EMAIL PROTECTED] (@pxref{Debuglen}).
@item f
In debug and trace output, include the name of the current input file in
@@ -2978,26 +2982,6 @@
@samp{aeq}. Many examples in this manual show their output using
default flags.
[EMAIL PROTECTED] FIXME - add a new macro debuglen (or some other spelling) that
[EMAIL PROTECTED] allows changing the -l/--arglength option on the fly? If so,
[EMAIL PROTECTED] add a new node here describing it.
-Also, the option @option{--arglength} (@option{-l}) can affect trace
-and dumpdef output. If the option is specified to a non-zero value,
-then strings longer than that length are truncated, and @samp{...}
-included in the output to show that truncation took place. This allows
-reducing the size of the debug output in the face of arbitrarily long
-macro arguments or definitions.
-
[EMAIL PROTECTED] options: -l4 -techo
[EMAIL PROTECTED]
-$ @kbd{m4 -d -l 4 -t echo}
-define(`echo', `$@')
[EMAIL PROTECTED]
-echo(`long string')
[EMAIL PROTECTED]: -1- echo(`long...') -> ``lon...'
[EMAIL PROTECTED] string
[EMAIL PROTECTED] example
-
@cindex @acronym{GNU} extensions
There is a builtin macro @code{debugmode}, which allows on-the-fly control of
the debugging output format:
@@ -3034,7 +3018,64 @@
@result{}FOO
@end example
[EMAIL PROTECTED] Debug Output
[EMAIL PROTECTED] Debuglen
[EMAIL PROTECTED] Limiting debug output
+
[EMAIL PROTECTED] @acronym{GNU} extensions
[EMAIL PROTECTED] arglength
[EMAIL PROTECTED] debuglen
[EMAIL PROTECTED] limiting trace output length
[EMAIL PROTECTED] trace output, limiting length
[EMAIL PROTECTED] dumpdef output, limiting length
+When debugging, sometimes it is desirable to reduce the clutter of
+arbitrary-length strings, because the prefix carries enough information
+to understand the issues. The builtin macro @code{debuglen}, along with
+the command line option counterpart @option{--debuglen} (or @option{-l},
[EMAIL PROTECTED] m4}), allow on-the-fly control of debugging string
+lengths:
+
[EMAIL PROTECTED] {Builtin (gnu)} debuglen (@var{len})
+The argument @var{len} is an integer that controls how much of
+arbitrary-length strings should be output during trace and dumpdef
+output. If specified to a non-zero value, then strings longer than that
+length are truncated, and @samp{...} included in the output to show that
+truncation took place. A warning is issued if @var{len} cannot be
+parsed as an integer.
[EMAIL PROTECTED] FIXME - make this understand an optional suffix, similar to
how
[EMAIL PROTECTED] --debuglen does. Also, we need a section documenting scaling
[EMAIL PROTECTED] suffixes.
[EMAIL PROTECTED] FIXME - should we allow len to be `?', meaning expand to the
[EMAIL PROTECTED] current value?
+
+The macro @code{debuglen} is recognized only with parameters.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] options: -l4 -techo
[EMAIL PROTECTED]
+$ @kbd{m4 -d -l 4 -t echo}
+debuglen(`oops')
[EMAIL PROTECTED]:stdin:1: Warning: debuglen: non-numeric argument `oops'
[EMAIL PROTECTED]
+define(`echo', `$@')
[EMAIL PROTECTED]
+echo(`long string')
[EMAIL PROTECTED]: -1- echo(`long...') -> ``lon...'
[EMAIL PROTECTED] string
+debuglen
[EMAIL PROTECTED]
+debuglen(`0')
[EMAIL PROTECTED]
+echo(`long string')
[EMAIL PROTECTED]: -1- echo(`long string') -> ``long string''
[EMAIL PROTECTED] string
+debuglen(`12')
[EMAIL PROTECTED]
+echo(`long string')
[EMAIL PROTECTED]: -1- echo(`long string') -> ``long string...'
[EMAIL PROTECTED] string
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] Debugfile
@section Saving debugging output
@cindex saving debugging output
@@ -3860,7 +3901,7 @@
a colon-separated list of directories, which will be searched in order.
If the automatic search for include-files causes trouble, the @samp{p}
-debug flag (@pxref{Debug Levels}) can help isolate the problem.
+debug flag (@pxref{Debugmode}) can help isolate the problem.
@node Diversions
@chapter Diverting and undiverting output
@@ -5080,7 +5121,7 @@
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
[EMAIL PROTECTED] and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
[EMAIL PROTECTED] and @samp{l} flags of @code{debugmode} (@pxref{Debugmode}),
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.
@@ -5454,11 +5495,11 @@
@item
The format of the output from @code{dumpdef} and macro tracing can be
-controlled with @code{debugmode} (@pxref{Debug Levels}).
+controlled with @code{debugmode} (@pxref{Debugmode}).
@item
The destination of trace and debug output can be controlled with
[EMAIL PROTECTED] (@pxref{Debug Output}).
[EMAIL PROTECTED] (@pxref{Debugfile}).
@end itemize
Additionally, @acronym{POSIX} only requires support for the command line
