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.
Menu