Next: Implementation Differences, Previous: GNU troff Internals, Up: GNU troff Reference [Contents][Index]
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
The
roff
language family
is not the easiest 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 each category can be selectively enabled or suppressed.
A trace of the formatter’s input processing stack
can be emitted when errors or warnings occur
by means of
GNU
troff’s -b
option,
or produced on demand with the
backtrace
request.
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.
Examine the state of the formatter with requests that write lists of
defined names—macros, strings, and diversions—colors,
composite character mappings,
environments,
occupied font mounting positions,
font translations,
automatic hyphenation codes
and exceptions,
registers,
open streams,
and page location traps.
Requests can also disclose
to the standard error stream
the internal properties and representations of
characters and classes,
macros
(and strings and diversions),
and the list of output nodes corresponding to the pending output line.
Recall GNU troff Internals.
"]file-identifier]Set the input line number
(and,
optionally,
the file name)
the formatter uses when reporting diagnostics.
The argument becomes the input line number of the
next
line the formatter reads.
file-identifier
is a sequence of ordinary characters and/or spaces.
GNU
troff removes a leading neutral double quote
‘"’
from
file-identifier,
permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
Recall Copy Mode.
lf’s primary purpose is to aid the debugging of documents that
undergo preprocessing. Programs like tbl that transform input
in their own languages into roff requests use it so that any
diagnostic messages emitted by a subsequent preprocessor or by
troff correspond to the source document.
"]message"]messageSend
terminal-message
to the standard error stream.
The formatter reads the argument
to the end of the input line in copy mode
(recall Copy Mode),
but does
not
remove a leading double quote;
contrast
tm1.
tm1
removes a leading neutral double quote
‘"’
from
message,
permitting initial embedded spaces in it.
tmc works as
tm1,
but does not append a newline.
Write any
terminal-message
to the standard error stream
(like
tm)
and then abort the formatter;
that is,
stop processing and terminate with a failure status.
Aborting does not flush a partially collected line,
a potentially significant fact if you’re using
ab
to “bisect” a troublesome document or macro definition;
see the
fl
request below.
Exit the formatter;
that is,
stop processing and terminate successfully.
To stop processing only the current file,
use the
nx
request;
recall Host System Service Access.
When doing something complicated, 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 you know in advance that there are many errors and no useful output,
or are interested only in diagnostic output, you can suppress GNU
troff’s formatted output with its -z option.
Report,
to the standard error stream,
information about each character
(be it
ordinary,
special,
or indexed)
or character class c.
A character defined by a request
(char,
fchar,
fschar,
or
schar)
reports its contents as a JSON-encoded string,
but the output is not otherwise in JSON format.
Report, to the standard error stream, each defined color named col, its color space identifier, and channel value assignments, or, without arguments, those of all defined colors. A device’s default stroke and/or fill colors, “default”, are not listed since they are immutable and their details unknown to the formatter.
Report,
to the standard error stream,
the list of configured composite character mappings.
Recall the composite request description in Characters and Glyphs.
The “from” code point is listed first,
followed by its “to” mapping.
Report the state of the current environment followed by that of all other environments to the standard error stream.
Report,
to the standard error stream,
the list of occupied font mounting positions.
Recall the
fp
request description in
Selecting Fonts.
Occupied mounting positions are listed,
one per line,
in increasing order,
followed by the typeface name;
if the name corresponds to an abstract style,
the entry ends there.
Otherwise,
the name of the font description file
and the font’s “internal name” datum,
the meaning of which varies by output device,
follow.
Report,
to the standard error stream,
the list of font translations.
Recall the ftr request description in Selecting Fonts.
The “from” font identifier is listed first,
followed by its “to” translation.
Report,
to the standard error stream,
the list of hyphenation exception words
associated with the hyphenation language
selected by the
hla
request;
recall Manipulating Hyphenation.
A
‘-’
marks each hyphenation point.
A word prefixed with
‘-’
is not hyphenated at all.
The report suffixes words
to which automatic hyphenation applies
(meaning those defined in a hyphenation pattern file
rather than with the
hw
request)
with a tab and asterisk
(*).
Report, in JSON syntax to the standard error stream, the list of output nodes corresponding to the pending output line. In JSON, a pair of empty brackets ‘[ ]’ represents an empty list. A pending output line has not yet undergone adjustment, and lacks a line number and margin character (all as applicable).
Report, to the standard error stream, the JSON-encoded name and contents of each macro, string, or diversion name, or, without arguments, the names of all defined macros, strings, and diversions and their lengths in characters or nodes.
Report the name and value and, if its type is numeric, the autoincrement amount and assigned format of each register reg, or, without arguments, those of all defined registers, to the standard error stream.
Report, in JSON syntax to the standard error stream, the list of open streams, including the name of each open stream, the name of the file backing it, and its mode (writing or appending). In JSON, a pair of empty brackets ‘[ ]’ represents an empty list.
Report the names and positions of all page location traps to the
standard error stream. GNU troff reports empty slots in the
list, where a trap had been planted but subsequently (re)moved, because
they can affect the visibility of subsequently planted traps.
Break the line and flush any pending output line immediately.
The effect is the same as the
br
request unless the no-break control character is used;
‘'br’
does nothing,
whereas
‘'fl’
writes the pending output line
without further updating the drawing position.
However,
the reported horizontal drawing position is still
reckoned from the start of the input line.
foo \n(hp
bar \c
'fl
\n(hp baz \n(hp
⇒ foo 96 bar 0 baz 144
Flush timing is most easily perceived in device-independent output.
Use of
‘'fl’
may be desirable immediately prior to an
ab
request
when troubleshooting a document or macro definition line by line,
because a significant number of formatting operations
can accumulate on a partially collected output line,
misleading you about “where” the abort “really” took place.
Historically, fl was used with rd to produce interactive
nroff documents. GNU troff does not easily support
that mode of operation, because its output for terminals is first
prepared in device-independent format, which grotty renders a
page at a time.
Write the state 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.
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.
Set the scaling unit used in certain warnings (one of
‘u’,
‘i’,
‘c’,
‘p’,
and
‘P’;
default:
‘i’).
Ignored on
nroff-mode
output devices,
for which these diagnostics report the vertical page location in lines,
and the horizontal page location in ens.
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 unit 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
GNU
troff must add
0.2m
or more for each inter-word space in a line.
See Warnings.
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.
GNU
troff has command-line options for reporting warnings
(-w),
suppressing them
(-W),
and issuing backtraces
(-b)
when a warning or an error occurs.
| • Warnings |
Next: Implementation Differences, Previous: GNU troff Internals, Up: GNU troff Reference [Contents][Index]