Next: , Previous: , Up: GNU troff Reference   [Contents][Index]


5.37 Debugging

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. 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 characters, environments, hyphenation codes and exceptions, registers, open streams, page location traps, and a list of output nodes corresponding to the pending input line to the standard error stream.

Request: .lf line [name]

Set the input line number (and, optionally, the 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.

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 troff correspond to the source document.

Request: .tm message
Request: .tm1 ["]message
Request: .tmc ["]message

Send message, which consumes the remainder of the input line and cannot contain special characters, to the standard error stream, followed by a newline. Leading spaces in message are ignored.

tm1 is similar, but recognizes and strips a leading neutral double quote, allowing leading embedded spaces in message.

tmc works as tm1, but does not append a newline.

Request: .ab [message]

Write any message to the standard error stream (like tm) and then abort GNU troff; that is, stop processing and terminate with a failure status.

Request: .ex

Exit GNU troff; that is, stop processing and terminate successfully. To stop processing only the current file, use the nx request; see I/O.

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.

Request: .pcolor [col ]

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.

Request: .pcomposite

Report, to the standard error stream, the list of defined composite characters. The “from” code point is listed first, followed by its “to” mapping.

Request: .pev

Report the state of the current environment followed by that of all other environments to the standard error stream.

Request: .phcode c

Report, to the standard error stream, the hyphenation code of each ordinary or special character c. Special characters are listed in bracketed syntax using the default escape character.

Request: .phw

Report, to the standard error stream, the list of hyphenation exceptions associated with the current hyphenation language. Each hyphenation point is marked with ‘-’. Words that will not be hyphenated at all are prefixed with ‘-’. Those to which automatic hyphenation applies (meaning those defined in a hyphenation pattern file rather than with the hw request) are suffixed with a tab and asterisk (*).

Request: .pline

Report, to the standard error stream, the list of output nodes corresponding to the pending output line. The list is empty if there are none.

Request: .pm

Report, to the standard error stream, the names of all defined macros, strings, and diversions with their sizes in bytes.

Request: .pnr [reg ]

Report the name and value and, if the value is numeric, the assigned format of each register reg, or, without arguments, those of all defined registers, to the standard error stream.

Request: .pstream

Report, to the standard error stream, the name of each opened stream, the name of the file backing it, and its mode (writing or appending).

Request: .ptr

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.

Request: .fl

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 bar \n(hp
foo bar \c
'fl
\n(hp
    ⇒ foo bar 192 foo bar 0

The timing of a flush is most easily perceived in GNU troff’s device-independent output.

Historically, fl was used with rd to produce interactive nroff documents. GNU troff does not easily support this mode of operation, because its output for terminals is first prepared in device-independent format, which grotty renders a page at a time.

Request: .backtrace

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.

Register: \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.

Request: .warnscale su

Set the scaling unit used in certain warnings to su, which can take the values ‘u’, ‘i’, ‘c’, ‘p’, and ‘P’. The default is ‘i’. Ignored on nroff-mode output devices, for which these diagnostics report the vertical page location in lines.

Request: .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 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 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.

Request: .warn [n]
Register: \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.


Next: , Previous: , Up: GNU troff Reference   [Contents][Index]