Info: (groff) Debugging

Info Catalog
groff: Gtroff Internals
groff: gtroff Reference
groff: Implementation Differences
groff: Debugging

 
 5.33 Debugging
 ==============
 
 'gtroff' is not easy to debug, but there are some useful features and
 strategies for debugging.
 
  -- Request: .lf line [filename]
      Change the line number and optionally the file name 'gtroff' shall
      use for error and warning messages.  LINE is the input line number
      of the _next_ line.
 
      Without argument, the request is ignored.
 
      This is a debugging aid for documents that are split into many
      files, then put together with 'soelim' and other preprocessors.
      Usually, it isn't invoked manually.
 
      Note that other 'troff' implementations (including the original
      AT&T version) handle 'lf' differently.  For them, LINE changes the
      line number of the _current_ line.
 
  -- Request: .tm string
  -- Request: .tm1 string
  -- Request: .tmc string
      Send STRING to the standard error output; this is very useful for
      printing debugging messages among other things.
 
      STRING is read in copy mode.
 
      The 'tm' request ignores leading spaces of STRING; 'tm1' handles
      its argument similar to the 'ds' request: a leading double quote in
      STRING is stripped to allow initial blanks.
 
      The 'tmc' request is similar to 'tm1' but does not append a newline
      (as is done in 'tm' and 'tm1').
 
  -- Request: .ab [string]
      Similar to the 'tm' request, except that it causes 'gtroff' to stop
      processing.  With no argument it prints 'User Abort.' to standard
      error.
 
  -- Request: .ex
      The 'ex' request also causes 'gtroff' to stop processing; see also
      I/O.
 
    When doing something involved it is useful to leave the debugging
 statements in the code and have them turned on by a command line flag.
 
      .if \n(DB .tm debugging output
 
 To activate these statements say
 
      groff -rDB=1 file
 
    If it is known in advance that there are many errors and no useful
 output, 'gtroff' can be forced to suppress formatted output with the
 '-z' flag.
 
  -- Request: .pev
      Print the contents of the current environment and all the currently
      defined environments (both named and numbered) on 'stderr'.
 
  -- Request: .pm
      Print the entire symbol table on 'stderr'.  Names of all defined
      macros, strings, and diversions are print together with their size
      in bytes.  Since 'gtroff' sometimes adds nodes by itself, the
      returned size can be larger than expected.
 
      This request differs from UNIX 'troff': 'gtroff' reports the sizes
      of diversions, ignores an additional argument to print only the
      total of the sizes, and the size isn't returned in blocks of 128
      characters.
 
  -- Request: .pnr
      Print the names and contents of all currently defined number
      registers on 'stderr'.
 
  -- Request: .ptr
      Print the names and positions of all traps (not including input
      line traps and diversion traps) on 'stderr'.  Empty slots in the
      page trap list are printed as well, because they can affect the
      priority of subsequently planted traps.
 
  -- Request: .fl
      Instruct 'gtroff' to flush its output immediately.  The intent is
      for interactive use, but this behaviour is currently not
      implemented in 'gtroff'.  Contrary to UNIX 'troff', TTY output is
      sent to a device driver also ('grotty'), making it non-trivial to
      communicate interactively.
 
      This request causes a line break.
 
  -- Request: .backtrace
      Print a backtrace of the input stack to the standard error stream.
 
      Consider the following in file 'test':
 
           .de xxx
           .  backtrace
           ..
           .de yyy
           .  xxx
           ..
           .
           .yyy
 
      On execution, 'gtroff' prints the following:
 
           test:2: backtrace: macro `xxx'
           test:5: backtrace: macro `yyy'
           test:8: backtrace: file `test'
 
      The option '-b' of 'gtroff' internally calls a variant of this
      request on each error and warning.
 
  -- Register: \n[slimit]
      Use the 'slimit' number register to set the maximum number of
      objects on the input stack.  If 'slimit' is less than or equal
      to 0, there is no limit set.  With no limit, a buggy recursive
      macro can exhaust virtual memory.
 
      The default value is 1000; this is a compile-time constant.
 
  -- Request: .warnscale si
      Set the scaling indicator used in warnings to SI.  Valid values for
      SI are 'u', 'i', 'c', 'p', and 'P'.  At startup, it is set to 'i'.
 
  -- Request: .spreadwarn [limit]
      Make 'gtroff' emit a warning if the additional space inserted for
      each space between words in an output line is larger or equal to
      LIMIT.  A negative value is changed to zero; no argument toggles
      the warning on and off without changing LIMIT.  The default scaling
      indicator is 'm'.  At startup, 'spreadwarn' is deactivated, and
      LIMIT is set to 3m.
 
      For example,
 
           .spreadwarn 0.2m
 
      causes a warning if 'gtroff' must add 0.2m or more for each
      interword space in a line.
 
      This request is active only if text is justified to both margins
      (using '.ad b').
 
    'gtroff' has command line options for printing out more warnings
 ('-w') and for printing backtraces ('-b') when a warning or an error
 occurs.  The most verbose level of warnings is '-ww'.
 
  -- Request: .warn [flags]
  -- Register: \n[.warn]
      Control the level of warnings checked for.  The FLAGS are the sum
      of the numbers associated with each warning that is to be enabled;
      all other warnings are disabled.  The number associated with each
      warning is listed below.  For example, '.warn 0' disables all
      warnings, and '.warn 1' disables all warnings except that about
      missing glyphs.  If no argument is given, all warnings are enabled.
 
      The read-only number register '.warn' contains the current warning
      level.
groff: Debugging

Menu
