GNU Info

(groff)Debugging

---

Next: Implementation Differences Prev: Gtroff Internals Up: gtroff Reference

---

Enter node , (file) or (file)node

Debugging
=========

   `gtroff' is not easy to debug, but there are some useful features
and strategies for debugging.

 - Request: .tm string
     Sends the STRING to the standard error stream; this is very useful
     for printing debugging output among other things.

 - Request: .ab [string]
     Similar to the `tm' request, except that it causes `gtroff' to
     stop processing.  With no argument it prints `User Abort'.

 - Request: .ex
     The `ex' request also causes `gtroff' to stop processing if
     encountered at the topmost level; see also Note: 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 will be many errors and no
useful output, `gtroff' can be forced to suppress formatted output with
the `-z' flag.

 - Request: .pm
     The `pm' request prints out the entire symbol table on `stderr'.

 - Request: .pnr
     Prints the names and contents of all currently defined number
     registers on `stderr'.

 - Request: .ptr
     Prints 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
     Instructs `gtroff' to flush its output immediately.  The intent is
     for interactive use.  `gtroff'; there is little other use for it.
     This request causes a line break.

 - Request: .backtrace
     The `backtrace' request prints a backtrace of the input stack to
     the standard error stream.

   `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]
     Controls 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 characters.  If an argument is not given, all warnings are
     enabled.

     The read-only number register `.warn' contains the current warning
     level.

Warnings