groff
Section: Environments, Tables, and Troff Macros (7)
Updated: 202-0-28
Index
Return to Main Contents
Name
groff - GNU
roff
language reference
.nr d-fallback 1
.nr d-fallback 1
Description
groff
is short for GNU
roff,
a free reimplementation of the AT&T devic-independent
troff typesetting system.
See
for a survey of and background on
roff
systems.
This document is intended as a reference.
The primary
groff
manual,
Groff: The GNU Implementation of troff,
by Trent A. Fisher and Werner Lemberg,
is a better resource for learners,
containing many examples and much discussion.
It is written in Texinfo;
you can browse it interactively with [lq]info groff[rq].
Additional formats,
including plain text,
HTML,
TeX DVI,
and PDF,
may be available in
/usr/:share/:doc/:groff-1.24.2.
We apply the term [lq]groff[rq] to the language documented here,
the GNU implementation of the overall system,
the project that develops that system,
and the command of that name.
In the first sense,
groff
is an extended dialect of the
roff
language,
for which many
similar implementations exist.
GNU
troff,
installed on this system as
is the
formatter:
a program that reads device and font descriptions
(
interprets the
groff
language expressed in input text,
and translates it into a devic-independent page description language
(
that is usually then pos-processed by an output driver to produce
PostScript,
PDF,
HTML,
DVI,
or terminal output.
We speak of [lq]the formatter[rq] when describing behavior
that is generally true of
troff and
nroff programs.
Input format
Organize input to
GNU
troff into lines separated by the Unix newline character
(U+000A),
using the character encoding it recognizes:
ISO~Lati-1 (885-1).
We recommend use of ISO~646:1991~IRV (U-ASCII)
or (equivalently) the Basic Latin subset
of ISO~10646 (Unicode);
see
Some control characters
(from the sets [lq]C0 Controls[rq] and [lq]C1 Controls[rq]
as Unicode describes them)
are invalid as input characters.
GNU
troff discards them upon reading.
(It also emits a warning in category
[lq]input[rq];
see section [lq]Warnings[rq] of
It processes
a character sequence [lq]foo[rq],
followed by an invalid
character and then [lq]bar[rq],
as [lq]foobar[rq].
Invalid input characters comprise
0x00,
0x0B,
0x0D[en]
0x1F,
and
0x80[en]
0x9F.
(Historically,
control characters like
ASCII
STX,
ETX,
and
BEL
(Control+B,
Control+C,
and
Control+G)
respectively)
have been observed in
roff
documents,
particularly in macro packages employing them as delimiters
with the output comparison operator
to try to avoid collisions with the content
of arbitrary use-supplied parameters
(see subsection [lq]Conditional expressions[rq] below).
We discourage this expedient;
in
GNU
troff it is unnecessary
(outside of compatibility mode)
because the program parses delimited arguments
at a different input level than their surrounding context.
See section [lq]Miscellaneous[rq] of
GNU
troff uses some of these code points for internal purposes,
making no-trivial the extension of the program
to accept UT-8
or other encodings that use characters from these ranges.
Syntax characters
Several input characters are syntactically significant to
groff.
The most important of these distinguish
control lines,
which instruct the formatter,
from
text lines
that are formatted as output.
- .
-
A dot at the beginning of an input line marks it as a control line.
It can also follow the
and
requests,
and the condition in
[lq]if[rq],
and
[lq]while[rq]
requests.
The control character invokes requests and calls macros by the name that
follows it.
The
request can change the control character.
- [aq]
-
The neutral apostrophe is the
n-break control character,
recognized where the control character is.
It suppresses the (first) break implied by the
[lq]in[rq],
and
requests.
The requested operation takes effect at the next break.
It makes
and
nilpotent.
The n-break control character can be changed with the
request.
When formatted,
[lq][aq][rq]
may be typeset as a typographical quotation mark;
use the
special character escape sequence to format a neutral apostrophe glyph.
- [dq]
-
The neutral double quote can be used to enclose arguments to macros and
strings,
and is required if those arguments contain space or tab characters.
The requests
[lq]as[rq],
[lq]open[rq],
[lq]so[rq],
and
strip a leading neutral double quote
from their final arguments
to allow embedding of leading spaces.
All such arguments are [lq]strings[rq] in a general sense,
representing character sequences,
file names,
operating system commands,
or parameters to an output device extension command.
To include a double quote inside a quoted argument,
use the
special character escape sequence
(which also serves to typeset the glyph in text).
- [rs]
-
A backslash introduces an escape sequence.
The escape character can be changed with the
request;
disables escape sequence recognition.
Use the
special character escape sequence to format a backslash glyph,
and
to typeset the glyph of the current escape character.
- (
-
An opening parenthesis is special only in certain escape sequences;
when recognized,
it introduces an argument of exactly two characters.
groff
offers the more flexible square bracket syntax.
- [
-
An opening bracket is special only in certain escape sequences;
when recognized,
it introduces an argument (list) of any length,
not including a closing bracket.
- ]
-
A closing bracket is special only when an escape sequence using an
opening bracket as an argument delimiter is being interpreted.
It ends the argument (list).
Additionally,
the Control+A character (U+0001) in text is interpreted as a
leader
(see below).
Horizontal whitespace characters are significant to
groff,
but trailing spaces on text lines are ignored.
- space
-
On control lines and within bracketed escape sequences,
spaces separate arguments.
On text lines,
they separate words.
Multiple adjacent space characters in text cause
groff
to attempt en-o-sentence detection on the preceding word
(and trailing punctuation).
The amount of space between words and sentences is controlled by the
request.
When filling is enabled
(the default),
a line may be broken at a space.
When adjustment is enabled
(the default),
inte-word spaces are expanded until the output line reaches the
configured length.
An adjustable but no-breaking space is available with
To get a space of fixed width,
use one of the escape sequences
(the escape character followed by a space),
or
see section [lq]Escape sequences[rq] below.
- newline
-
On text lines,
a newline formats an inte-word space and,
if filling is enabled,
triggers en-o-sentence recognition on the preceding text.
See section [lq]Line continuation[rq] below.
- tab
-
A tab character on a text line causes the drawing position to advance to
the next defined tab stop.
Sentences
Configure the sets of characters that potentially end sentences
or are transparent to sentence endings
with the
cflags
request.
Use the
ss
request
to change[em]or eliminate[em]supplemental inte-sentence space.
Tabs and leaders
The formatter interprets input horizontal tab characters
([lq]tabs[rq]) and Control+A characters ([lq]leaders[rq]) into
movements to the next tab stop.
Tabs simply move to the next tab stop;
leaders place enough periods to fill the space.
Tab stops are by default located every half inch measured from the
drawing position corresponding to the beginning of the input line;
see section [lq]Page geometry[rq] of
Tabs and leaders do not cause breaks and therefore do not interrupt
filling.
Tab stops can be configured with the
ta
request,
and tab and leader glyphs with the
tc
and
lc
requests,
respectively.
Line continuation
When filling is enabled,
input and output line breaks generally do not correspond.
The
roff
language therefore distinguishes input and output line continuation.
A backslash
[rs]
immediately followed by a newline,
sometimes discussed as
[rs]newline,
suppresses the effects of that newline
on the input.
The next input line thus retains the classification of its predecessor
as a control or text line.
[rs]newline
is useful for managing line lengths in the input during document
maintenance;
you can break an input line at a space,
or in the middle of a word,
request invocation,
macro call,
or escape sequence.
Input line continuation is invisible to the formatter,
with two exceptions:
the
[or]
operator recognizes the new input line,
and the input line counter register
.c
increments.
The
escape sequence continues an
output
line.
Nothing on the input line after it is formatted.
In contrast to
[rs]newline,
a line after
is treated as a new input line,
so a control character is recognized at its beginning.
The visual results depend on whether filling is enabled.
An intervening control line that causes a break overrides
flushing out the pending output line in the usual way.
The
interpolates a positive value only if the pending output line has been
continued with
this datum is associated with the
environment.
Colors
groff
supports color output with a variety of color spaces and up to 16 bits
per channel.
Some devices,
particularly terminals,
may be more limited.
When color support is enabled,
two colors are current at any given time:
the
stroke color,
with which glyphs,
rules (lines),
and geometric objects like circles and polygons are drawn,
and the
fill color,
which can be used to paint the interior of a closed geometric figure.
The
color,
defcolor,
gcolor,
and
fcolor
requests;
[rs]m
and
[rs]M
escape sequences;
and
.color,
.m,
and
.M
registers exercise color support.
Each output device has a color named
[lq]
default[rq],
which cannot be redefined.
A device's default stroke and fill colors are not necessarily the same.
For the
dvi,
html,
pdf,
ps,
and
xhtml
output devices,
troff
automatically loads a macro file defining many color names at startup.
By the same mechanism,
the devices supported by
recognize the eight standard ISO~6429/ECM-48 color names.
(These are known vulgarly as [lq]ANSI[rq] colors,
after its X3.64 standard,
now withdrawn.)
Measurements
Express numeric parameters that specify measurements
as integers
or decimal fractions
with an optional scaling unit suffixed.
A
scaling unit
is a letter
that immediately follows the magnitude of a measurement.
Digits after the decimal point are optional.
The formatter scales measurements by the specified scaling unit,
storing them internally
(with any fractional part discarded)
in basic units.
The device resolution can therefore be obtained
by storing a value of
[lq]
1i[rq]
to a register,
then reading the register.
- u
-
Basic unit;
it is at least as small as any other unit.
- i
-
Inch;
defined as 2.54~centimeters.
- c
-
Centimeter.
- p
-
Point;
a typesetter's unit used for measuring type size.
There are 72~points to an inch.
- P
-
Pica;
another typesetter's unit.
There are 6~picas to an inch and 12~points to a pica.
- z
-
Typographical point;
like
p,
but used only with type sizes,
to overcome a limitation of AT&T
troff.
- s
-
Scaled point.
- f
-
Multiplication by 65,536;
scales decimal fractions in the interval [0, 1] to 1-bit unsigned
integers.
The magnitudes of other scaling units depend on the text formatting
parameters in effect.
- m
-
Em;
an em is equal to the current type size in points.
- n
-
En;
on typesetters,
an en is on-half em,
but on terminals an en equals an em.
- v
-
Vee;
distance between text baselines.
- M
-
Hundredth of an em.
Motion quanta
The basic unit
u
is not necessarily an output device's smallest addressable length;
u
can be smaller to avoid integer rounding errors.
The minimum distances that a device can work with
in the horizontal and vertical directions are termed its
motion quanta,
stored in the
.H
and
.V
registers,
respectively.
The formatter rounds measurements to applicable motion quanta.
Hal-quantum fractions round toward zero.
Default units
A genera-purpose register
(one created or updated with the
nr
request;
see section [lq]Registers[rq] below)
is implicitly dimensionless,
or reckoned in basic units if interpreted in a measurement context.
But it is convenient for many requests and escape sequences to infer a
scaling unit for an argument if none is specified.
An explicit scaling unit
(not after a closing parenthesis)
can override an undesirable default.
Effectively,
the default unit is suffixed to the expression if a scaling unit is not
already present.
GNU
troff's
use of integer arithmetic in numeric expressions
should also be kept in mind.
Numeric expressions
When evaluated,
a
numeric expression
interpolates an integer.
GNU
troff recognizes the following operators.
| + | addition |
|
| - | subtraction |
|
| * | multiplication |
|
| / | truncating division |
|
| % | modulus |
|
|
| R]unary] + | assertion, motion, incrementation |
|
| R]unary]- | negation, motion, decrementation |
|
|
| ; | scaling |
|
| >? | maximum |
|
| <? | minimum |
|
|
| < | less than |
|
| > | greater than |
|
| <= | less than or equal |
|
| >= | greater than or equal |
|
| = | equal |
|
| == | equal |
|
|
| & | logical conjunction ([lq]and[rq]) |
|
| : | logical disjunction ([lq]or[rq]) |
|
| ! | logical complementation ([lq]not[rq]) |
|
|
| ( ) | precedence |
|
|
| | | boundar-relative measurement |
|
troff
provides a set of mathematical and logical operators familiar to
programmers[em]as well as some unusual ones[em]but supports only
integer arithmetic.
(Provision is made for interpreting and
reporting decimal fractions in certain cases.)
The internal data type used for computing results depends on the host
machine but is at least a 3-bit signed integer,
which suffices to represent magnitudes within a range of [-]2
billion.
(If that's not enough, see
for the
62bit.tmac
macro package.)
Arithmetic saturates.
(If overflow would occur,
GNU
troff emits a warning in category
[lq]
range[rq].
See section [lq]Warnings[rq] of
Arithmetic infix operators perform a function on the numeric expressions
to their left and right;
they are
+
(addition),
-
(subtraction),
*
(multiplication),
/
(truncating division),
and
%
(modulus).
Truncating division
rounds to the integer nearer to zero,
no matter how large the fractional portion.
Division and modulus by zero
are errors and abort evaluation of a numeric expression.
Arithmetic unary operators operate on the numeric expression to their
right;
they are
-
(negation)
and
+
(assertion[em]for completeness;
it does nothing).
The unary minus must often be used with parentheses to avoid confusion
with the decrementation operator,
discussed below.
The sign of the modulus of operands of mixed signs is determined by the
sign of the first.
Division and modulus operators satisfy the following property:
given a
dividend~
a
and a
divisor~
b,
a
quotient~
q
formed by
[lq]
(a / b)[rq]
and a
remainder~
r
by
[lq]
(a % b)[rq],
then
qb~+~
r~=~
a.
GNU
troff's
scaling operator,
used with parentheses as
(c;e),
evaluates a numeric
expression~
e
using~
c
as the default scaling unit.
If
c
is omitted,
scaling units are ignored in the evaluation
of~
e.
GNU
troff also provides a pair of operators to compute the extremum of two
operands:
>?
(maximum)
and
<?
(minimum).
Comparison operators comprise
<
(less than),
>
(greater than),
<=
(less than or equal),
>=
(greater than or equal),
and
=
(equal,
with a synonym
==).
When evaluating a comparison,
the formatter replaces it with
[lq]
0[rq]
if it is false and
[lq]
1[rq]
if true.
In the
roff
language,
positive values are true,
others false.
Operate on truth values with the logical operators
&
(logical conjunction or [lq]and[rq])
and
:
(logical disjunction or [lq]or[rq]).
They evaluate as comparison operators do.
A logical complementation ([lq]not[rq]) operator,
!,
works only within
[lq]
if[rq],
[lq]
ie[rq],
and
[lq]
while[rq]
requests.
Furthermore,
the formatter recognizes
!
only at the beginning of a numeric expression
not contained by another numeric expression.
In other words,
!
must be the [lq]outermost[rq] operator.
Its presence elsewhere causes the expression
to evaluate false.
(GNU
troff emits a warning in category
[lq]
number[rq].
See section [lq]Warnings[rq] of
This unfortunate limitation maintains compatibility with AT&T
troff.
Test a numeric expression for falsity
within a complex expression
by comparing it to a false value.
The
roff
language has no operator precedence:
expressions are evaluated strictly from left to right,
in contrast to schoolhouse arithmetic.
Use parentheses
( )
to impose a desired precedence upon subexpressions.
For many requests and escape sequences that cause motion on the page,
the unary operators
+
and
-
work differently when leading a numeric expression.
They then indicate a motion relative to the drawing position:
positive is down in vertical contexts,
right in horizontal ones.
+
and
-
are also treated differently by the following requests and escape
sequences:
bp,
in,
ll,
pl,
pn,
po,
ps,
pvs,
rt,
ti,
[rs]H,
[rs]R,
and
[rs]s.
Here,
leading plus and minus signs serve as incrementation and decrementation
operators,
respectively.
To negate an expression in these contexts,
subtract it from zero
or include the unary minus in parentheses with its argument.
A leading
[or]
operator indicates a motion relative not to the drawing position but to
a boundary.
For horizontal motions,
the measurement specifies a distance relative to a drawing position
corresponding to the beginning of the
input
line.
By default,
tab stops reckon movements in this way.
Most escape sequences do not;
[or]
tells them to do so.
For vertical motions,
the
[or]
operator specifies a distance from the first text baseline on the page
or in the current diversion,
using the current vertical spacing.
The delimited escape sequence
[rs]B
tests its argument for validity as a numeric expression.
A register interpolated as an operand in a numeric expression must have
an Arabic format;
luckily,
this is the default.
Because spaces separate arguments to requests,
spaces are not allowed in numeric expressions
unless parentheses surround the (sub)expression containing them.
Identifiers
An
identifier
labels a GNU
troff datum such as a register,
name
(macro,
string,
or diversion),
typeface,
color,
special character or character class,
hyphenation language code,
environment,
or stream.
Valid identifiers consist of one or more ordinary characters.
An
ordinary character
is any Unicode Basic Latin character
that is not a space and not the escape character;
recall section [lq]Input format[rq] above.
An identifier with a closing bracket ([lq]][rq]) in its name can't be
accessed with bracke-form escape sequences that expect an identifier as
a parameter.
Similarly,
the
identifier [lq]([rq] can't be interpolated
except
with bracket forms.
Beginning a macro,
string,
or diversion name with the character
[lq][[rq]
or
[lq]][rq]
forecloses use of the
preprocessor,
which recognizes input lines starting with
[lq].[[rq]
and
[lq].][rq]
as bibliographic reference delimiters.
The delimited escape sequence
[rs]A
tests its argument for validity as an identifier.
The formatter's handling of undefined identifiers is contex-dependent.
There is no way to invoke an undefined request;
such syntax is interpreted as a macro call instead.
If the identifier is interpreted as a string,
macro,
or diversion name,
the formatter defines it as empty and interpolates nothing.
(GNU
troff emits a warning in category
[lq]
mac[rq].
See section [lq]Warnings[rq] of
Similarly,
if the identifier is interpreted as a register name,
the formatter initializes it to zero
and interpolates that value.
GNU
troff emits a warning in category
[lq]
reg[rq];
see section [lq]Warnings[rq] in
and subsection [lq]Interpolating registers[rq] and section
[lq]Strings[rq] below.
Attempting to use an undefined
typeface,
special character or character class,
color,
environment,
hyphenation language code,
or
stream
generally provokes an error diagnostic.
Identifiers for requests,
macros,
strings,
and diversions share one name
space;
special characters and character classes another.
No other object types do.
Control characters
The formatter recognizes a control character
only at the beginning of an input line,
or at the beginning of a branch of a control structure request;
see section [lq]Control structures[rq] below.
A few requests cause a break implicitly;
invoke them with the n-break control character
to prevent the break.
Break suppression is its sole behavioral distinction.
Employing the n-break control character
to invoke requests that don't cause breaks
is harmless but poor style.
The control character
[lq]
.[rq]
and the n-break control character
[lq]
[aq][rq]
can be changed with the
cc
and
c2
requests,
respectively.
Within a macro definition,
register
.br
indicates the control character used to call it.
Invoking requests
A control character is optionally followed by tabs and/or spaces and
then an identifier naming a request or macro.
The invocation of an unrecognized request is interpreted as a macro
call.
Defining a macro with the same name as a request replaces the request.
Deleting a request name with the
rm
request makes it unavailable.
The
als
request can alias requests,
permitting them to be wrapped or no-destructively replaced.
See section [lq]Strings[rq] below.
There is no inherent limit on argument length or quantity.
Most requests take one or more arguments,
and ignore any they do not expect.
A request may be separated from its arguments by tabs or spaces,
but only spaces can separate an argument from its successor.
Only one between arguments is necessary;
any excess is ignored.
GNU
troff does not allow tabs for argument separation.
(Plan~9
troff does.)
Generally,
a space
within
a request argument is not relevant,
not meaningful,
or is supported by bespoke provisions,
as with the
tl
request's delimiters.
Some requests,
like
ds,
interpret the remainder of the control line as a single argument.
See section [lq]Strings[rq] below.
Spaces and tabs immediately after a control character are ignored.
Commonly,
authors use them to indent the source of documents or macro files.
Calling macros
If a macro of the desired name does not exist when called,
the formatter creates it
and assigns it an empty definition.
(GNU
troff emits a warning in category
[lq]
mac[rq].
See section [lq]Warnings[rq] in
Calling an undefined macro
does
end a macro definition naming it as its end macro
(see section [lq]Writing macros[rq] below).
To embed spaces
within
a macro argument,
enclose the argument in neutral double quotes
[oq]
[dq][cq].
Horizontal motion escape sequences are sometimes a better choice for
arguments to be formatted as text.
The foregoing raises the question of how to embed neutral double quotes
or backslashes in macro arguments when
those
characters are desired as literals.
In GNU
troff,
the special character escape sequence
[rs][rs]
produces a backslash and
[rs][dq]
a neutral double quote.
In GNU
troff's
AT&T compatibility mode,
these characters remain available as
[rs](rs
and
[rs](dq,
respectively.
AT&T
troff did not consistently define these special characters,
but its descendants can be made to support them.
See
If even that is not feasible,
see the [lq]Calling Macros[rq] section of the
groff
Texinfo manual for the complex macro argument quoting rules of AT&T
troff.
Using escape sequences
Whereas requests must occur on control lines,
escape sequences can occur intermixed with text and may appear in
arguments to requests,
macros,
and other escape sequences.
An escape sequence is introduced by the escape character,
a backslash
[rs].
The next character selects the escape's function.
Escape sequences vary in length.
Some take an argument,
and of those,
some have different syntactical forms for a on-character,
tw-character,
or arbitrar-length argument.
Others accept
only
an arbitrar-length argument.
In the former scheme,
a on-character argument follows the function character immediately,
an opening parenthesis
[lq]
([rq]
introduces a tw-character argument
(no closing parenthesis is used),
and an argument of arbitrary length is enclosed in brackets
[lq]
[][rq].
In the latter scheme,
the user selects a delimiter character.
A few escape sequences are idiosyncratic,
and support both of the foregoing conventions
(
[rs]s),
designate their own termination sequence
(
[rs]?),
consume input until the next newline
(
[rs]!,
[rs] ,
[rs]#),
or support an additional modifier character
(
[rs]s
again,
and
[rs]n).
In no case can an escape sequence parameter contain an unescaped
newline.
If the character that follows the escape character
does not identify a defined operation,
the formatter ignores the escape character.
(GNU
troff emits a warning in category
[lq]
escape[rq].
See section [lq]Warnings[rq] in
Escape sequence interpolation is of higher precedence than escape
sequence argument interpretation.
This rule affords flexibility in using escape sequences to construct
parameters to other escape sequences.
The escape character can be interpolated
(
[rs]e).
Requests permit the escape mechanism to be deactivated
(
eo)
and restored,
or the escape character changed
(
ec),
and to save and restore it
(
ecs
and
ecr).
Delimiters
Some escape sequences that require parameters use delimiters.
The neutral apostrophe
[aq]
is a popular choice and shown in this document.
The neutral double quote
[dq]
is also commonly seen.
Punctuation characters are the best choice
(and most portable to other
troffs,
except for those meaningful in numeric expressions;
see below.
The following escape sequences are not themselves delimited,
and thus are allowed as delimiters:
[rs]space,
[rs]%,
[rs]|,
[rs][ha],
[rs]{,
[rs]},
[rs][aq],
[rs][ga],
[rs]-,
[rs]_,
[rs]!,
[rs]?,
[rs]),
[rs]/,
[rs],,
[rs]&,
[rs]:,
[rs][ti],
[rs]0,
[rs]a,
[rs]c,
[rs]d,
[rs]e,
[rs]E,
[rs]p,
[rs]r,
[rs]t,
and
[rs]u.
However,
we discourage using them this way;
they can make the input confusing to read.
(The
and
preprocessors use parameterized but no-delimited special character
escape sequences
[rs](
and
[rs][
to bracket portions of their output.)
An invalid escape sequence is valid as a delimiter
if the character after the escape character would be valid.
The escape sequences
[rs]D,
[rs]h,
[rs]H,
[rs]l,
[rs]L,
[rs]N,
[rs]R,
[rs]s,
[rs]S,
[rs]v,
and
[rs]x
prohibit delimiters that are meaningful in numeric expressions,
because they accept numeric expressions as
(or within)
their arguments.
For consistency,
GNU
troff prohibits the same delimiters in the argument to the
tl
request.
The
[lq]
if[rq],
ie,
and
[lq]
while[rq]
requests each interpret their first argument
as a conditional expression;
only characters that are not meaningful as operators
in that context
can be used as output comparison delimiters.
The following inputs are therefore invalid as delimiters in
GNU
troff.
-
- [bu]
-
the numerals 0[en]9 and the decimal point
[lq].[rq]
- [bu]
-
the (singl-character) operators
+-/*%<>=&:()|
- [bu]
-
any escape sequences other than
[rs]%,
[rs]:,
[rs]{,
[rs]},
[rs][aq],
[rs][ga],
[rs]-,
[rs]_,
[rs]!,
[rs]/,
[rs]c,
[rs]e,
and
[rs]p
Delimiter syntax is flexible
(and laborious to describe)
primarily for historical reasons;
the foregoing restrictions need be kept in mind mainly when using
GNU
troff in AT&T compatibility mode.
Normally,
GNU
troff keeps track of the nesting depth of escape sequence interpolations,
so the only characters you need to avoid using as delimiters are those
that appear in the arguments you input,
not those that result from interpolation.
Typically,
[aq]
works fine.
See section [lq]Implementation differences[rq] in
Dummy characters
As discussed in
the first character on an input line is treated specially.
Further,
formatting a glyph has many
consequences on formatter state
(see section [lq]Environments[rq] below).
Occasionally,
we want to escape this context or embrace some of those consequences
without actually rendering a glyph to the output.
[rs]&
interpolates a dummy character,
which is constitutive of output but invisible.
Its presence alters the interpretation context of a subsequent input
character,
and enjoys several applications:
preventing the insertion of extra space after an en-o-sentence
character,
preventing interpretation of a control character at the beginning of an
input line,
preventing kerning between two glyphs,
and permitting the
tr
request to remap a character to [lq]nothing[rq].
[rs])
works as
[rs]&
does,
except that it does not cancel a pending en-o-sentence state.
Page control
Discretionary page breaks
can prevent the unwanted separation of content.
A new page number takes effect during page ejection;
see subsection [lq]The implicit page trap[rq] below.
The
bp
request breaks the page,
incrementing the page number by one
(or setting it per the supplied argument).
The
ne
request forces a page break if insufficient vertical space is available
(it asserts [lq]needed[rq] space).
sv
requires vertical space as
ne
does,
but also
saves
it for later output by the
os
request.
The
nl
register interpolates the vertical drawing position
as of the most recently typeset output line.
It does not necessarily
(and often does not)
represent that of the pending output line,
because the formatter does not determine the position of its baseline
until it is output.
Assigning a value to
nl
sets the vertical drawing position
in advance of further modifications to baseline positioning
arising from alterations to type size,
changes to vertical spacing,
or application of extra pr- or pos-vertical spacing.
When the formatter starts,
the transition to the first page
has not yet happened[em]
nl
is negative.
If you plant a page location trap at vertical position
[lq]
0[rq]
(idiomatically to format a header),
you can assign a negative value to
nl
to spring that trap even if the page has already started
(see subsection [lq]Page location traps[rq] below).
Control structures
groff
has [lq]if[rq] and [lq]while[rq] control structures like other
languages.
However,
the syntax for grouping multiple input lines in the branches or bodies
of these structures is unusual.
They have a common form:
the request name is
(except for
[lq]else[rq])
followed by a conditional expression
con-expr;
the remainder of the line,
input,
is interpreted as if it were an input line.
Any quantity of spaces between arguments to requests serves only to
separate them;
leading spaces in
input
are therefore not seen.
input
effectively
cannot
be omitted;
if
con-expr
is true and
input
is empty,
the newline at the end of the control line is interpreted as a blank
line
(and therefore a blank text line).
It is frequently desirable for a control structure to govern more than
one request,
macro call,
or text line,
or combination of the foregoing.
The opening and closing brace escape sequences
and
perform such grouping.
Brace escape sequences outside of control structures have no meaning and
produce no output.
should appear
(after optional spaces and tabs)
immediately subsequent to the request's conditional expression.
should appear on a line with other occurrences of itself as necessary to
match
sequences.
It can be preceded by a control character,
spaces,
and tabs.
Input after any quantity of
sequences on the same line is processed only if all the preceding
conditions to which they correspond are true.
Furthermore,
a
closing the body of a
[lq]
while[rq]
request must be the last such escape sequence on an input line.
GNU
troff treats the body of a
[lq]
while[rq]
request similarly to that of a
de
request
(albeit one not read in copy mode),
but stores it under an internal name
and deletes it when the loop finishes.
The operation of a macro containing a
[lq]
while[rq]
request can slow significantly if its
body is large.
Each time
GNU
troff interpolates the macro,
it parses and stores the
[lq]
while[rq]
body again.
An often better solution[em]and one that is more portable,
since AT&T
troff lacked the
[lq]
while[rq]
request[em]is to instead write a recursive macro,
which is parsed only once
(unless you redefine it).
To prevent infinite loops,
GNU
troff limits the default number of available recursion levels
to 1,000 or somewhat less
(because things other than macro calls can be on the input stack).
You can disable this protective measure,
or alter the limit,
by setting the
slimit
register.
See section [lq]Debugging[rq] below.
Conditional expressions
The
[lq]
if[rq],
ie,
and
[lq]
while[rq]
requests test the truth values of numeric expressions.
They also support several additional Boolean operators;
the members of this expanded class are termed
conditional expressions;
their truth values are as shown below.
| con-exprB]... | ...is true if...
|
|
|
[aq]s1[aq]s2[aq]
|
s1
produces the same formatted output as
s2.
|
|
c~g
|
a character
g
is defined.
|
|
d~m
|
a string,
macro,
diversion,
or request
m
is defined.
|
| e |
the current page number is even.
|
|
F~f
|
a font named
f
is available.
|
|
m~c
|
a color named
c
is defined.
|
| n |
the formatter is in
nroff
mode.
|
| o |
the current page number is odd.
|
|
r~n
|
a register named
n
is defined.
|
|
S~s
|
a font style named
s
is available.
|
| t |
the formatter is in
troff
mode.
|
| v |
n/a
(historical artifact;
always false).
|
If the first argument to an
[lq]
if[rq],
ie,
or
[lq]
while[rq]
request begins with a no-alphanumeric character apart from
[lq]
![rq]
(see below)
and is not a numeric expression,
the formatter performs an
output comparison test.
Shown first in the table above,
the
output comparison operator
interpolates a true value if formatting its comparands
s1
and
s2
produces the same output commands.
Other delimiters can be used in place of the neutral apostrophes;
see section [lq]Delimiters[rq] above.
troff formats
s1
and
s2
in separate scratch buffers;
after comparison,
it discards the resulting data.
The resulting glyph properties,
including font family,
style,
size,
and
slant,
must match,
but not necessarily the requests and/or escape sequences
used to obtain them.
Motions must match in orientation and magnitude to within the applicable
horizontal or vertical motion quantum of the device,
after rounding.
Surround the comparands with
[rs]?
to avoid formatting them;
this causes them to be compared character by character,
as with string comparisons in other programming languages.
Since
GNU
troff reads comparands protected with
[rs]?
in copy mode,
they need not be syntactically valid.
The escape character is still lexically recognized,
however,
and consumes the next character.
The above operators can't be combined with most others,
but a leading
[lq]
![rq],
not followed immediately by spaces or tabs,
complements an expression.
Spaces and tabs are optional immediately after the
[lq]
c[rq],
[lq]
d[rq],
[lq]
F[rq],
[lq]
m[rq],
[lq]
r[rq],
and
[lq]
S[rq]
operators,
but right after
[lq]
![rq],
they end the predicate and the conditional evaluates true.
(This bizarre behavior maintains compatibility with AT&T
troff.)
Conditional operators do not create
roff
language objects as interpolations with
[rs]n
and
[rs]*
escape sequences do.
Syntax reference conventions
In the following request and escape sequence specifications,
most argument names were chosen to be descriptive.
GNU
troff reads arguments named
characte-sequence,
command,
contents,
file,
and
message
in copy mode
(see section [lq]Copy Mode[rq] below)
until the end of the input line.
A
characte-sequence
comprises one or more ordinary,
special,
or indexed characters;
spaces;
or escape sequences that interpolate only these.
We name the remaining arguments for clarity;
they are also
characte-sequences.
A neutral double quote
[oq]
[dq][cq]
can optionally prefix a
characte-sequence;
the formatter discards one if present,
permitting initial embedded spaces in the argument.
input
refers to arbitrary character sequences
(up to a newline or delimiter)
that
GNU
troff fully interprets,
in contrast to copy mode.
A few denotations are more specific.
-
- b
-
is a numerical expression evaluated as a Boolean;
positive values are true,
others false.
- c
-
denotes a single character[em]ordinary,
special,
or indexed.
- command
-
is an instance of
contents
(see below)
to be passed to the system as a command
(potentially with arguments).
GNU
troff strips a leading neutral double quote,
allowing embedded leading spaces.
- contents
-
is arbitrary input,
excluding an unescaped newline,
read in copy mode.
GNU
troff strips a leading neutral double quote,
allowing embedded leading spaces.
- div
-
is a diversion identifier.
- env
-
is an environment identifier.
- file
-
is an instance of
contents
naming a file on the system.
GNU
troff strips a leading neutral double quote,
allowing embedded leading spaces.
GNU
troff does not accept newlines
(line feeds)
in file names supplied as arguments to requests.
- font
-
is a typeface specified as a font identifier,
an abstract style,
or a mounting position.
- ident
-
is a valid
groff
identifier;
its use often indicates that the operation creates an object of a type
subsequently referred to as
mac,
reg,
str,
and so forth.
- mac
-
is a macro identifier.
- message
-
is an instance of
contents
to emit on the standard error stream.
GNU
troff strips a leading neutral double quote,
allowing embedded leading spaces.
- n
-
is a numeric expression that evaluates to a no-negative integer.
- [-]N
-
is a numeric expression with a meaning dependent on its sign;
see below.
- name
-
is a macro,
string,
or diversion identifier,
or the name of a request.
- npl
-
is a numeric expression constituting a count of subsequent
productive
input lines;
that is,
those that directly produce formatted output.
Text lines produce output,
as do control lines containing requests like
[lq].tl //Page %//[rq]
or escape sequences like
[lq][rs]l[aq]1i[aq][rq].
Macro calls are not themselves productive,
but their interpolations can be.
- reg
-
is a register identifier.
- str
-
is a string identifier.
- stream
-
is an output stream identifier.
If a numeric expression presented as
[-]N
starts with a
sign,
an increment in the amount of
of~
N
is applied to the value applicable to the request or escape sequence.
If it starts with a
sign,
a decrement of magnitude
N
is applied instead.
Without a sign,
N
replaces any existing value.
A
roff
formatter always interprets a leading minus sign
in~
N
as a decrementation operator,
not an algebraic sign.
To assign a register a negative value
or the negated value of another interpolation,
you must force the formatter to interpret
[lq]
-[rq]
as a negation or minus,
rather than decrementation,
operator:
enclose the
[lq]
-[rq]
with its operand in parentheses
or subtract the expression of interest from zero.
If a prior value does not exist[em]the register was undefined[em]an increment or decrement applies as if to~0.
Request short reference
Not all details of request behavior are outlined here.
See the
groff
Texinfo manual or,
for features new to GNU
troff,
-
-
Abort the formatter;
exit with failure status.
-
-
Abort the formatter;
write
termina-message
to the standard error stream and exit with failure status.
-
-
Enable output line alignment and adjustment using the mode stored in
[rs]n[.j].
-
-
Enable output line alignment and adjustment in mode
c
(c=b,c,l,n,r).
Sets
[rs]n[.j].
-
-
Assign format
c
to register
reg,
where
c
is
[lq]i[rq],
[lq]I[rq],
[lq]a[rq],
[lq]A[rq],
or a sequence of decimal digits whose quantity denotes the minimum width
in digits to be used when the register is interpolated.
[lq]i[rq]
and
[lq]a[rq]
indicate Roman numerals and basic Latin alphabetics,
respectively,
in the lettercase specified.
The default is
0.
-
-
Create alias
(additional name)
ne-register
of
existin-register,
causing the names to refer to the same stored object.
If
existin-register
is undefined,
the formatter ignores the request.
GNU
troff emits a warning in category
[lq]reg[rq].
-
-
Create alias
(additional name)
ne-name
of request,
string,
macro,
or diversion
existin-name,
causing the names to refer to the same stored object.
If
existin-name
is undefined,
the formatter ignores the request.
GNU
troff emits a warning in category
[lq]mac[rq].
If
ne-name
already exists,
its definition is lost unless already aliased.
-
-
Append to macro
mac
until encountering
[lq]..[rq]
at the start of a control line in the current conditional block.
-
-
Append to macro
mac
until
en-mac
is called at the start of a control line in the current conditional
block.
en-mac
can be a request.
-
-
As
[rq]am[rq],
with compatibility mode disabled when the appendment to macro
mac
is interpreted.
-
-
As
[lq].am
mac[rq],
with compatibility mode disabled when the appendment to macro
mac
is interpreted.
-
-
Append to a macro indirectly[em]its name is in string
str[em]until
encountering
[lq]..[rq].
-
-
Append to a macro indirectly.
As
[rq]am[rq],
but
str
and
en-ma-str
contain the names of the macro to be appended to,
and that whose call ends the appendment,
respectively.
-
-
As
with compatibility mode disabled when the appendment is interpreted.
-
-
As
with compatibility mode disabled when the appendment is interpreted.
-
-
Create string
ident
with empty contents;
no operation if
ident
already exists.
-
-
Append
contents
to string
str.
-
-
As
[lq].as
ident[rq].
-
-
As
[rq]as[rq],
with compatibility mode disabled when the appendment to string
str
is interpreted.
-
-
Unformat ordinary characters,
spaces,
and some escape sequences in diversion
div.
When transforming a glyph node back into an input sequence
that demands expression as a special character escape sequence,
GNU
troff
uses the default escape character.
-
-
Write the state of the input stack to the standard error stream.
See the
-b
option of
-
-
Stop emboldening font
font.
-
-
Embolden
font
by overstriking its glyphs offset by
n-1
units.
See
-
-
Stop emboldening
specia-font
when
font
is selected.
specia-font
must be a font name,
not a mounting position.
-
-
Embolden
specia-font,
overstriking its glyphs offset by
n-1
units when
font
is selected.
See
-
-
Unset blank line macro (trap).
Restore default handling of blank lines.
-
-
Set blank line macro (trap) to
mac.
-
-
Stop directing output to current diversion;
any pending output line is discarded.
-
-
Direct output to diversion
ident,
omitting a partially collected line.
-
-
Stop appending output to current diversion;
any pending output line is discarded.
-
-
Append output to diversion
div,
omitting a partially collected line.
-
-
Break page and start a new one.
-
-
Break page,
starting a new one numbered
[-]N.
-
-
Break output line.
-
-
Break and force adjustment of the output line
per the current adjustment mode.
-
-
Break out of a
[rq]while[rq]
loop.
-
-
Reset n-break control character to
-
-
Recognize ordinary character
o
as n-break control character.
-
-
Reset control character to
-
-
Recognize ordinary character
o
as the control character.
-
-
Break,
center the output of the next productive input line without filling,
and break again.
-
-
Break,
center the output of the next
npl
productive input lines without filling,
then break again.
If
npl
[<=] 0,
stop centering.
-
-
Break and copy contents of
file
as [lq]throughput[rq] to GNU
troff output
(see
Each line of
file
is output
as if preceded by
[rs]!,
but is not interpreted by the formatter.
Unsafe request;
disabled by default.
-
-
Assign properties encoded by no-negative integer
n
to each character or class
c.
Spaces need not separate
c
arguments.
-
-
Unplant page location trap
mac.
-
-
Change page location trap
mac
planted by
by moving its location to
vertica-position
(default scaling unit~
-
-
Define an
ordinary,
special,
or
indexed
character
c
as empty.
-
-
Define an
ordinary,
special,
or
indexed
character
c
as
contents.
-
-
Remove the last character from the macro,
string,
or diversion
name.
-
-
Define a (character) class
ident
comprising the characters or range expressions
c,
where each
c
is an
ordinary,
special,
or
indexed
character;
or a
range expression.
A class thus defined can then be referred to
in a
cflags
request in lieu of listing all the characters within it.
-
-
Close
stream,
making it unavailable for
[rq]write[rq]
requests.
-
-
Enable output of colo-related devic-independent output commands.
It is enabled by default.
-
-
Enable or disable output of colo-related devic-independent output
commands per Boolean expression
b.
-
-
Remove composite character mapping for character
c.
-
-
Map character
c1
to
c2
when
c1
is a combining component in a composite character.
-
-
Skip the remainder of a
[lq]while[rq]
loop's body,
immediately retesting its conditional expression.
-
-
Enable AT&T
troff compatibility mode.
It is disabled by default.
-
-
Enable or disable AT&T
troff compatibility mode per Boolean expression
b.
-
-
Disable constan-width glyph spacing mode for font
f.
-
-
Enable constan-width glyph spacing mode for font
f
at
n/36
ems.
-
-
Enable constan-width glyph spacing mode for
font
at
n/36
ems,
as if one em equals
p
scaled points.
-
-
Continuously underline the output of the next productive input line.
-
-
Continuously underline the output of the next
npl
productive input lines.
If
npl=0,
stop continuously underlining.
-
-
Stop appending output to current diversion.
-
-
Append output to diversion
div.
-
-
Define macro
ident
until
[lq]..[rq]
occurs at the start of a control line in the current conditional block.
-
-
Define macro
ident
until
en-mac
is called at the start of a control line in the current conditional
block.
en-mac
can be a request.
-
-
As
with compatibility mode disabled when
mac
is interpreted.
-
-
As
[lq].de
ident en-mac[rq],
with compatibility mode disabled when
mac
is interpreted.
-
-
Define a color named
ident.
scheme
identifies a color space and determines the number of required
colo-components;
it must be one of
[lq]rgb[rq]
(three components),
[lq]cmy[rq]
(three),
[lq]cmyk[rq]
(four),
or
[lq]gray[rq]
(one).
[lq]grey[rq]
is accepted as a synonym of
[lq]gray[rq].
The color components can be encoded as a single hexadecimal value
starting with
#
or
##.
The former indicates that each component is in the range 0[en]255
(0[en]FF),
the latter the range 0[en]65,535 (0[en]FFFF).
Alternatively,
each color component can be specified as a decimal fraction in the range
0[en]1,
interpreted using a default scaling unit
of~[lq]f[rq],
which multiplies its value by 65,536
(but clamps it at 65,535).
-
-
Define macro indirectly.
As
but interpolate string
str
to obtain the macro's name.
-
-
Define macro indirectly.
As
but
str
and
en-ma-str
contain the names of the macro to be defined,
and that whose call ends the definition,
respectively.
-
-
As
with compatibility mode disabled when the macro is interpreted.
-
-
As
with compatibility mode disabled when the macro is interpreted.
-
-
Embed
characte-sequence
into
GNU
troff output as parameters to an
[lq]xX[rq]
device extension command;
see
The output driver or other postprocessor interprets
characte-sequence
as it sees fit.
-
-
Write contents of macro or string
name
to
troff
output as the argument to a device extension command.
-
-
Stop directing output to current diversion.
-
-
Direct output to diversion
ident.
-
-
Interpret the string,
request,
diversion,
or macro
name
(along with any further arguments)
with compatibility mode disabled.
Compatibility mode is restored
(only if it was active)
when the interpolation of
name
is interpreted.
-
-
Create empty string named
ident.
-
-
Create a string named
ident
containing
contents.
-
-
As
with compatibility mode disabled when the string is interpreted.
-
-
Clear diversion trap.
-
-
Set the diversion trap to macro
mac
at
vertica-position
(default scaling unit~
-
-
Recognize
[rs]
as the escape character.
-
-
Recognize ordinary character
o
as the escape character.
-
-
Restore escape character saved with
-
-
Save the escape character.
-
-
Interpolate a newline if the conditional expression of the corresponding
request was false.
-
-
Interpret
input
as if it were an input line if the conditional expression of the
corresponding
request was false.
-
-
Unset en-o-input macro.
-
-
Call macro
mac
after the end of input.
-
-
Disable the escape mechanism in interpretation mode.
-
-
Pop environment stack,
returning to previous one.
-
-
Push current environment onto stack and switch to
env,
creating it if necessary.
-
-
Copy environment
env
to the current one.
-
-
Exit the formatter.
-
-
Set default font family to previous value.
-
-
Set default font family to
name.
-
-
Disable field mechanism.
-
-
Set field delimiter to~c
and pad glyph to space.
-
-
Set field delimiter to~c1
and pad glyph to~c2.
-
-
Define fallback
character~c
as empty.
-
-
Define fallback
character~c
as
contents.
As
but while that request hides a glyph with the same name in the selected
font,
fchar
definitions are used only if the font
lacks a glyph for
c.
GNU
troff performs this test before searching special fonts.
-
-
Restore previous fill color,
or the default if there is none.
-
-
Select
col
as the fill color.
-
-
Enable filling of output lines;
a pending output line is broken.
Sets
[rs]n[.u].
-
-
Flush any pending output line.
-
-
Mount font with font description file name
id
at no-negative position
pos.
-
-
Mount font with
fon-descriptio-fil-name
as name
id
at no-negative position
pos.
-
-
Define fallback
character~c
specific to
font~f
as empty.
-
-
Define fallback
character~c
specific to
font~f
as
contents.
As
but GNU
troff locates a character defined by
fschar
after any fonts named as arguments to the
fspecial
are searched and before those named as arguments to the
[lq]special[rq]
request.
-
-
Empty the list of fonts treated as special when
f
is selected.
-
-
Declare each font
s
as special only when
font~f
is selected.
GNU
troff searches fonts specified as arguments to the
[lq]special[rq]
request after those given as arguments to the
fspecial
request.
-
-
Select the typeface
font.
If
font
is an integer,
the formatter interprets it as a mounting position;
the font mounted there is selected.
If that position refers to an abstract style,
GNU
troff combines it with the default family
(see
fam
above and
[rs]F
below)
to make a resolved font name.
If
font
is
[lq]DESC[rq],
if the mounting position is not an abstract style
and no font is mounted there,
or the mounting position is negative,
GNU
troff ignores the request.
(It also
emits a warning in category
[lq]font[rq],
or
[lq]range[rq],
as appropriate.
See section [lq]Warnings[rq] in
Also see
[rs]f .
-
-
Remove translation of font named
f.
-
-
Translate font name
f1
to
f2.
-
-
Stop magnifying
font.
-
-
Set magnification of mounted
font
to
zoom,
a multiplier of the current type size in thousandths
(default:
1000).
-
-
Restore previous stroke color,
or the default if there is none.
-
-
Select
col
as the stroke color.
-
-
Reset the hyphenation character
to~[rs]%
(the default).
-
-
Change the hyphenation character
to~c.
-
-
Set the hyphenation code of character
dst1
to that of
src1,
and so on.
-
-
Clear the environment's hyphenation language
(disabling automatic hyphenation).
-
-
Set the environment's hyphenation language to
ident.
-
-
Set the consecutive automatically hyphenated line limit to
-1
(the default),
meaning [lq]no limit[rq].
-
-
Set the consecutive automatically hyphenated line limit to
to~n.
A negative value means [lq]no limit[rq].
-
-
Read hyphenation patterns from
file.
-
-
Append hyphenation patterns from
file.
-
-
Caution:
This request will be withdrawn in a future
groff
release.
Use
hcode
instead.
-
Define mappings for character codes in hyphenation pattern files.
-
-
Define each argument
word
(comprising ordinary,
special,
or indexed characters)
as a
hyphenation exception word
such that each occurrence of a hyphe-minus
[lq]-[rq]
in
word
indicates a hyphenation point.
-
-
Set automatic hyphenation mode to the value of the
.hydefault
register.
-
-
Disable automatic hyphenation;
same as
.nh.
-
-
Set automatic hyphenation mode to
mode;
see section [lq]Hyphenation[rq] below.
-
-
Set hyphenation mode default to
mode;
see section [lq]Hyphenation[rq] below.
-
-
Set the (right) hyphenation margin to
0
(the default).
-
-
Set the (right) hyphenation margin to
length
(default scaling unit~
-
-
Set the hyphenation space to
0
(the default).
-
-
Suppress automatic hyphenation in adjustment modes
[lq]b[rq]
or
[lq]n[rq]
if that adjustment can be achieved by adding no more than
hyphenatio-space
to each inte-word space
(default scaling unit~
-
-
Interpolate a newline if
con-expr
is true,
otherwise skip to a corresponding
request.
-
-
If
con-expr
is true,
interpret
input
as if it were an input line,
otherwise skip to a corresponding
request.
-
-
Interpolate a newline if
con-expr
is true.
-
-
If
con-expr
is true,
then interpret
input
as if it were an input line.
-
-
Ignore input
(except for side effects of
[rs]R
on aut-incrementing registers)
until
[lq]..[rq]
occurs at the start of a control line in the current conditional block.
-
-
Ignore input
(except for side effects of
[rs]R
on aut-incrementing registers)
until
en-mac
is called at the start of a control line in the current conditional
block.
en-mac
can be a request.
-
-
Set indentation amount to previous value.
-
-
Set indentation to
[-]N
(default scaling unit~
-
-
Cancel any pending input line trap.
-
-
Set
(or replace)
an input line trap in the environment,
calling
mac
after the next
npl
productive input lines have been read.
Lines interrupted with the
[rs]c
escape sequence are counted separately.
-
-
Cancel any pending input line trap.
-
-
As
[rq]it[rq],
but lines interrupted with the
[rs]c
escape sequence do not apply to the line count.
-
-
Enable pairwise kerning.
-
-
Enable or disable pairwise kerning
per Boolean expression
b.
-
-
Unset leader repetition character.
-
-
Set leader repetition character
to~c
(default:
[lq].[rq]).
-
-
Compute the number of characters in
contents
and store the count
in the register
reg.
-
-
Activate lin-tabs in the environment.
It is disabled by default.
-
-
Activate or deactivate lin-tabs in the environment per Boolean
expression
b.
-
-
Set the input line number
the formatter uses when reporting diagnostics.
The argument becomes the input line number of the
next
line the formatter reads.
-
-
As
lf
with one argument,
but also update the reported file name to
characte-sequence.
-
-
Enable ligature mode
1.
-
-
Set ligature mode to
m
(0
= disable,
1
= enable,
2
= enable for tw-letter ligatures only).
-
-
Set line length to previous value.
Does not affect a pending output line.
-
-
Set line length to
[-]N
(default length
default scaling unit~
Does not affect a pending output line.
-
-
Unset the leading space macro (trap).
Restore default handling of lines with leading spaces.
-
-
Set the leading space macro (trap) to
mac.
-
-
Change to the previous value of additional intr-line skip.
-
-
Set additional intr-line skip value to
n,
i.e.,
n-1
blank lines are inserted after each text output line.
-
-
Set length of title lines to previous value.
-
-
Set length of title lines
(default length
default scaling unit~
-
-
Cease writing margin character.
-
-
Begin writing margin
character~c
to the right of each output line at a distance of
-
-
Begin writing margin
character~c
on each output line at
distance~d
to the right of the right margin
(default distance
default scaling unit~
-
-
Mark vertical drawing position in an internal register;
see
.rt.
-
-
Mark vertical drawing position in register
reg.
-
-
As
[rq]so[rq],
except that GNU
troff searches for the specified
file
in the same directories as macro files;
see
GROFF_TMAC_PATH
in section [lq]Environment[rq] of
and
-m
in section [lq]Options[rq]
of the same page.
-
-
As
but no warning is emitted if
file
does not exist.
-
-
Disable output line adjustment.
-
-
Break page if distance to next page location trap is less than one vee.
-
-
Break page if distance to next page location trap is less than distance
d
(default scaling unit~
-
-
Disable filling of output lines;
a pending output line is broken.
Clears
[rs]n[.u].
-
-
Disable automatic hyphenation;
same as
[lq].hy 0[rq].
-
-
Deactivate output line numbering.
-
-
Activate output line numbering:
number the next output line
[-]N,
writing numbers every
m
lines
(default 1),
with
s
numeral widths
([rs]0)
between the line number and the output
(default 1),
and indenting the line number by
i
numeral widths
(default 0).
-
-
Suppress numbering of the next output line counted by
nm.
-
-
Suppress numbering of the next
n
output lines counted by
nm.
If
n=0,
cancel suppression.
-
-
Interpolate a newline.
-
-
Interpret
input
as if it were an input line.
-
-
Define or update register
reg
with value
N.
-
-
Define or update register
reg
with value
N
and aut-increment
I,
which may be any integer.
-
-
Make the conditional expressions
n
true and
t
false.
-
-
Enable
n-space mode,
ignoring
.sp
requests until a glyph or
[rs]D
primitive is output.
See
.rs.
-
-
Stop processing the input file and read the next,
if any.
-
-
Stop processing the input file and read
file.
-
-
Open
file
for writing and associate a stream named
ident
with it,
making it available for
[rq]write[rq]
requests.
Unsafe request;
disabled by default.
-
-
As
[lq]open[rq],
but if
file
already exists,
appends to it instead of overwriting it.
Unsafe request;
disabled by default.
-
-
Output vertical space that was saved by the
request.
-
-
Emit
characte-sequence
[lq]transparently[rq]
(directly) to
troff's
output.
-
-
Reset page number character to~
-
-
Change the page number character used in titles
to~c.
-
-
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 JSO-encoded string,
but the output is not otherwise in JSON format.
-
-
Report,
to the standard error stream,
each defined color name,
its color space identifier,
and channel value assignments.
A device's default stroke and/or fill colors,
[lq]default[rq],
are not listed since they are immutable and their details unknown to the
formatter.
-
-
Report,
to the standard error stream,
the name,
color space identifier,
and channel value assignments of each color
col.
-
-
Report,
to the standard error stream,
the list of configured composite character mappings.
See the
[lq]composite[rq]
request.
The [lq]from[rq] code point is listed first,
followed by its [lq]to[rq] 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.
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 [lq]internal name[rq] datum,
the meaning of which varies by output device,
follow.
-
-
Report,
to the standard error stream,
the list of font translations.
-
-
Report,
to the standard error stream,
the list of hyphenation exception words
associated with the hyphenation language
selected by the
hla
request.
A
[lq]-[rq]
marks each hyphenation point.
A word prefixed with
[lq]-[rq]
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
[lq]*[rq].
-
-
Pipe GNU
troff output through
command
(which is read in copy mode)
by passing it to
Multiple
pi
requests construct a mult-stage pipeline in the same order as the
formatter encounters the requests.
Unsafe request;
disabled by default.
-
-
Set page length to default
The current page length is stored in register
.p.
-
-
Change page length to
[-]N
(default scaling unit~
-
-
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
[lq][ ][rq]
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 names of all defined macros,
strings,
and diversions and their lengths in characters or nodes.
-
-
Report,
to the standard error stream,
the JSO-encoded name and contents of each macro,
string,
or diversion
name.
-
-
Set next page number.
-
-
Report the names,
values,
and
(as applicable)
autoincrement amounts and
assigned formats of all defined registers to the standard error stream.
-
-
Report the name and value and,
if its type is numeric,
the autoincrement amount and assigned format,
of each register
reg
to the standard error stream.
-
-
Change to previous page offset.
The current page offset is available in register
.o.
-
-
Alter page offset
(default scaling unit~
-
-
Restore previous type size.
-
Set/increase/decrease the type size to/by
N
scaled points
(a no-positive resulting type size is set to 1~u);
also see
-
-
Retrieve the bounding box of the PostScript image found in
postscrip-file,
which must conform to Adobe's Document Structuring Conventions (DSC).
See registers
llx,
lly,
urx,
ury.
-
-
As
[lq]so[rq],
except that input comes from the standard output stream of
command,
which is passed to
Unsafe request;
disabled by default.
-
-
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).
-
-
Report names and positions of all page location traps to the standard
error stream.
-
-
Change to previous pos-vertical line spacing.
-
-
Change pos-vertical line spacing according to
[-]N
(default scaling unit~
-
-
Remove definition of each
ordinary,
special,
or
indexed
character
c,
undoing the effect of a
char,
fchar,
or
schar
request.
Spaces need not separate
c
arguments.
The character definition removed
(if any)
is the first encountered in the resolution process documented
in section [lq]Using Symbols[rq] of
Groff: The GNU Implementation of troff.
Glyphs,
which are defined by font description files,
cannot be removed.
-
-
Read insertion from standard input stream,
ringing terminal bell as prompt.
-
-
Read insertion from standard input stream,
writing
termina-message
to standard error stream as prompt.
-
-
Stop interpreting an interpolated macro,
skipping the remainder of its definition.
-
-
As
return,
but perform the skip twice[em]once within the macro being interpreted
and once in an enclosing macro.
-
-
Remove each fallback special
character~c
for font
f.
Spaces need not separate
c
arguments.
See
fschar.
-
-
Break,
righ-align the output of the next productive input line without
filling,
then break again.
-
-
Break,
righ-align the output of the next
npl
productive input lines without filling,
then break again.
If
npl
[<=] 0,
stop righ-aligning.
-
-
Remove each request,
macro,
diversion,
or string
name.
-
-
Rename request,
macro,
diversion,
or string
old
to
new.
-
-
Rename register
reg1
to
reg2.
-
-
Remove each register
reg.
-
-
Restore spacing;
disable n-space mode.
See
.ns.
-
-
Return
(upward only)
to vertical position marked by
.mk
on the current page.
-
-
Return
(upward only)
to vertical position
N
(default scaling
unit~
-
-
Define global fallback character
c
as empty.
-
-
Define global fallback character
c
as
contents.
As
char,
but GNU
troff locates a character defined with
schar
after any fonts named as arguments to the
[lq]special[rq]
request and before any mounted special fonts.
-
-
Reset the soft hyphen character to
-
-
Set the soft hyphen character
to~c.
-
-
Shift macro or string parameters one place
n
places:
argument~i
becomes argument
i-1;
argument 1
becomes unavailable.
-
-
Shift macro or string parameters
n
places:
argument~i
becomes argument
i-n;
arguments 1
to~n
become unavailable.
-
-
Set available type sizes to the list of values or ranges;
each
si
is interpreted in units of scaled points (
GNU
troff strips a leading neutral double quote from
s1;
it reads
each
si
in copy mode.
-
-
Replace the request's control line
with the contents of
file,
[lq]sourcing[rq] it.
GNU
troff searches for
file
in any directories specified by
-I
comman-line options,
followed by the current working directory.
If
file
does not exist,
the formatter ignores the request.
(GNU
troff emits a warning in category
[lq]file[rq].)
-
-
As
[rq]so[rq],
but no warning is emitted if
file
does not exist.
-
-
Break and move the next text baseline down by one vee,
or until springing a page location trap.
If invoked with the n-break control character,
sp
moves the text baseline applicable to the entire pending output line.
-
-
As
sp,
but move by
vertica-distance
instead of
1v.
Inside a diversion,
the formatter ignores any argument.
A negative
vertica-distance
cannot reduce the position of the text baseline below zero.
Applying the boundar-relative measurement operator
[or]
operator to
vertica-distance,
as in
[lq][or]N[rq],
moves to a position relative to the page top for positive
N,
and the bottom if
N
is negative.
-
-
Empty the list of special fonts designated by this request
when given arguments.
-
-
Declare each font
s
as special,
irrespective of its description file,
populating a list that
GNU
troff searches,
in order,
to find the glyph demanded.
GNU
troff searches fonts specified as arguments to the
[lq]special[rq]
request after those given as arguments to the
fspecial
request.
-
-
Toggle the spread warning on and off (the default) without changing its
value.
-
-
Emit a
break
warning if the additional space inserted for each space between words in
an adjusted output line is greater than or equal to
N.
A negative
N
is treated as 0.
The default scaling unit is~
At startup,
is inactive and
N
is
-
-
Set minimum inte-word space and supplemental inte-sentence space sizes
to
n~12ths
of the selected font's
spacewidth
parameter
(default: 12).
-
-
As
[lq].ss~n[rq],
but set supplemental inte-sentence space size to
m~12ths
of the selected font's
spacewidth
parameter.
-
-
Replace each byte in the string named
str
with its lowercase version.
-
-
Replace each byte in the string named
str
with its uppercase version.
-
-
Associate abstract
style
with no-negative font position
pos.
-
-
Replace the string named
str
with its substring bounded by the indices
start
and
end,
inclusive.
Negative indices count backward from the end of the string.
-
-
As
but save
for output with
request.
-
-
As
but save distance
d
for later output with
request
(default scaling unit~
-
-
Execute
command
(which is read in copy mode)
in the operating environment
by passing it to
See register
systat.
Unsafe request;
disabled by default.
-
-
Clear tab stops.
-
-
Set tabs at positions
n1,
n2,
...,
nn,
then set tabs at
nn+m[tmu]rn+r1
through
nn+m[tmu]rn+rn,
where
m
increments from 0,
1,
2,
... to the output line length.
Each
n~argument
can be prefixed with
a~[lq]+[rq]
to place the tab stop
ni
at a distance relative to the previous,
n(i-1).
Each argument
ni~or~ri
can be suffixed with a letter to align text within the tab column
bounded by tab stops
i~and~i+1;
[lq]L[rq]
for lef-aligned
(the default),
[lq]C[rq]
for centered,
and
[lq]R[rq]
for righ-aligned.
-
-
Reserved for internal use.
-
-
Reserved for internal use.
-
-
Unset tab repetition character.
-
-
Set tab repetition character
to~c
(default: none).
-
-
Temporarily indent next output line
(default scaling unit~
-
-
Enable track kerning for
font.
-
-
Format thre-part title.
-
-
Write a newline to the standard error stream.
-
-
Send
termina-message,
followed by a newline,
to the standard error stream.
The formatter reads the argument
to the end of the input line in copy mode,
but does
not
remove a leading double quote;
contrast
.tm1.
-
-
As
-
-
As
but removes a leading neutral double quote
[oq][dq][cq]
from
message,
permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
-
-
No operation.
-
-
As
but does not append a newline.
-
-
Translate ordinary or special characters
a
to
b,
c
to
d,
and so on prior to output.
-
-
Break and copy contents of
file
as [lq]throughput[rq] to GNU
troff output
(see
Unlike
characters invalid as input to GNU
troff are discarded.
If
file's
contents do not end with a newline,
trf
appends one.
-
-
As
except that
ignores the translation when a diversion is interpolated.
-
-
As
except that translations are suppressed in the argument to
-
-
Make the conditional expressions
t
true and
n
false.
-
-
Set underline font used by
to
font.
-
-
Underline
(italicize in
troff
mode)
the output of the next productive input line.
-
-
Underline
(italicize in
troff
mode)
the output of the next
npl
productive input line.
If
npl=0,
stop underlining.
-
-
Unformat space characters and tabs in diversion
div,
preserving font information.
-
-
Enable vertical position traps.
They are enabled by default.
-
-
Enable or disable vertical position traps per Boolean expression
b.
-
-
Change to previous vertical spacing.
-
-
Set vertical spacing to
[-]N
(default scaling unit~
-
-
Enable all warning categories.
-
-
Disable all warning categories.
-
-
Enable warnings in categories whose codes sum
to~n;
see
-
-
Select scaling unit used in certain warnings (one of
u,
i,
c,
p,
or
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.
-
-
Remove visible page location trap at
vertica-position
(default scaling unit~
-
-
Plant macro
mac
as page location trap at
vertica-position
(default scaling unit~
removing any visible trap already there.
-
-
Interpolate newlines unless and until
con-expr
evaluates false.
-
-
Repeatedly execute
input
unless and until
con-expr
evaluates false.
-
-
Write
characte-sequence,
a sequence of ordinary characters,
spaces,
or tabs,
to
stream,
which must previously have been the subject of an
[lq]open[rq]
(or
opena)
request,
followed by a newline.
GNU
troff flushes the stream after writing to it.
-
-
As
[rq]write[rq],
but does not write a newline to the output.
-
-
Write the contents of the macro or string
name
to
stream,
which must previously have been the subject of an
[lq]open[rq]
(or
opena)
request.
GNU
troff reads the contents of
name
in copy mode.
Escape sequence short reference
The escape sequences
and
are interpreted even in copy mode.
The escape sequences
and
are not tokenized when
GNU
troff reads its input.
updates only the formatter's register dictionary,
and does not contribute (directly) to output.
The others alter the environment
(see section [lq]Environments[rq] below).
See the [lq]GNU troff Internals[rq] section of the
groff
Texinfo manual.
-
-
Comment;
read everything up to the next newline in copy mode and discard it.
-
-
Whol-line comment;
read everything up to and including the next newline in copy mode and
discard it.
-
-
Interpolate string with on-character
name~s.
-
-
Interpolate string with tw-character
name~st.
-
-
Interpolate string with name
string
(of arbitrary length).
-
-
Interpolate string with name
string
(of arbitrary length),
taking
arg
...
as arguments.
-
-
Interpolate name by which currently executing macro was invoked.
-
-
Interpolate macro or string parameter
numbered~n
(1[<=]n[<=]9).
-
-
Interpolate macro or string parameter
numbered~nn
(01[<=]nn[<=]99).
-
-
Interpolate macro or string parameter
numbered~nnn
(nnn[>=]1).
-
-
Interpolate catenation of all macro or string parameters,
separated by spaces.
-
-
Interpolate catenation of all macro or string parameters,
with each surrounded by double quotes and separated by spaces.
-
-
Interpolate catenation of all macro or string parameters
as if they were arguments to the
request.
-
-
is a synonym for
the acute accent special character.
-
-
is a synonym for
the grave accent special character.
-
-
is a synonym for
the minus sign special character.
-
-
is a synonym for
the underrule special character.
-
-
Mark a hyphenation point within a word.
At the beginning of a word,
prevent it from being otherwise hyphenated.
-
-
Transparently
embed
characte-sequence,
up to and including the end of the line,
into the current diversion,
requests,
macro calls,
and escape sequences
when reading them into a diversion.
Doing so prevents them from taking effect
until the diverted text is actually output.
-
-
Transparently embed
characte-sequence,
up to its own next occurrence on the input line,
into a diversion,
or unformatted as an output comparand in a conditional expression.
Ignored in the to-level diversion.
-
-
Move right one inte-word space.
-
-
Insert an unbreakable,
adjustable space.
-
-
Move right by the width of a numeral in the current font.
-
-
Move on-sixth em to the right on typesetters.
-
-
Move on-twelfth em to the right on typesetters.
-
-
Interpolate a dummy character.
-
-
Interpolate a dummy character that is transparent to en-o-sentence
recognition.
-
-
Apply italic correction.
Use between an immediately adjacent oblique glyph on the left and an
upright glyph on the right.
-
-
Apply left italic correction.
Use between an immediately adjacent upright glyph on the left and an
oblique glyph on the right.
-
-
No-printing break point
(similar to
but never produces a hyphen glyph).
-
-
Continue current input line on the next.
-
-
Begin conditional input.
-
-
End conditional input.
-
-
Interpolate glyph of special character with tw-character identifier
sc.
-
-
Interpolate glyph of special character with identifier
spchar
(of arbitrary length).
-
-
Interpolate composite glyph constructed from
bas-char
and each component
comp.
-
-
Interpolate glyph of eigh-bit encoded character
nnn,
where
0[<=]nnn[<=]255.
-
-
Interpolate glyph of Unicode character with code point
nnnn[n[n]]
in uppercase hexadecimal.
-
-
Interpolate composite glyph from Unicode character
bas-char
and
combinin-components.
-
-
Interpolate a leader in copy mode.
-
-
Interpolate 1 if
input
is a valid identifier,
and~0 otherwise.
Because GNU
troff ignores any input character with an invalid code when reading it,
invalid identifiers are empty or contain
spaces,
tabs,
newlines,
or
escape sequences
that interpolate something other than a sequence of ordinary characters.
-
-
Build bracket:
pile a sequence of glyphs corresponding to each character in
string
vertically,
and center it vertically on the output line.
-
-
Interpolate 1 if
input
is a valid numeric expression,
and~0 otherwise.
-
-
Continue output line at next input line.
-
-
As
but compatible with other
troff implementations.
-
-
Move downward [12]~em on typesetters.
-
-
See subsection [lq]Drawing commands[rq] below.
-
-
Interpolate the escape character.
-
-
As
but not interpreted in copy mode.
-
-
Select previous font mounting position
(abstract style or font);
same as
[lq].ft[rq]
or
[lq].ft~P[rq].
-
-
Select font mounting position,
abstract style,
or font with on-character name or on-digit
position~F.
F~cannot
be
P.
-
-
Select font mounting position,
abstract style,
or font with tw-character name or tw-digit
position~ft.
-
-
Select font mounting position,
abstract style,
or font with arbitrarily long name or position
font.
font
cannot be
P.
-
-
Select previous font mounting position
(abstract style or font).
-
-
Set default font family to that with on-character
name~f.
-
-
Set default font family to that with tw-character
name~fm.
-
-
Set default font family to that with arbitrarily long name
fam.
-
-
Set default font family to previous value.
-
-
Interpolate format of register with on-character
name~r.
-
-
Interpolate format of register with tw-character
name~rg.
-
-
Interpolate format of register with arbitrarily long name
reg.
-
-
Horizontally move the drawing position by
N~ems
(or specified units);
[or]
may be used.
Positive motion is rightward.
-
-
Set
(increment, decrement)
the height of the current font,
but not its width.
If
N
is zero,
the formatter uses the font's inherent height for its type size
default scaling unit~
-
-
Store the horizontal drawing position,
relative to that corresponding to the start of the input line
(ignoring page offset and indentation),
in register
name~r.
-
-
Store the horizontal drawing position,
relative to that corresponding to the start of the input line
(ignoring page offset and indentation),
in register
name~rg.
-
-
Store the horizontal drawing position,
relative to that corresponding to the start of the input line
(ignoring page offset and indentation),
in register
name~reg.
-
-
Draw horizontal line of length
N
with character
c
(default:
[rs][ru];
default scaling unit~
-
-
Draw vertical line of length
N
with character
c
(default:
[rs][br];
default scaling unit~
-
-
Select stroke color with on-character
name~c.
-
-
Select stroke color with tw-character
name~cl.
-
-
Select stroke color with arbitrarily long
name~color.
-
-
Restore previous stroke color.
-
-
Select fill color with on-character
name~c.
-
-
Select fill color with tw-character
name~cl.
-
-
Select fill color with arbitrarily long
name~color.
-
-
Restore previous fill color.
-
-
Interpolate value of register with on-character
name~r.
-
-
Interpolate value of register with tw-character
name~rg.
-
-
Interpolate value of register with arbitrarily long
name~reg.
-
-
Format indexed character numbered
n
in the current font.
-
-
Overstrike centered glyphs of characters
a,
b,
c,
and so on.
-
-
At the outermost suppression level,
disable emission of glyphs and geometric objects to the output
driver.
-
-
At the outermost suppression level,
enable emission of glyphs and geometric objects to the output driver.
-
-
At the outermost suppression level,
enable glyph and geometric primitive emission to the output driver and
write to the standard error stream the page number,
four bounding box registers enclosing glyphs written since the previous
[rs]O
escape sequence,
the page offset,
line length,
image file name
(if any),
horizontal and vertical device motion quanta,
and input file name.
-
-
Begin a nested suppression level.
-
-
End a nested suppression level.
-
-
At the outermost suppression level,
write the name
file
to the standard error stream at
position~P,
which must be one of
l,
r,
c,
or
i.
-
-
Break output line at next word boundary;
adjust if applicable.
-
-
Move [lq]in reverse[rq] (upward) 1~em.
-
-
Set,
increment,
or decrement register
name
by~N.
-
-
Set/increase/decrease the type size to/by
N
scaled points.
N
must be a single digit.
If
n~is
an unsigned
[lq]0[rq],
restore the previous size.
(In compatibility mode only,
a no-zero
N
must be in the range 4[en]39.)
Otherwise,
as
request.
-
-
s[-](N
Set/increase/decrease the type size to/by
N
scaled points;
N
is a tw-digit number [>=]1.
If
n~is
an unsigned
[lq]00[rq],
restore the previous size.
Otherwise,
as
request.
-
-
s[-][N]
s[-][aq]N[aq]
Set/increase/decrease the type size to/by
N
scaled points.
If
n~is
an unsigned
[lq]0[rq]
(with any number of leading zeroes),
restore the previous size.
Otherwise,
as
request.
-
-
Slant the glyphs of the currently selected font by
@var{N}
degrees.
Positive values slant in the direction of text flow.
Only integer values are possible.
-
-
Interpolate a tab in copy mode.
-
-
Move upward [12]~em on typesetters.
-
-
Vertically move the drawing position by
N~vees
(or specified units);
[or]
may be used.
Positive motion is downward.
-
-
Interpolate value of system environment variable with on-character
name~e
as returned by
-
-
Interpolate value of system environment variable with tw-character
name~ev
as returned by
-
-
Interpolate value of system environment variable with arbitrarily
long
name~env
as returned by
-
-
Interpolate the width of
input,
as interpreted,
in basic units.
This escape sequence
allows several properties of formatted output to be measured
without writing it out.
The formatter processes
input
in a dummy environment:
this means that font and type size changes,
for example,
may occur within it without affecting subsequent output.
-
-
Increase vertical spacing of pending output line by
N~vees
(or specified units;
negative before,
positive after).
-
-
Write
characte-sequence
to
troff
output as a device extension command.
The
groff
special character repertoire is unknown to output drivers outside of
glyphs named in a device's fonts,
and even then they may not possess complete coverage of the names
documented in
Further,
escape sequences that produce horizontal or vertical motions,
hyphenation breaks,
or that are dummy characters may appear in strings
or be converted to nodes,
particularly in diversions. These are not representable when interpolated directly into
devic-independent output,
as might be done when writing out tag names for PDF bookmarks,
which can appear in a viewer's navigation pane.
So that documents or macro packages do not have to laboriously
[lq]sanitize[rq] strings destined for interpolation
in device extension commands,
this escape sequence
performs certain transformations on its argument.
For these transformations,
character translations and definitions are ignored.
GNU
troff converts several ordinary characters that typeset as no-basic Latin
code points to code points outside that range so that they are used
consistently whether they are formatted as glyphs or used in a device
control command argument.
These ordinary characters are
[lq][aq][rq],
[lq]-[rq],
[lq][ha][rq],
[lq][ga][rq],
and
[lq][ti][rq];
others are written a-is.
Special characters that typeset as Unicode basic Latin characters
are translated to basic Latin characters accordingly.
So that any Unicode code point can be represented in device extension
commands,
for example in an author's name in document metadata
or as a usefully named bookmark or hyperlink anchor,
GNU
troff maps other special characters to Unicode special character notation.
Special characters without a Unicode representation,
and escape sequences that do not interpolate a sequence
of ordinary and/or special characters,
produce warnings in category
[lq]char[rq].
-
-
Write contents of macro or string
n
to
troff
output as a device extension command.
-
-
Write contents of macro or string
nm
to
troff
output as a device extension command.
-
-
Write contents of macro or string
name
to
troff
output as a device extension command.
-
-
Format character
c
with zero width[em]without advancing the drawing position.
-
-
Save the drawing position,
format
input,
then restore it.
GNU
troff ignores tabs and leaders in
input
with an error diagnostic.
Drawing commands
Drawing commands direct the output device to render geometrical objects
rather than glyphs.
Specific devices may support only a subset,
or may feature additional ones;
consult the man page for the output driver in use.
Terminals in particular implement almost none.
Rendering starts at the drawing position;
when finished,
the drawing position is left at the rightmost point of the object,
even for closed figures,
except where noted.
GNU
troff draws stroked (outlined) objects with the stroke color,
and shades filled ones with the fill color.
See section [lq]Colors[rq] above.
Coordinates
h
and
v
are horizontal and vertical motions relative to the drawing position
or previous point in the command.
The default scaling unit for horizontal measurements
(and diameters of circles)
is~
m;
for vertical ones,
v.
Circles,
ellipses,
and polygons can be drawn stroked or filled.
These are independent properties;
if you want a filled,
stroked figure,
you must draw the same figure twice using each drawing command.
A filled figure is always smaller than an outlined one because the
former is drawn only within its defined area,
whereas strokes have a line thickness
(set with
[rs]D[aq]t[aq]).
- [rs]D[aq][ti]~h1 v1~
-
...~hn vn[aq]
Draw -spline to each point in sequence,
leaving drawing position at
(hn,~vn).
- [rs]D[aq]a~hc vc h v[aq]
-
Draw circular arc centered at
(hc,~vc)
counterclockwise from the drawing position to a point
(h,~v)
relative to the center.
(hc,~vc)
is adjusted to the point nearest the perpendicular bisector of the arc's
chord.
- [rs]D[aq]c~d[aq]
-
Draw circle of diameter
d
with its leftmost point at the drawing position.
- [rs]D[aq]C~d[aq]
-
As
[rs]D[aq]C[aq],
but the circle is filled.
- [rs]D[aq]e~h v[aq]
-
Draw ellipse of width
h
and height
v
with its leftmost point at the drawing position.
- [rs]D[aq]E~h v[aq]
-
As
[rs]D[aq]e[aq],
but the ellipse is filled.
- [rs]D[aq]l~h v[aq]
-
Draw line from the drawing position to
(h,~v).
- [rs]D[aq]p~h1 v1~
-
...~hn vn[aq]
Draw polygon with vertices at the drawing position
and each point in sequence.
GNU
troff closes the polygon by drawing a line from
(hn,~vn)
back to the initial drawing position.
Afterward,
the drawing position is left at
(hn,~vn).
- [rs]D[aq]P~h1 v1~
-
...~hn vn[aq]
As
[rs]D[aq]p[aq],
but the polygon is filled.
- [rs]D[aq]t~n[aq]
-
Set stroke thickness of geometric objects to
to~n
basic units.
A zero
n
selects the minimum supported thickness.
A negative
n
selects a thickness proportional to the type size;
this is the default.
Strings
groff
supports strings primarily for user convenience.
Conventionally,
if one would define a macro only to interpolate a small amount of text,
without invoking requests or calling any other macros,
one defines a string instead.
Only one string is predefined by the language.
-
-
Contains the name of the output device
(for example,
[lq]utf8[rq]
or
[lq]pdf[rq]).
The
request creates a string with a specified name and contents.
If the identifier named by
already exists as an alias,
the target of the alias is redefined.
If
is invoked with only one argument,
the named string becomes empty.
The formatter removes a leading neutral double quote
[oq][dq][cq]
from
contents
to permit the embedding of leading spaces.
It interprets any other
[oq][dq][cq]
literally,
but the wise author uses the special character escape sequence
[rs][dq]
instead if the string
might be interpolated as part of a macro argument;
see section [lq]Calling macros[rq] above.
The
escape sequence dereferences a string's name,
interpolating its contents.
If the name does not exist,
the formatter defines it as empty,
interpolates nothing,
and emits a warning in category
[lq]mac[rq].
See section [lq]Warnings[rq] in
The bracketed interpolation form accepts arguments that are handled as
macro arguments are;
see section [lq]Calling macros[rq] above.
In contrast to macro calls,
an argument containing a closing bracket
]
must be enclosed in double quotes.
When defining strings,
argument interpolations must be escaped if they are to reference
parameters from the calling context;
see section [lq]Parameters[rq] below.
Any no-initial neutral double quote
[dq]
is interpreted literally,
but it is wise to use the special character escape sequence
[rs][dq]
instead if the string might be interpolated as part of a macro argument;
see section [lq]Calling macros[rq] above.
Strings are not limited to a single input line of text.
[rs]newline
works just as it does elsewhere.
The resulting string is stored
without
the newlines.
When filling is disabled,
care is required to avoid overrunning the line length when interpolating
strings.
Conversely,
when filling is enabled,
it is not necessary to append
[rs]c
to a string interpolation to prevent a break afterward,
as might be required in a macro argument.
Nor does a string require use of
the GNU
troff chop
request to excise a trailing newline as is often done with diversions.
It is not possible to embed a newline in a string that will be
interpreted as such when the string is interpolated.
To achieve that effect,
use
[rs]*
to interpolate a macro instead;
see section [lq]Punning names[rq] below.
The
[lq]as[rq]
request is similar to
but appends to a string instead of redefining it.
If
[lq]as[rq]
is invoked with only one argument,
no operation is performed
(beyond dereferencing the string).
Because strings are similar to macros,
they too can be defined to suppress AT&T
troff compatibility mode enablement when interpolated;
see section [lq]Compatibility mode[rq] below.
The
request defines a string that suspends compatibility mode when the
string is later interpolated.
is likewise similar to
[lq]as[rq],
with compatibility mode suspended when the appended portion of the
string is later interpolated.
Caution:
These requests treat the remainder of the input line
as their second argument,
including any spaces,
up to a newline or comment escape sequence.
Ending string definitions
(and appendments)
with a comment,
even an empty one,
prevents unwanted space from creeping into them during source document
maintenance.
This rule and suggestion also applies to the second argument of the
[lq]length[rq]
request,
to requests that define characters
(char,
fchar,
fschar,
and
schar),
and to the file name or command arguments of the
cf,
hpf,
hpfa,
mso,
msoquiet,
nx,
[lq]open[rq],
opena,
pi,
pso,
[lq]so[rq],
soquiet,
and
trf
requests.
Several requests exist to perform rudimentary string operations.
Strings can be queried
(
and modified
(
and their names can be manipulated through renaming,
removal,
and aliasing
(
Redefinitions and appendments [lq]write through[rq] request,
macro,
string,
and diversion names.
To replace an aliased object with a separately defined one,
you must use the
rm
request on its name first.
Registers
In the
roff
language,
numbers and measurements can be stored in
registers.
Many buil-in registers exist,
supplying anything from components of the date
to details of formatting parameters;
some of these are rea-only.
You can also define your own.
See section [lq]Identifiers[rq] above
regarding the construction of valid names for registers.
Each register
(except rea-only ones)
can be assigned a
format,
causing its value to interpolate with leading zeroes,
in Roman numerals,
or alphabetically.
Some rea-only registers are strin-valued,
meaning that they interpolate text and lack a format.
Define registers and update their values with the
nr
request or the
[rs]R
escape sequence.
Use-defined registers can also be incremented or decremented
by a configured amount
at the time they are interpolated.
The value of the increment is specified with a third argument to the
nr
request,
and a special interpolation syntax,
[rs]n[-],
alters and then retrieves the register's value.
Together,
these features are called
aut-increment.
(A negative aut-increment can be
considered an [lq]aut-decrement[rq].)
Many predefined registers are available.
The following presentation uses
register interpolation syntax
[rs]n[name]
to refer to a register
name
to clearly distinguish it from a string or request
name;
the symbols
[rs]n[]
are
not
part of the register name.
The register name space is separate from that used for requests,
macros,
strings,
and diversions.
Rea-only registers
Predefined registers whose identifiers start with a dot are rea-only.
Many are Boolea-valued.
Caution:
Buil-in registers are subject to removal like others;
once removed,
they can be recreated only as normal writable registers
and will not otherwise reflect the configuration of the formatter.
A register name
is often associated with a request of the same name
(without the dot);
exceptions are noted.
-
-
Count of arguments passed to currently interpolated macro or string.
-
-
Amount of extra pos-vertical line space;
see
-
-
Approximate output is being formatted (Boolea-valued);
see
troff
-a
option.
-
-
Font emboldening offset;
see
-
-
The normal control character was used to call the macro being
interpreted (Boolea-valued).
-
-
Input line number;
see
and
-
-
AT&T
troff compatibility mode is enabled (Boolea-valued);
see
Always false when processing
[rq]do[rq];
see
-
-
Depth of last glyph formatted in the environment;
positive if glyph extends below the baseline.
-
-
Count of input lines remaining to be centered
in the environment.
-
-
Height of last glyph formatted in the environment;
positive if glyph extends above the baseline.
-
-
Color output is enabled (Boolea-valued).
-
-
Within
[rq]do[rq],
the saved value of compatibility mode;
see
-
-
Skew of the last glyph formatted in the environment;
see
-
-
Vertical drawing position in diversion.
-
-
Name of environment (strin-valued).
-
-
Mounting position of selected font;
see
and
-
-
Name of input file (strin-valued);
see
-
-
Name of the environment's default font family (strin-valued).
-
-
Resolved name of font selected in the environment (strin-valued);
see
and
-
-
Next no-zero free font mounting position index.
-
-
Always true in GNU
troff (Boolea-valued).
-
-
Text baseline hig-water mark on page or in diversion.
-
-
Horizontal motion quantum of output device in basic units.
-
-
Height of the environment's selected font;
see
-
-
Hyphenation language in environment (strin-valued).
-
-
Count of immediately preceding consecutive hyphenated lines in
environment.
-
-
Maximum quantity of consecutive hyphenated lines allowed in environment.
-
-
Automatic hyphenation mode in environment.
-
-
Hyphenation mode default in environment.
-
-
Hyphenation margin in environment.
-
-
Hyphenation space adjustment threshold in environment.
-
-
Environment's indentation amount;
see
[rq]in[rq].
-
-
Indentation amount applicable to the output line pending
in the environment;
see
-
-
The text most recently formatted in the environment
was [lq]interrupted[rq] or continued with
(Boolea-valued).
-
-
Count of input lines remaining
in the environment's pending input trap.
-
-
The environment's pending input trap honors output line continuation
with
(Boolea-valued).
-
-
Name of the macro associated with the pending input trap
(strin-valued).
-
-
The environment's adjustment mode encoded as an integer;
see
and
Do not interpret or perform arithmetic on its value.
-
-
The environment's horizontal drawing position relative to indentation.
-
-
Pairwise kerning is enabled (Boolea-valued).
-
-
Line length;
see
-
-
Line spacing;
see
-
-
Ligature mode.
-
-
Lin-tabs mode is enabled in the environment (Boolea-valued).
-
-
Line length applicable to the environment's pending output line.
-
-
Environment's title line length.
-
-
Stroke color (strin-valued);
see
and
The default stroke color is named
[lq]default[rq].
-
-
Fill color (strin-valued);
see
and
The default fill color is named
[lq]default[rq].
-
-
Length of formatted output on previous output line.
-
-
Amount of vertical space required by last
that caused a trap to be sprung;
also see
-
-
Output line numbering is enabled in the environment (Boolea-valued).
-
-
Count of lines remaining in the environment
for which numbering is suppressed
while output line numbering is enabled.
-
-
N-space mode is enabled (Boolea-valued).
-
-
Page offset;
see
-
-
Output suppression nesting level;
see
-
-
Page length;
see
-
-
The page is selected for output (Boolea-valued);
see
troff
-o
option.
-
-
Page ejection is in progress (Boolea-valued).
-
-
Number of the next page.
-
-
The environment's type size in scaled points.
-
-
The environment's most recently requested type size in scaled points;
see
and
-
-
The environment's pos-vertical line spacing.
-
-
Maximum representable integer in GNU
troff.
-
-
Count of input lines remaining to be righ-aligned
in the environment.
-
-
The environment's type size in points as a decimal fraction
(strin-valued);
see
and
-
-
Reserved.
Plan~9
troff uses this name for roughly the same purpose as
GNU
troff's
-
-
Slant in degrees of the environment's selected font;
see
-
-
The environment's most recently requested type size
in points as a decimal fraction
(strin-valued);
see
and
-
-
Size of the environment's minimum inte-word space
in twelfths of the space width of the selected font.
-
-
Size of the environment's supplemental inte-sentence space
in twelfths of the space width of the selected font.
-
-
The environment's selected abstract style (strin-valued);
see
and
-
-
Distance to next vertical position trap;
see
and
If no such traps exist between the drawing position
and the bottom of the page,
troff
interpolates the distance to the page bottom.
Within a diversion,
in the absence of a diversion trap,
this distance is
the maximum possible vertical position supported by the output device.
-
-
An output device was explicitly selected (Boolea-valued);
see
troff
-T
option.
-
-
The environment's tab stop settings
(if any)
suitable for use as argument to
(strin-valued).
-
-
Name of the next vertical position trap
after the vertical drawing position.
(strin-valued);
see
and
-
-
Amount of vertical space truncated by the most recently sprung
vertical position trap,
or,
if the trap was sprung by an
minus the amount of vertical motion produced by
also see
-
-
Filling is enabled in the environment (Boolea-valued);
see
and
-
-
Unsafe mode is enabled (Boolea-valued);
see
troff
-U
option.
-
-
The environment's vertical line spacing;
see
-
-
Vertical motion quantum of the output device in basic units.
-
-
Vertical position traps are enabled (Boolea-valued).
-
-
Width of last glyph formatted in the environment.
-
-
Sum of the numeric codes of enabled warning categories.
-
-
Major version number of the running
troff
formatter.
-
-
Minor version number of the running
troff
formatter.
-
-
Revision number of the running
troff
formatter.
-
-
Name of diversion (strin-valued).
Empty if output is directed to the to-level diversion.
-
-
Magnification of the environment's selected font
(in thousandths;
zero if no magnification);
see
Writable predefined registers
Several registers are predefined but also modifiable;
some are updated upon interpretation of certain requests or escape
sequences.
Dat- and tim-related registers are set to the local time as determined
by
when the formatter launches.
This initialization can be overridden by
SOURCE_DATE_EPOCH
and
TZ;
see section [lq]Environment[rq] of
-
-
Process ID of
troff.
-
-
Page number.
-
-
Input line number.
-
-
Union of character types of each glyph rendered into dummy environment
by
-
-
Width of last closed diversion.
-
-
Height of last closed diversion.
-
-
Day of the week (1[en]7;
1 is Sunday).
-
-
Day of the month (1[en]31).
-
-
Count of hours elapsed since midnight (0[en]23).
-
-
Horizontal drawing position relative to that at the start of the input
line.
-
-
Lowe-left
x
coordinate
(in PostScript units)
of PostScript image;
see
-
-
Lowe-left
y
coordinate
(in PostScript units)
of PostScript image;
see
-
-
Output line number;
see
-
-
Count of leading spaces on input line.
-
-
Amount of horizontal space corresponding to leading spaces on input
line.
-
-
Count of minutes elapsed in the hour (0[en]59).
-
-
Month of the year (1[en]12).
-
-
Vertical drawing position.
-
-
-
-
-
-
-
-
These four registers mark the top lef- and bottom righ-hand corners of
a rectangle encompassing all formatted output on the page.
They are reset to -1 by
[rs]O0
or
[rs]O1.
-
-
As
adding maximum glyph height to measurement.
-
-
As
adding maximum glyph depth to measurement.
-
-
Maximum displacement of text baseline below its original position
after rendering into dummy environment by
-
-
Count of seconds elapsed in the minute (0[en]60).
-
-
Skew of last glyph rendered into dummy environment by
-
-
The maximum depth of
troff's
internal input stack.
If [<=]0,
there is no limit:
recursion can continue until available memory is exhausted.
The default is 1,000.
-
-
Subscript correction of last glyph rendered into dummy environment by
-
-
Maximum displacement of text baseline above its original position
after rendering into dummy environment by
-
-
Return value of
see
-
-
Uppe-right
x
coordinate
(in PostScript units)
of PostScript image;
see
-
-
Uppe-right
y
coordinate
(in PostScript units)
of PostScript image;
see
-
-
Gregorian year.
-
-
Gregorian year minus 1900.
Using fonts
In digital typography,
a
font
is a collection of characters in a specific typeface that a device can
render as glyphs at a desired size.
(Terminals and some typesetters have fonts that render at only one or
two sizes.
As examples,
take the
groff
lj4
device's
Lineprinter,
and
lbp's
Courier and Elite faces.)
A
roff
formatter can change typefaces at any point in the text.
The basic faces are a set of
styles
combining upright and slanted shapes with normal and heavy stroke
weights:
[lq]
R[rq],
[lq]
I[rq],
[lq]
B[rq],
and
[lq]
BI[rq][em]these stand for
roman,
bold,
italic,
and
bol-italic.
For linguistic text,
GNU
troff groups typefaces into
families
containing each of these styles.
(Font designers prepare families such that the styles share esthetic
properties.)
A
text font
is thus often a family combined with a style,
but it need not be:
consider the
ps
and
pdf
devices'
ZCMI
(Zapf Chancery Medium italic)[em]often,
no other style of Zapf Chancery Medium is provided.
On typesetters,
at least one
special font
is available,
comprising
unstyled
glyphs for mathematical operators and other purposes.
Like the AT&T
troff formatter,
GNU
troff does not itself load or manipulate a digital font file;
instead it
works with a
font description file
that characterizes it,
including its glyph repertoire and the
metrics
(dimensions) of each glyph.
This information permits the formatter to accurately place glyphs with
respect to each other.
Before using a font description,
the formatter associates it with a
mounting position,
a place in an ordered list of available typefaces.
So that a document need not be strongly coupled to a specific font
family,
in GNU
troff an output device can associate a style in the abstract sense with a
mounting position.
Thus the default family can be combined with a style dynamically,
producing a
resolved font name.
A use-specified font name that combines family and style,
or refers to a font that is not a member of a family,
is already [lq]resolved[rq].
Fonts often have trademarked names,
and even Free Software fonts can require renaming upon modification.
groff
maintains a convention that a device's serif font family is given the
name
T
([lq]Times[rq]),
its san-serif family
H
([lq]Helvetica[rq]),
and its
monospaced family
C
([lq]Courier[rq]).
Historical inertia has driven
groff's
font identifiers to short uppercase abbreviations of font names,
as with
TR,
TB,
TI,
TBI,
and a special font
S.
The default family used with abstract styles can be changed at any time;
initially,
it
is~
T.
Typically,
abstract styles are arranged in the first four mounting positions in the
order shown above.
The default mounting position,
and therefore style,
is always
1
(
R).
By issuing appropriate formatter instructions,
you can override these defaults before your document writes its first
glyph.
Terminals cannot change font families and lack special fonts.
They support style changes by overstriking,
or by altering ISO~6429/:ECM-48
graphic renditions
(character cell attributes).
The
ft
request
and
[rs]f
escape sequence select a typeface by name,
abstract style,
or mounting position.
The
fam
request
and
[rs]F
escape sequence set the default font family.
The
ftr
request translates one font name to another;
fzoom
magnifies or reduces the typeface corresponding to a resolved one.
sty
and
fp
associate abstract styles and font names with mounting positions.
Characters and glyphs
A glyph is a graphical representation of a character.
Whereas a
character
is an abstraction of semantic information,
a
glyph
is an intelligible mark visible on screen or paper.
A character has many possible representation forms;
for example,
the character [lq]A[rq]
can be written in an upright or slanted typeface,
producing distinct glyphs.
Sometimes,
a sequence of characters map to a single glyph:@:
this is a
ligature[em]the most common is `fi'.
Space characters never become glyphs in
GNU
troff.
If not discarded
(as when trailing text lines),
horizontal motions represent them in the output.
The formatter supports three kinds of character.
An ordinary character
(see section [lq]Identifiers[rq] above)
is the most commonly used,
has no special syntax,
and typically represents itself.
(Depending on the breadth
of the output device's glyph repertoire,
the characters
[aq],
-,
[ha],
[ga],
and
[ti]
can be exceptions to this rule.
[dq]
and
[rs]
are not exceptions,
but because they are syntactically meaningful to the formatter,
access to their glyphs
may require use of special characters
(or changing or disabling the escape character).
See
Interpolate a
special character
with the
[lq]
[rs][xxx]
or
[lq]
[rs]C[aq]xxx[aq][rq]
escape sequence syntax,
where
xxx
is an identifier.
An
indexed character
bypasses most characte-t-glyph resolution logic,
uses the
[lq]
[rs]N[aq]i[aq]syntax,
and selects a glyph from the currently selected font
by its intege-valued position
i
in the output device's representation of that font.
(A device's fonts
do not necessarily arrange their glyphs
according to a standard character encoding.)
Use-defined characters
are similar to string definitions
(see section [lq]Strings[rq] above)
and permit extension of or substitution within the character repertoire.
Any ordinary,
special,
or indexed character can be use-defined.
The
char,
fchar,
schar,
and
fschar
requests create use-defined characters
employed at various stages of the characte-t-glyph resolution process.
In a
troff system,
a font description file
lists all of the glyphs a particular font provides.
If the user requests a glyph
not available in the currently selected font,
the formatter looks it up an ordered list of
special fonts.
By default,
the
[lq]
ps[rq]
(PostScript)
and
[lq]
pdf[rq]
output devices support the two special fonts
[lq]
SS[rq]
(slanted symbol)
and
[lq]
S[rq]
(symbol);
and these devices'
DESC
files arrange them such that the formatter searches
the former before the latter.
Other output devices use different names for special fonts.
Fonts mounted with the
fonts
keyword in the
DESC
file are globally available.
GNU
troff's
special
and
fspecial
requests alter the list of fonts treated as special on a general basis,
or only when a certain font is currently selected,
respectively.
GNU
troff employs the following procedure to resolve an input character
into a glyph.
Use-defined characters make this resolution process recursive.
The first step that succeeds ends the resolution procedure
for the character being formatted,
which may not be the last in the sequence interpolated
by a use-defined character.
- [bu]
-
Interpolate the definition of any character
defined by the
char
request
and apply this procedure to each character in its definition.
- [bu]
-
Check the current font for a glyph corresponding to the character.
- [bu]
-
Interpolate the definition of any use-defined character matching
defined by the
fchar
request
and apply this procedure to each character in its definition.
- [bu]
-
Check whether the current font has a fon-specific list of special
fonts;
if so,
check the each font therein,
in the order determined by the last applicable
fspecial
request,
for a glyph corresponding to the character.
- [bu]
-
Interpolate the definition of any character
defined by the
fschar
request for the currently selected font,
and apply this procedure to each character in its definition.
- [bu]
-
Check each font in the list configured by the most recently issued
special
request for a glyph corresponding to the character.
- [bu]
-
Interpolate the definition of any character
defined by the
sschar
request
and apply this procedure to each character in its definition.
- [bu]
-
Finally,
iterate through the list of mounted fonts by position.
For each mounted font,
if that font bears the
special
directive
(see
check it for a glyph corresponding to the character.
This stage of the resolution process
can sometimes lead to surprising
results since the
fonts
directive in the
DESC
file often contains empty positions that are filled
by a macro file or document employing the
fp
request
after the formatter initializes.
Special fonts
Special fonts are those that the formatter searches,
in mounting position order,
when it cannot find a requested glyph in the selected font.
Typically,
they are declared as such in their description files
(see
and
contain unstyled glyphs.
The [lq]Symbol[rq] and [lq]Zapf Dingbats[rq] fonts
of the PostScript and PDF standards are examples.
Ordinarily,
only typesetters have special fonts.
GNU
troff's
special
and
fspecial
requests permit a document
to supplement the set of fonts the device configures
for glyph search
without having to use
the
fp
request to manipulate the list of mounting positions,
which can be tedious[em]by default,
GNU
troff mounts 40 fonts at startup
when using the
ps
device.
Hyphenation
When filling,
groff
hyphenates words as needed at use-specified and automatically
determined hyphenation points.
Explicitly hyphenated words such as [lq]mothe-i-law[rq] are always
eligible for breaking after each of their hyphens.
The hyphenation
character~
[rs]%
and no-printing break
point~
[rs]:
escape sequences may be used to control the hyphenation and breaking of
individual words.
The
hw
request sets use-defined hyphenation points for specified words at any
subsequent occurrence.
Otherwise,
groff
determines hyphenation points automatically by default.
Several requests influence automatic hyphenation.
Because conventions vary,
a variety of hyphenation modes is available to the
hy
request;
these determine whether hyphenation will apply to a word prior to
breaking a line at the end of a page
(more or less;
see below for details),
and at which positions within that word automatically determined
hyphenation points are permissible.
The localization macro files loaded by
troffrc
configure a default hyphenation mode appropriate to the language.
- 0
-
disables hyphenation.
- 1
-
enables hyphenation except after the first and before the last character
of a word.
The remaining values [lq]imply[rq]
1;
that is,
they enable hyphenation under the same conditions as
[lq].hy 1[rq],
and then apply or lift restrictions relative to that basis.
- 2
-
disables hyphenation of the last word on a page or column,
even for explicitly hyphenated words.
(Hyphenation is prevented if the next page location trap is closer to
the vertical drawing position than the next text baseline would be.
See section [lq]Traps[rq] below.)
- 4
-
disables hyphenation before the last two characters of a word.
- 8
-
disables hyphenation after the first two characters of a word.
- 16
-
enables hyphenation before the last character of a word.
- 32
-
enables hyphenation after the first character of a word.
Apart from value~2,
restrictions imposed by the hyphenation mode are
not
respected for words whose hyphenations have been specified with the
hyphenation character
([lq][rs]%[rq]
by default)
or the
.hw
request.
Nonzero values are additive.
For example,
mode~12 causes
groff
to hyphenate neither the last two nor the first two characters of a
word.
Some values cannot be used together because they contradict;
for instance,
values 4 and~16,
and values 8 and~32.
As noted,
it is superfluous to add~1 to any no-zero even mode.
The places within a word that are eligible for hyphenation are
determined by languag-specific data
(hla,
hpf,
and
hpfa)
and lettercase relationships
(hcode
and
hpfcode).
Furthermore,
hyphenation of a word might be suppressed due to a limit on
consecutive hyphenated lines
(hlm),
a minimum line length threshold
(hym),
or because the line can instead be adjusted with additional inte-word
space
(hys).
Localization
GNU
troff ties the set of hyphenation patterns
to the hyphenation language code
selected by the
hla
request.
The
hpf
request is usually invoked by a localization file loaded by the
troffrc
file.
groff
provides localization files for several languages;
See subsection [lq]Localization packages[rq] of
For Western languages,
the localization file
sets the default hyphenation mode
and loads hyphenation patterns and exceptions.
By default,
troffrc
loads the localization file for English.
Writing macros
The
.de
request defines a macro named for its argument.
If that name already exists as an alias,
the target of the alias is redefined;
see section [lq]Strings[rq] above.
troff
enters [lq]copy mode[rq]
(see below),
storing subsequent input lines as the definition.
If the optional second argument is not specified,
the definition ends with the control line
[lq]
..[rq]
(two dots).
Tabs and spaces are permitted between the dots.
Alternatively,
a second argument to
.de
names a macro whose call
(or request whose invocation)
syntax ends the definition;
this
end macro
is then interpreted normally.
Spaces or tabs are permitted after the first control character in the
line containing this ending token,
but a tab immediately after the token prevents its recognition as the
end of a macro definition.
Macro definitions can be nested if they use distinct end macros or if
their ending tokens are sufficiently escaped.
An end macro need not be defined until it is called.
This fact enables a nested macro definition to begin inside one macro
and end inside another.
Variants of
.de
disable compatibility mode and/or indirect the names of the macros
specified for definition or termination:
these are
.de1,
.dei,
and
.dei1.
Append to macro definitions with
.am,
.am1,
.ami,
and
.ami1.
The
.als,
.rm,
and
.rn
requests create an alias of,
remove,
and rename a macro,
respectively.
.return
stops the execution of a macro immediately,
returning to the enclosing context.
Parameters
Macro call and string interpolation parameters can be accessed using
escape sequences starting with
[lq]
[rs]$[rq].
The
[rs]n[.$]
rea-only register stores the count of parameters available to a macro
or string;
change its value with the
.shift
request,
which dequeues parameters from the current list.
The
[rs]$0
escape sequence interpolates the name by which a macro was called.
Applying string interpolation to a macro does not change this name.
Copy mode
GNU
troff processes certain requests in
copy mode:
it copies ordinary,
special,
and indexed characters a-is;
interpolates the escape sequences
[rs]n,
[rs]g,
[rs]$,
[rs]*,
[rs]V,
and
[rs]?
normally;
discards comments
[rs]
and
[rs]#;
interpolates
[rs]a,
[rs]e,
and
[rs]t,
as the current
leader,
escape,
or
tab
character with
respectively;
represents
[rs]newline,
[rs]&,
[rs]_,
[rs]|,
[rs][ha],
[rs]{,
[rs]},
[rs][ga],
[rs][aq],
[rs]-,
[rs]!,
[rs]c,
[rs]%,
[rs]space,
[rs]E,
[rs]),
[rs][ti],
and
[rs]:
in an encoded form,
and copies other escape sequences a-is.
The term [lq]copy mode[rq] reflects its most visible application
in requests that populate macros and strings,
but other requests also use it when interpreting arguments
that can't meaningfully represent typesetting operations.
For example,
a font selection escape sequence has no meaning
in a hyphenation pattern file name
(
hpf)
or a diagnostic message written to the terminal
(
tm).
The complement of copy mode[em]a
roff
formatter's behavior when not defining or appending to a macro,
string,
or diversion[em]where all macros are interpolated,
requests invoked,
and valid escape sequences processed immediately upon recognition,
can be termed
interpretation mode.
The escape character
(
[rs]
by default)
when used before itself
quotes
an escape character for later interpretation
in an enclosing context.
Escape character quotation enables you to control
whether the formatter interprets a given
[rs]n,
[rs]g,
[rs]$,
[rs]*,
[rs]V,
or
[rs]?
escape sequence at the time the macro containing it is defined,
or later when the macro is called.
You can think of
[rs][rs]
as a [lq]delayed[rq] backslash;
it is the escape character followed by a backslash from which the escape
character has removed its special meaning.
Consequently,
[rs][rs]
is not best considered an escape sequence,
but a quoted escape character.
In any escape sequence
[rs]X
that
troff
does not recognize,
the formatter discards the escape character and outputs
X.
An unrecognized escape sequence causes a warning in category
[lq]
escape[rq],
with two exceptions,
[rs][rs]
being one.
The other is
[rs].,
which quotes the control character.
It is used to permit nested macro definitions to end
without a named macro call to conclude them.
Without a syntax for quoting the control character,
this would not be possible.
Outside of copy mode,
roff
documents should not use the
[rs][rs]
or
[rs].
character sequences;
they serve only to obfuscate the input.
Use
[rs]e
to represent the escape character,
[rs][rs]
to obtain a backslash glyph,
and
[rs]&
before
.
and
[aq]
where
troff
expects them as control characters
if you mean to use them literally.
Macro definitions can be nested to arbitrary depth.
Given the input character sequence
[lq]
[rs][rs][rq]
in a macro or string definition,
the formatter interprets each escape character in multiple contexts;
once,
when populating the macro or string,
where the first
[lq]
[rs][rq]
serves its quotation function[em]thus
only one
[lq]
[rs][rq]
is stored in the definition.
(Verify this fact with the
pm
request.)
The formatter interprets the second
[lq]
[rs][rq]
as an escape character
(assuming the escape character hasn't been changed in the meantime)
each time it interpolates the macro or string definition.
This fact leads to exponential growth
in the quantity of escape characters
required to quote and thereby delay interpolation of
[rs]n,
[rs]g,
[rs]$,
[rs]*,
[rs]V,
and
[rs]?
at each nesting level.
An alternative is to use
[rs]E,
which represents an escape character that is not interpreted in copy
mode.
Because
[rs].
is not a true escape sequence,
we can't use
[rs]E
to keep
[lq]
..[rq]
from ending a macro definition prematurely.
If the multiplicity of backslashes complicates maintenance,
use end macros.
Traps
Traps
are locations in the output,
or conditions on the input that,
when reached or fulfilled,
call a specified macro.
A
vertical position trap
calls a macro when the formatter's vertical drawing position reaches or
passes,
in the downward direction,
a certain location on the output page or in a diversion.
Its applications include setting page headers and footers,
body text in multiple columns,
and footnotes.
These traps can occur at a given location either on the page
(
wh,~
ch)
or in the current diversion
(
dt)[em]together,
these are known as
vertical position traps,
which can be disabled and re[e ad]nabled
(
vpt).
A diversion is not formatted in the context of a page,
so it lacks page location traps;
instead it can have a
diversion trap.
There can exist at most one such vertical position trap per diversion.
Other kinds of trap can be planted
at a blank line
(
blm);
at a line with leading space characters
(
lsm);
after a certain number of productive input lines
(
it,~
itc);
or at the end of input
(
em).
Setting a trap is also called
planting
one.
It is said that a trap is
sprung
if its condition is fulfilled.
The formatter passes no arguments to macros called by traps.
Registers associated with trap management include
vertical position trap enablement status
(
[rs]n[.vpt]),
distance to the next trap
(
[rs]n[.t]),
and the name of that trap
(
[rs]n[.trap]);
the count of lines remaining in the pending input trap
(
[rs]n[.it]),
the name of the macro associated with it
(
[rs]n[.itm]),
and whether that input trap honors the
[rs]c
output line continuation escape sequence
(
[rs]n[.itc]);
amount of needed
(
.ne-requested)
space that caused the most recent vertical position trap to be sprung
(
[rs]n[.ne]),
amount of needed space truncated from the amount requested
(
[rs]n[.trunc]);
page ejection status
(
[rs]n[.pe]);
and
leading space count
(
[rs]n[lsn])
with its corresponding amount of motion
(
[rs]n[lss]).
Page location traps
A
page location trap
is a vertical position trap that applies to the page;
that is,
to the to-level diversion.
Many can be present;
manage them with the
wh
and
ch
requests.
No-negative page locations given to these requests set the trap
relative to the top of the page;
negative values set the trap relative to the bottom of the page.
It is not possible to plant a trap less than one basic unit from the
page bottom:
a location of [lq]-0[rq] is interpreted as [lq]0[rq],
the top of the page.
An existing
visible
trap
(see below)
at the same location is removed;
this is
wh's
sole function if its second argument is missing.
A trap is sprung only if it is
visible,
meaning that its location is reachable on the page and it is not hidden
by another trap at the same location already planted there.
(A trap planted at [lq]20i[rq] or [lq]-30i[rq] will not be sprung
on a page of length [lq]11i[rq].)
A trap above the top or at or below the bottom of the page
can be made visible
by either moving it into the page area
or increasing the page length so that the trap is on the page.
A negative trap value always uses the
current
page length;
the formatter does not convert it to an absolute vertical position.
We can use the
pwh
request to dump page location traps to the standard error stream;
see section [lq]Debugging[rq] below.
GNU
troff reports their positions in basic units,
and includes 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.
The implicit page trap
An
implicit page trap
always exists in the to-level diversion
(see below);
its purpose is to eject the current page and start the next one.
It works like a trap in some ways but not others.
It has no name,
so it cannot be moved or deleted with
wh
or
ch
requests.
You cannot hide it by placing another trap at its location,
and can move it only by redefining the page length with
pl.
Its operation is suppressed when vertical page traps are disabled with
GNU
troff's vpt
request.
Diversions
In
roff
systems it is possible to format text as if for output,
but instead of writing it immediately,
one can
divert
the formatted text into a named storage area.
It is retrieved later by specifying its name after a control character.
The formatter uses the same name space for such
diversions
as for strings and macros;
see section [lq]Identifiers[rq] above.
Such text is sometimes said to be [lq]stored in a macro[rq],
but this coinage obscures the important distinction
between macros and strings on one hand
and diversions on the other;
the former store
unformatted
input text,
and the latter capture
formatted
output.
Diversions also do not interpret arguments.
Applications of diversions include
footnotes,
tables of contents,
indices,
and [lq]keeps[rq]
(preventing a page break from occurring at an inconvenient place
by forcing a set of output lines to be set as a group).
For orthogonality it is said that GNU
troff populates the
to-level diversion
if no diversion is active
(that is,
formatted output is being [lq]diverted[rq] directly
to the output device).
The to-level diversion has no name.
Dereferencing an undefined diversion creates an empty one of that name.
(GNU
troff also emits a warning in category
[lq]mac[rq];
see section [lq]Warnings[rq] of
A diversion does not exist for the purpose of testing with the
d
conditional expression operator
until its initial definition ends;
see subsection [lq]Conditional expressions[rq] above.
The
di
request creates a diversion,
including any partially collected line.
da
appends to a diversion,
creating one if it does not already exist.
If the diversion's name already exists as an alias,
the target of the alias is replaced or appended to;
see section [lq]Strings[rq] above.
The pending output line is diverted as well.
Switching to another environment
(with the
ev
request)
before invoking
di
or
da
avoids including any pending output line in the diversion.
(See section [lq]Environments[[rq] below.)
Invoking
di
or
da
without an argument stops diverting output
to the diversion named by the most recent corresponding request.
Invoking
di
or
da
without an argument
when no diversion is being populated does nothing.
(GNU
troff emits a warning in category
[lq]di[rq];
see section [lq]Warnings[rq] of
box
and
boxa
work similarly,
but ignore partially collected lines.
Call any of these macros again without an argument to end the diversion.
Diversion requests can be nested.
The registers
.d
and
.z
report information about the current diversion,
and
dn
and
dl
about the most recently closed one.
.h
is meaningful in diversions,
including the to-level one.
After output to a (named) diversion stops,
the formatter stores its vertical and horizontal sizes,
to the writable registers
dn
and
dl,
respectively.
Only the lines just processed are counted:
for the computation of
dn
and
dl,
the requests
da
and
boxa
are handled as if
di
and
box
had been used,
respectively[em]lines that have been already stored in the diversion
(box) are not taken into account.
The
[rs]!
and
[rs]?
escape sequences and
output
request escape from a diversion,
the first two to the enclosing level and the last to the top level.
This facility is termed
transparent embedding.
The
asciify
and
[lq]
unformat[rq]
requests reprocess diversions.
Punning names
Macros,
strings,
and diversions share a name space;
see section [lq]Identifiers[rq] above.
Internally,
the same mechanism is used to store them.
You can thus call a macro with string interpolation syntax and vice
versa.
Interpolating a string does not hide existing macro arguments.
Place the sequence
[rs][rs]
at the end of a line in a macro definition or,
within a macro definition,
immediately after the interpolation of a macro as a string,
to suppress the effect of a newline.
Environments
Environments store most of the parameters that control text processing.
A default environment named
[lq]
0[rq]
(zero)
exists when
exists when the formatter starts up;
formattin-related requests and escape sequences modify its properties.
You can create new environments and switch among them.
Only one is current at any given time.
Active environments are managed using a
stack,
a data structure supporting [lq]push[rq] and [lq]pop[rq] operations.
The current environment is at the top of the stack.
The same environment name can be pushed onto the stack multiple times,
possibly interleaved with others.
Popping the environment stack does not destroy the current environment;
it remains accessible by name and can be made current again
by pushing it at any time.
Environments cannot be renamed or deleted,
and can only be modified when current.
To inspect the environment stack,
use the
pev
request;
see section [lq]Debugging[rq] below.
Environments store the following information.
- [bu]
-
a partially collected line, if any
- [bu]
-
data about the most recently output glyph and line
(registers
.cdp,
.cht,
.csk,
.n,
.w)
- [bu]
-
typeface parameters
(size,
family,
style,
height and slant,
inte-word and inte-sentence space sizes)
- [bu]
-
page parameters
(line length,
title length,
vertical spacing,
line spacing,
indentation,
line numbering,
centering,
righ-alignment,
underlining,
hyphenation parameters)
- [bu]
-
filling enablement;
adjustment enablement and mode
- [bu]
-
tab stops;
tab,
leader,
escape,
control,
n-break control,
hyphenation,
and
margin characters
- [bu]
-
input line traps
- [bu]
-
stroke and fill colors
The
ev
request
(with an argument)
pushes to
and
(without)
pops from the environment stack,
while
evc
copies a named environment's parameters to the current one.
Postprocessor access
Beyond the
cf
and
trf
requests,
two escape sequences and two requests enable documents
to pass information directly to a postprocessor.
These are useful for exercising devic-specific capabilities that the
groff
language does not abstract or generalize;
examples include the embedding of hyperlinks and image files.
Devic-specific functions are documented
in each output driver's man page,
such as
or
The
[lq]
device[rq]
request and
[rs]X
escape sequence embed their arguments into GNU
troff output as parameters to an
[lq]
x X[rq]
device extension command
(see
The interpretation of such parameters is determined by the output driver
or other postprocessor.
GNU
troff also permits the interpolation of macro or string contents
as a device extension command.
The
devicem
request and
[rs]Y
escape sequence correspond to
[lq]
.device [rs]*[name][rq]
and
[lq]
[rs]X[aq][rs]*[name][rq],
respectively.
They differ from their counterparts
in that GNU
troff does not interpret the contents of the string or macro
name;
further,
name
may be a macro and thus contain newlines.
(There is no way to embed a newline in the arguments to
[lq]
device[rq]
or
[rs]X.)
The inclusion of newlines requires an extension to the AT&T
troff devic-independent page description language,
and their presence confuses drivers that do not know about it
(see subsection [lq]Device control commands[rq] of
Use of device extension commands early in a document
(before the first text is formatted)
can interfere with processing of page location traps.
If you experience problems when placing them early,
precede the first with a dummy character escape sequence
[lq]
[rs]&[rq];
recall section [lq]Dummy Characters[rq] above.
The
tag
and
taga
requests are reserved for internal use.
Underlining
In
RUNOFF
(see
underlining,
even of lengthy passages,
was straightforward because only fixe-pitch printing devices were
targeted.
Typesetter output posed a greater challenge.
There exists a
groff
request
.ul
(see above)
that underlines subsequent source lines on terminals,
but on typesetters,
it selects an italic font style instead.
The
ms
macro package
(see
offers a macro
.UL,
but it too produces the desired effect only on typesetters,
and has other limitations.
One could adapt
ms's
approach to the construction of a macro as follows.
-
.de UNDERLINE
. ie n [rs][rs]$1[rs]f[I][rs][rs]$2[rs]f[P][rs][rs]$3
. el [rs][rs]$1[rs]Z[aq][rs][rs]$2[aq][rs]v[aq].25m[aq][rs]D[aq]l [rs]w[aq][rs][rs]$2[aq]u 0[aq][rs]v[aq]-.25m[aq][rs][rs]$3
..
If
makes trouble, change the macro name
UNDERLINE
into some -letter word, like
Ul.
Moreover,
change the form of the font selection escape sequence from
[rs]f[P]
to
[rs]fP.
Underlining without macro definitions
If one does not want to use macro definitions,
e.g.,
when
doclifter
gets lost,
use the following.
-
.ds u1 before
.ds u2 in
.ds u3 after
.ie n [rs]*[u1][rs]f[I][rs]*[u2][rs]f[P][rs]*[u3]
.el [rs]*[u1][rs]Z[aq][rs]*[u2][aq][rs]v[aq].25m[aq][rs]D[aq]l [rs]w[aq][rs]*[u2][aq]u 0[aq][rs]v[aq]-.25m[aq][rs]*[u3]
When using
doclifter,
it might be necessary to change syntax forms such as
[xy]
and
*[xy]
to those supported by AT&T
troff:
*(xy
and
(xy,
and so on.
Then these lines could look like
-
.ds u1 before
.ds u2 in
.ds u3 after
.ie n [rs]*[u1][rs]fI[rs]*(u2[rs]fP[rs]*(u3
.el [rs]*(u1[rs]Z[aq][rs]*(u2[aq][rs]v[aq].25m[aq][rs]D[aq]l [rs]w[aq][rs]*(u2[aq]u 0[aq][rs]v[aq]-.25m[aq][rs]*(u3
The result looks like
-
before
[ul]i[ul]n
after
Underlining by overstriking with [rs](ul
The
[rs]z
escape sequence writes a glyph without advancing the
drawing position,
enabling overstriking.
Thus,
[rs]zc[rs](ul
formats
c
with an underrule glyph on top of it.
Video terminals implement the underrule by setting a character cell's
underline attribute,
so this technique works in both
nroff and
troff modes.
Long words may then look intimidating in the input;
a clarifying approach might be to use the input line continuation escape
sequence
[rs]newline
to place each underlined character on its own input line.
Thus,
-
.nf
[rs]&[rs]fB: ${[rs]fIvar[rs]fR[rs]c
[rs]zo[rs](ul[rs]
[rs]zp[rs](ul[rs]c
[rs]&[rs]fIvalue[rs]fB}
.fi
produces
-
: ${var__value}
as output.
Compatibility mode
documents differences between the
roff
language recognized by
GNU
troff and that of
AT&T
troff,
as well as the device,
font,
and devic-independent page description formats described by
CSTR~#54.
GNU
troff provides an
AT&T
troff compatibility mode.
The
request and registers
.C
and
.cp
set and test the enablement of this mode.
Debugging
Preprocessors use the
lf
request to preserve the identities of line numbers and names of input
files.
groff
emits a variety of error diagnostics and supports several categories of
warning;
the output of these can be selectively suppressed with
[lq]
warn[rq]
(and see the
-E,
-w,
and
-W
options of
A trace of the formatter's input processing stack can be emitted when
errors or warnings occur by means of
-b
option,
or produced on demand with the
request.
tm,
tmc,
and
tm1
can be used to emit customized diagnostic messages or for
instrumentation while troubleshooting.
ex
and
ab
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[em]macros,
strings,
and
diversions[em](
pm);
characters
(
pchar; experimental);
colors
(
pcolor);
composite character mappings
(
pcomposite);
environments
(
pev);
occupied font mounting positions
(
pfp);
font translations
(
pftr);
automatic hyphenation codes
(
pchar)
and exceptions
(
phw);
registers
(
pnr);
open streams
(
pstream);
and
page location traps
(
pwh).
Requests can also disclose
to the standard error stream
the internal properties and representations of
characters and classes
(
pchar),
macros
(and strings and diversions)
(
pm),
and the list of output nodes corresponding to the pending input line
(
pline).
Authors
This document was written by
Trent A. Fisher,
Werner Lemberg
and
G. Branden Robinson
Section [lq]Underlining[rq] was primarily written by
Bernd Warken
See also
Groff: The GNU Implementation of troff,
by Trent A. Fisher and Werner Lemberg,
is the primary
groff
manual.
You can browse it interactively with [lq]info groff[rq].
[lq]Troff User's Manual[rq]
by Joseph F. Ossanna,
1976
(revised by Brian W. Kernighan,
1992),
AT&T Bell Laboratories Computing Science Technical Report No. 54,
widely called simply [lq]CSTR~#54[rq],
documents the language,
device and font description file formats,
and devic-independent page description language
referred to collectively in
groff
documentation as
[lq]AT&T~
troff[rq].
[lq]A Typesette-independent TROFF[rq]
by Brian W. Kernighan,
1982,
AT&T Bell Laboratories Computing Science Technical Report No. 97
(CSTR~#97),
provides additional insights into the
device and font description file formats
and devic-independent page description language.
-
-
is the preferred interface to the
groff
system;
it manages the pipeline that carries a source document through
preprocessors,
the
troff
formatter,
and an output driver to viewable or printable form.
It also exhaustively lists the man pages provided with the GNU
roff
system.
-
-
discusses character encoding issues
and escape sequences that produce glyphs.
-
-
covers differences between the
GNU
troff formatter,
its device and font description file formats,
its devic-independent page description language,
and those of AT&T
troff.
-
-
describes the formats of the files that describe devices
(DESC)
and fonts.
-
-
surveys macro packages provided with
groff,
describes how documents can take advantage of them,
offers guidance on writing macro packages and using diversions,
and includes historical information.
-
-
presents a detailed history of
roff
systems and summarizes concepts common to them.
Index
- Name
-
- Description
-
- Input format
-
- Syntax characters
-
- Sentences
-
- Tabs and leaders
-
- Line continuation
-
- Colors
-
- Measurements
-
- Motion quanta
-
- Default units
-
- Numeric expressions
-
- Identifiers
-
- Control characters
-
- Invoking requests
-
- Calling macros
-
- Using escape sequences
-
- Delimiters
-
- Dummy characters
-
- Page control
-
- Control structures
-
- Conditional expressions
-
- Syntax reference conventions
-
- Request short reference
-
- Escape sequence short reference
-
- Drawing commands
-
- Strings
-
- Registers
-
- Read-only registers
-
- Writable predefined registers
-
- Using fonts
-
- Characters and glyphs
-
- Special fonts
-
- Hyphenation
-
- Localization
-
- Writing macros
-
- Parameters
-
- Copy mode
-
- Traps
-
- Page location traps
-
- The implicit page trap
-
- Diversions
-
- Punning names
-
- Environments
-
- Postprocessor access
-
- Underlining
-
- Underlining without macro definitions
-
- Underlining by overstriking with [rs](ul
-
- Compatibility mode
-
- Debugging
-
- Authors
-
- See also
-
|
|
- Running on 
-
:
