Changes to m4/doc/m4.texinfo,v

[Eric Blake]

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}),
address@hidden (@pxref{Debug Output}), @code{syscmd} (@pxref{Syscmd}),
address@hidden (@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 address@hidden@address@hidden
 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}
address@hidden address@hidden
 @itemx address@hidden
 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.
address@hidden can have an optional scaling suffix.
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?
+zero, output is unlimited.  @xref{Debuglen}, for more details.
address@hidden can have an optional scaling suffix.  The spelling
address@hidden is deprecated, since it does not match the
address@hidden macro; using it will evoke a warning, and it may be
+withdrawn in a future release.
address@hidden FIXME - Should we add an option that controls whether output
address@hidden strings are sanitized with escape sequences, so that dumpdef is
address@hidden 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
 
address@hidden Levels}, for information on how the @samp{m}, @samp{q}, and
address@hidden, 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 (@address@hidden)
 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,
address@hidden).
 
 @example
 $ @kbd{m4 -d}
@@ -2882,11 +2887,11 @@
 @result{}1 2
 @end example
 
address@hidden Levels}, for information on controlling the details of the
address@hidden, for information on controlling the details of the
 display.
 
address@hidden Debug Levels
address@hidden Controlling debugging output
address@hidden Debugmode
address@hidden 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
address@hidden (@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.
 
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:
@@ -3034,7 +3018,64 @@
 @result{}FOO
 @end example
 
address@hidden Debug Output
address@hidden Debuglen
address@hidden Limiting debug output
+
address@hidden @acronym{GNU} extensions
address@hidden arglength
address@hidden debuglen
address@hidden limiting trace output length
address@hidden trace output, limiting length
address@hidden 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},
address@hidden m4}), allow on-the-fly control of debugging string
+lengths:
+
address@hidden {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.
address@hidden FIXME - make this understand an optional suffix, similar to how
address@hidden --debuglen does.  Also, we need a section documenting scaling
address@hidden suffixes.
address@hidden FIXME - should we allow len to be `?', meaning expand to the
address@hidden current value?
+
+The macro @code{debuglen} is recognized only with parameters.
address@hidden deffn
+
address@hidden options: -l4 -techo
address@hidden
+$ @kbd{m4 -d -l 4 -t echo}
+debuglen(`oops')
address@hidden:stdin:1: Warning: debuglen: non-numeric argument `oops'
address@hidden
+define(`echo', `$@')
address@hidden
+echo(`long string')
address@hidden: -1- echo(`long...') -> ``lon...'
address@hidden string
+debuglen
address@hidden
+debuglen(`0')
address@hidden
+echo(`long string')
address@hidden: -1- echo(`long string') -> ``long string''
address@hidden string
+debuglen(`12')
address@hidden
+echo(`long string')
address@hidden: -1- echo(`long string') -> ``long string...'
address@hidden string
address@hidden example
+
address@hidden 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
address@hidden and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
address@hidden 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
address@hidden (@pxref{Debug Output}).
address@hidden (@pxref{Debugfile}).
 @end itemize
 
 Additionally, @acronym{POSIX} only requires support for the command line