Changes to m4/doc/m4.texinfo,v

[Eric Blake]

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 address@hidden
-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
address@hidden to @var{NUM} characters per string.  If unspecified or
+zero, output is unlimited.  @xref{Debug Levels}, for more details.
address@hidden FIXME - should we add a debuglen macro that can alter this
address@hidden setting on the fly?  Also, should we add an option that
address@hidden controls whether output strings are sanitized with escape
address@hidden sequences, so that dumpdef is truly one line per macro?
 
 @item -t @var{NAME}
 @itemx address@hidden
@@ -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
address@hidden option (@option{-l}) can affect output, by
+truncating longer strings.
 
address@hidden options: -ds
address@hidden 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')
address@hidden:@tabchar{}3, <divnum>, 1
address@hidden:@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.
 
address@hidden FIXME - add a new macro debuglen (or some other spelling) that
address@hidden allows changing the -l/--arglength option on the fly?  If so,
address@hidden 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.
+
address@hidden options: -l4 -techo
address@hidden
+$ @kbd{m4 -d -l 4 -t echo}
+define(`echo', `$@')
address@hidden
+echo(`long string')
address@hidden: -1- echo(`long...') -> ``lon...'
address@hidden string
address@hidden 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.