gtroff is not easy to debug, but there are some useful features
and strategies for debugging.
Change the line number and optionally the file name
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.
Send string to the standard error output; this is very useful for printing debugging messages among other things.
string is read in copy mode.
tm request ignores leading spaces of string;
handles its argument similar to the
ds request: a leading double
quote in string is stripped to allow initial blanks.
tmc request is similar to
tm1 but does not append a
newline (as is done in
Similar to the
tm request, except that it causes
stop processing. With no argument it prints ‘User Abort.’ to
ex request also causes
gtroff to stop processing; see
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
gtroff can be forced to suppress formatted output with
the -z flag.
Print the contents of the current environment and all the currently
defined environments (both named and numbered) on
Print the entire symbol table on
stderr. Names of all defined
macros, strings, and diversions are print together with their size in
gtroff sometimes adds nodes by itself, the returned
size can be larger than expected.
This request differs from Unix
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
Print the names and contents of all currently defined number registers
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.
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
This request causes a line break.
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
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.
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.
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’.
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,
deactivated, and limit is set to 3m.
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.
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,
.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