Standard troff voodoo, just put a power of two backslashes in front of it until it works and if you still have problems add a \c. — Ron Natalie
GNU troff
is not the easiest language to debug, in part thanks to
its design features of recursive interpolation and the use of multi-stage
pipeline processing in the surrounding system. Nevertheless there exist
several features useful for troubleshooting.
Preprocessors use the lf
request to preserve the identity of the
line numbers and names of input files. GNU troff
emits a variety
of error diagnostics and supports several categories of warning; the
output of these can be selectively suppressed. Backtraces can be
enabled when errors or warnings occur, or triggered on demand. The
tm
and related requests can be used to emit customized diagnostic
messages or for instrumentation while troubleshooting. The ex
and ab
requests cause early termination with successful and error
exit codes respectively, to halt further processing when continuing
would be fruitless. The state of the formatter can be examined with
requests that write lists of defined names (macros, strings, and
diversions), environments, registers, and page location traps to the
standard error stream.
.lf
line [filename] ¶Change the line number and optionally the file name GNU troff
shall use for error and warning messages. line is the input line
number of the next line. Without an argument, the request is
ignored.
This request is primarily a debugging aid for documents that undergo
preprocessing. Programs like tbl
that transform input in
their own languages to roff
requests use it so that any
diagnostic messages emitted by troff
correspond to the original
source document.
.tm
contents ¶.tm1
contents ¶.tmc
contents ¶Send contents, which consumes the remainder of the input line, to the standard error stream.
The tm
request ignores leading spaces of contents;
tm1
handles its argument similarly to the ds
request: an
initial neutral double quote is stripped to allow embedding of leading
spaces.
The tmc
request is similar to tm1
but does not append a
newline (as is done in tm
and tm1
).
.ab
[contents] ¶Write any contents to the standard error stream (like tm
)
and then abort GNU troff
; that is, stop processing and terminate
with a failure status.
.ex
¶Exit GNU troff
; that is, stop processing and terminate with a
successful status. To stop processing only the current file, use the
nx
request; see 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 such statements, use the -r option to set the register.
groff -rDB=1 file
If it is known in advance that there are many errors and no useful
output, GNU troff
can be forced to suppress formatted output with
the -z option.
.pev
¶Report the state of the current environment followed by that of all other environments to the standard error stream.
.pm
¶Report, to the standard error stream, the names of all defined macros,
strings, and diversions with their sizes in bytes. Since GNU
troff
sometimes adds nodes by itself, the returned sizes can be
larger than expected.
.pnr
¶Report the names and contents of all currently defined registers to the standard error stream.
.ptr
¶Report the names and positions of all page location traps to the standard error stream. Empty slots in the list, where a trap has been planted but subsequently (re)moved, are printed as well.
.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.
.backtrace
¶Write a backtrace of the input stack to the standard error stream.
Consider the following in a file test.
.de xxx . backtrace .. .de yyy . xxx .. . .yyy error→ troff: backtrace: 'test':2: macro 'xxx' error→ troff: backtrace: 'test':5: macro 'yyy' error→ troff: backtrace: file 'test':8
The -b option of GNU troff
causes a backtrace to be
generated on each error or warning. Some warnings have to be enabled;
See Warnings.
\n[slimit]
¶If greater than 0, sets the maximum quantity of objects on GNU
troff
’s internal input stack. If less than or equal to 0,
there is no limit: recursion can continue until program memory is
exhausted. The default is 1,000.
.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’.
.spreadwarn
[limit] ¶Emit a break
warning if the additional space inserted for each
space between words in an output line adjusted to both margins with
‘.ad b’ is larger than or equal to limit. A negative
value is treated as zero; an absent argument toggles the warning on and
off without changing limit. The default scaling indicator is
‘m’. At startup, spreadwarn
is inactive and limit is
3m.
For example,
.spreadwarn 0.2m
causes a warning if break
warnings are not suppressed and
gtroff
must add 0.2m or more for each inter-word space in a
line. See Warnings.
GNU troff
has command-line options for reporting warnings
(-w) and backtraces (-b) when a warning or an error
occurs.
.warn
[n] ¶\n[.warn]
¶Select the categories, or “types”, of reported warnings. n is the sum of the numeric codes associated with each warning category that is to be enabled; all other categories are disabled. The categories and their associated codes are listed in Warnings. For example, ‘.warn 0’ disables all warnings, and ‘.warn 1’ disables all warnings except those about missing glyphs. If no argument is given, all warning categories are enabled.
The read-only register .warn
contains the sum of the numeric
codes of enabled warning categories.