m4: Debug Levels

1 
1 7.3 Controlling debugging output
1 ================================
1 
11 The '-d' option to 'm4' (or '--debug', ⇒Invoking m4 Debugging
 options.) controls the amount of details presented in three categories
1 of output.  Trace output is requested by 'traceon' (⇒Trace), and
1 each line is prefixed by 'm4trace:' in relation to a macro invocation.
1 Debug output tracks useful events not associated with a macro
1 invocation, and each line is prefixed by 'm4debug:'.  Finally, 'dumpdef'
1 (⇒Dumpdef) output is affected, with no prefix added to the output
1 lines.
1 
1    The FLAGS following the option can be one or more of the following:
1 
1 'a'
1      In trace output, show the actual arguments that were collected
1      before invoking the macro.  This applies to all macro calls if the
1      't' flag is used, otherwise only the macros covered by calls of
1      'traceon'.  Arguments are subject to length truncation specified by
1      the command line option '--arglength' (or '-l').
1 
1 'c'
1      In trace output, show several trace lines for each macro call.  A
1      line is shown when the macro is seen, but before the arguments are
1      collected; a second line when the arguments have been collected and
1      a third line after the call has completed.
1 
1 'e'
1      In trace output, show the expansion of each macro call, if it is
1      not void.  This applies to all macro calls if the 't' flag is used,
1      otherwise only the macros covered by calls of 'traceon'.  The
1      expansion is subject to length truncation specified by the command
1      line option '--arglength' (or '-l').
1 
1 'f'
1      In debug and trace output, include the name of the current input
1      file in the output line.
1 
1 'i'
1      In debug output, print a message each time the current input file
1      is changed.
1 
1 'l'
1      In debug and trace output, include the current input line number in
1      the output line.
1 
1 'p'
1      In debug output, print a message when a named file is found through
1      the path search mechanism (⇒Search Path), giving the actual
1      file name used.
1 
1 'q'
1      In trace and dumpdef output, quote actual arguments and macro
1      expansions in the display with the current quotes.  This is useful
1      in connection with the 'a' and 'e' flags above.
1 
1 't'
1      In trace output, trace all macro calls made in this invocation of
1      'm4', regardless of the settings of 'traceon'.
1 
1 'x'
1      In trace output, add a unique 'macro call id' to each line of the
1      trace output.  This is useful in connection with the 'c' flag
1      above.
1 
1 'V'
1      A shorthand for all of the above flags.
1 
1    If no flags are specified with the '-d' option, the default is 'aeq'.
1 The examples throughout this manual assume the default flags.
1 
1    There is a builtin macro 'debugmode', which allows on-the-fly control
1 of the debugging output format:
1 
1  -- Builtin: debugmode ([FLAGS])
1      The argument FLAGS should be a subset of the letters listed above.
1      As special cases, if the argument starts with a '+', the flags are
1      added to the current debug flags, and if it starts with a '-', they
1      are removed.  If no argument is present, all debugging flags are
1      cleared (as if no '-d' was given), and with an empty argument the
1      flags are reset to the default of 'aeq'.
1 
1      The expansion of 'debugmode' is void.
1 
1      $ m4
1      define(`foo', `FOO')
1      =>
1      traceon(`foo')
1      =>
1      debugmode()
1      =>
1      foo
1      error->m4trace: -1- foo -> `FOO'
1      =>FOO
1      debugmode
1      =>
1      foo
1      error->m4trace: -1- foo
1      =>FOO
1      debugmode(`+l')
1      =>
1      foo
1      error->m4trace:8: -1- foo
1      =>FOO
1 
1    The following example demonstrates the behavior of length truncation,
1 when specified on the command line.  Note that each argument and the
1 final result are individually truncated.  Also, the special tokens for
1 builtin functions are not truncated.
1 
1      $ m4 -d -l 6
1      define(`echo', `$@')debugmode(`+t')
1      =>
1      echo(`1', `long string')
1      error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
1      =>1,long string
1      indir(`echo', defn(`changequote'))
1      error->m4trace: -2- defn(`change...')
1      error->m4trace: -1- indir(`echo', <changequote>) -> ``''
1      =>
1 
1    This example shows the effects of the debug flags that are not
1 related to macro tracing.
1 
1      $ m4 -dip -I examples
1      error->m4debug: input read from stdin
1      include(`foo')dnl
1      error->m4debug: path search for `foo' found `examples/foo'
1      error->m4debug: input read from examples/foo
1      =>bar
1      error->m4debug: input reverted to stdin, line 1
1      ^D
1      error->m4debug: input exhausted
1