— Request: .lf line [filename]

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 which 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.

— Request: .tm string

— Request: .tm1 string

— Request: .tmc string

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).

— Request: .ab [string]

Similar to the tm request, except that it causes gtroff to stop processing. With no argument it prints ‘User Abort.’ to standard error.

— Request: .ex

The ex request also causes gtroff to stop processing; see also I/O.

     
     .if \n(DB .tm debugging output

     
     groff -rDB=1 file

— Request: .pev

Print the contents of the current environment and all the currently defined environments (both named and numbered) on stderr.

— Request: .pm

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.

— Request: .pnr

Print the names and contents of all currently defined number registers on stderr.

— Request: .ptr

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.

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

— Request: .backtrace

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.

— Register: \n[slimit]

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.

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

— Request: .spreadwarn [limit]

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’).

— Request: .warn [flags]

— Register: \n[.warn]

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.