gtroff is not easy to debug, but there are some useful features
and strategies for debugging.
Without argument, the request is ignored.
This is a debugging aid for documents which are split into many files, then put together with
soelimand other preprocessors. Usually, it isn't invoked manually.
Note that other
troffimplementations (including the original AT&T version) handle
lfdifferently. For them, line changes the line number of the current line.
tmrequest ignores leading spaces of string;
tm1handles its argument similar to the
dsrequest: a leading double quote in string is stripped to allow initial blanks.
tmcrequest is similar to
tm1but does not append a newline (as is done in
exrequest also causes
gtroffto 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
gtroff can be forced to suppress formatted output with
the -z flag.
Print the entire symbol table on
stderr. Names of all defined macros, strings, and diversions are print together with their size in bytes. Since
gtroffsometimes adds nodes by itself, the returned size can be larger than expected.
This request differs from UNIX
gtroffreports 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.
gtroffto 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.
Consider the following in file test:.de xxx . backtrace .. .de yyy . xxx .. . .yyy
gtroffprints the following:test:2: backtrace: macro `xxx' test:5: backtrace: macro `yyy' test:8: backtrace: file `test'
The option -b of
gtroffinternally calls a variant of this request on each error and warning.
gtroffemit 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,
spreadwarnis deactivated, and limit is set to 3m.
For example,.spreadwarn 0.2m
causes a warning if
gtroffmust 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 0disables all warnings, and
.warn 1disables all warnings except that about missing glyphs. If no argument is given, all warnings are enabled.
The read-only number register
.warncontains the current warning level.