Next: Implementation Differences, Previous: Gtroff Internals, Up: gtroff Reference [Contents][Index]
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 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.
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).
Similar to the tm request, except that it causes gtroff to
stop processing. With no argument it prints ‘User Abort.’ to
standard error.
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.
Print the contents of the current environment and all the currently
defined environments (both named and numbered) on stderr.
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.
Print the names and contents of all currently defined number registers
on stderr.
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.
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.
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.
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.
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’.
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.
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.
| • Warnings: |
Next: Implementation Differences, Previous: Gtroff Internals, Up: gtroff Reference [Contents][Index]