CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/09/27 13:21:05
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -b -r1.52 -r1.53
--- doc/m4.texinfo 26 Sep 2006 21:21:50 -0000 1.52
+++ doc/m4.texinfo 27 Sep 2006 13:21:05 -0000 1.53
@@ -692,9 +692,13 @@
@item -l @var{NUM}
@itemx [EMAIL PROTECTED]
-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.
+Restrict the size of the output generated by macro tracing or by
[EMAIL PROTECTED] to @var{NUM} characters per string. If unspecified or
+zero, output is unlimited. @xref{Debug Levels}, for more details.
[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?
@item -t @var{NAME}
@itemx [EMAIL PROTECTED]
@@ -2640,19 +2644,22 @@
@xref{Debug Levels}, for information on how the @samp{q} and @samp{s}
flags affect the details of the display. Remember, the @samp{q} flag is
-implied when @option{-d} is used in the command line without arguments.
+implied when the @option{--debug} option (@option{-d}, @pxref{Invoking
+m4}) is used in the command line without arguments. Also, the
[EMAIL PROTECTED] option (@option{-l}) can affect output, by
+truncating longer strings.
[EMAIL PROTECTED] options: -ds
[EMAIL PROTECTED] options: -ds -l3
@example
-$ @kbd{m4 -ds}
-pushdef(`foo', `1')
+$ @kbd{m4 -ds -l 3}
+pushdef(`foo', `1 long string')
@result{}
pushdef(`foo', defn(`divnum'))
@result{}
pushdef(`foo', `3')
@result{}
dumpdef(`foo')
[EMAIL PROTECTED]:@tabchar{}3, <divnum>, 1
[EMAIL PROTECTED]:@tabchar{}3, <div...>, 1 l...
@result{}
@end example
@@ -2883,7 +2890,9 @@
@table @code
@item a
In trace output, show the actual arguments that were collected before
-invoking the macro.
+invoking the macro. Arguments are subject to length truncation
+specified by the command line option @option{--arglength}
+(@option{-l}).
@item c
In trace output, show several trace lines for each macro call. A line
@@ -2893,7 +2902,8 @@
@item e
In trace output, show the expansion of each macro call, if it is not
-void.
+void. The expansion is subject to length truncation specified by the
+command line option @option{--arglength} (@option{-l}).
@item f
In debug and trace output, include the name of the current input file in
@@ -2944,10 +2954,30 @@
Without either of these starting characters, @var{flags} simply replaces
the previous setting.
-If no flags are specified with the @option{-d} option, the default is
+If no flags are specified with the @option{--debug} option, the default is
@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:
@@ -2955,7 +2985,7 @@
@deffn {Builtin (gnu)} debugmode (@ovar{flags})
The argument @var{flags} should be a subset of the letters listed above.
If no argument is present, all debugging flags are cleared
-(as if no @option{-d} was given), and with an empty argument the flags
+(as if no @option{--debug} was given), and with an empty argument the flags
are reset to the default of @samp{aeq}. If an unknown flag is
encountered, an error is issued.
