'\" e
.TH groff_diff 7 "13 September 2023" "groff 1.23.0"
.SH Name
groff_diff \- differences between GNU
.I roff
and AT&T
.I troff
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
.\"
.\" This file is part of groff, the GNU roff type-setting system.
.\"
.\" Permission is granted to copy, distribute and/or modify this
.\" document under the terms of the GNU Free Documentation License,
.\" Version 1.3 or any later version published by the Free Software
.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
.\" and with no Back-Cover Texts.
.\"
.\" A copy of the Free Documentation License is included as a file
.\" called FDL in the main directory of the groff source package.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_groff_diff_7_man_C \n[.cp]
.cp 0
.
.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.nr do-fallback 0
.if !\n(.f           .nr do-fallback 1 \" mandoc
.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
.if \n[do-fallback]  \{\
.  de MR
.    ie \\n(.$=1 \
.      I \%\\$1
.    el \
.      IR \%\\$1 (\\$2)\\$3
.  .
.\}
.rr do-fallback
.
.
.\" ====================================================================
.\" Local definitions
.\" ====================================================================
.
.\" define a string tx for the TeX logo
.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
.el   .ds tx TeX
.
.
.\" from old groff_out.man
.ie \n(.g \
.  ds ic \/
.el \
.  ds ic \^
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
The GNU
.I roff
text processing system,
.IR groff ,
is an extension of AT&T
.IR troff , \" AT&T
the typesetting system originating in Unix systems of the 1970s.
.
.I groff
removes many arbitrary limitations and adds features,
both to the input language and to the page description language output
by the
.I troff \" generic
formatter.
.
Differences arising from
.IR groff 's
implementation of AT&T
.I troff \" AT&T
features are also noted.
.
See
.MR roff 7
for background.
.
.
.\" ====================================================================
.SH Language
.\" ====================================================================
.
GNU
.I troff \" GNU
features identifiers of arbitrary length;
supports color output,
non-integral type sizes,
and user-defined characters;
adds more conditional expression operators;
recognizes additional scaling units and numeric operators;
enables general file I/O
(in \[lq]unsafe mode\[rq] only);
and exposes more formatter state.
.
.
.\" ====================================================================
.SS "Long names"
.\" ====================================================================
.
GNU
.I troff \" GNU
introduces many new requests;
with three exceptions
.RB ( cp ,
.BR do ,
.BR rj ),
they have names longer than two characters.
.
The names of registers,
fonts,
strings/\:macros/\:diversions,
environments,
special characters,
streams,
and colors can be of any length.
.
Anywhere AT&T
.I troff \" AT&T
supports a parameterized escape sequence that uses an opening
parenthesis \[lq](\[rq] to introduce a two-character argument,
.I groff
supports a square-bracketed form \[lq][]\[rq] where the argument
within can be of arbitrary length.
.
.
.\" ====================================================================
.SS "Font families, abstract styles, and translation"
.\" ====================================================================
.
GNU
.I troff \" GNU
can group text typefaces into
.I families
containing each of the styles
.RB \[lq] R \[rq],
.RB \[lq] I \[rq],
.RB \[lq] B \[rq],
and
.RB \[lq] BI \[rq].
.
So that a document need not be coupled to a specific font family,
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
.I "resolved font name."
.
A document can
.I translate,
or remap,
fonts with the
.B ftr
request.
.
.
.P
Applying the requests
.BR cs ,
.BR bd ,
.BR tkf ,
.BR uf ,
or
.B \%fspecial
to an abstract style affects the member of the default family
corresponding to that style.
.
The default family can be set with the
.B fam
request or
.B \-f
command-line option.
.
The
.B styles
directive in the output device's
.I DESC
file controls which mounting positions
(if any)
are initially associated with abstract styles rather than fonts,
and the
.B sty
request can update this association.
.
.
.\" ====================================================================
.SS Colors
.\" ====================================================================
.
.I 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
.I stroke color,
with which glyphs,
rules (lines),
and geometric figures are drawn,
and the
.I fill color,
which paints the interior of filled geometric figures.
.
The
.BR color ,
.BR \%defcolor ,
.BR gcolor ,
and
.B fcolor
requests;
.B \[rs]m
and
.B \[rs]M
escape sequences;
and
.BR .color ,
.BR .m ,
and
.B .M
registers exercise color support.
.
.
.\" ====================================================================
.SS "Fractional type sizes and new scaling units"
.\" ====================================================================
.
.\" BEGIN Keep (roughly) parallel with groff.texi node "Using Fractional
.\" Type Sizes".
AT&T
.I troff \" AT&T
interpreted all type size measurements in points.
.
Combined with integer arithmetic,
this design choice made it impossible to support,
for instance,
ten and a half-point type.
.
In GNU
.IR troff , \" GNU
an output device can select a scaling factor that subdivides a point
into \[lq]scaled points\[rq].
.
A type size expressed in scaled points can thus represent a non-integral
type size.
.
.
.P
A
.I scaled point
is equal to
.RI 1/ sizescale
points,
where
.I sizescale
is specified in the device description file,
.IR DESC ,
and defaults to\~1;
see
.MR groff_font 5 .
.
Requests and escape sequences in GNU
.I troff \" GNU
interpret arguments that represent a type size in points,
which the formatter multiplies by
.I sizescale
and converts to an integer.
.
Arguments treated in this way comprise those to the escape sequences
.B \[rs]H
and
.BR \[rs]s ,
to the request
.BR ps ,
the third argument to the
.B cs
request,
and the second and fourth arguments to the
.B tkf
request.
.
Scaled points may be specified explicitly with the
.B z
scaling unit.
.
In GNU
.IR troff , \" GNU
the register
.B \[rs]n[.s]
can interpolate a non-integral type size.
.
The register
.B \[rs]n[.ps]
interpolates the type size in scaled points.
.
.
.P
For example,
if
.I sizescale
is\~1000,
then a scaled point is one thousandth of a point.
.
Consequently,
.RB \[lq] ".ps 10.5" \[rq]
is synonymous with
.RB \[lq] ".ps 10.5z" \[rq];
both set the type size to 10,500\~scaled points,
or 10.5\~points.
.
.
.P
It makes no sense to use the
.RB \[lq] z \[rq]\~scaling
unit in a numeric expression whose default scaling unit is neither
.RB \[lq] u \[rq]
.RB nor\~\[lq] z \[rq],
so GNU
.I troff \" GNU
disallows this.
.
Similarly,
it is nonsensical to use a scaling unit other
.RB than\~\[lq] z \[rq]
.RB or\~\[lq] u \[rq]
in a numeric expression whose default scaling unit
.RB is\~\[lq] z \[rq],
so GNU
.I troff
disallows this as well.
.
.
.br
.ne 2v
.P
Another new scaling unit,
.RB \[lq] s \[rq],
multiplies by the number of basic units in a scaled point.
.
Thus,
.RB \[lq]\^ \[rs]n[.ps]s \[rq]
is equal to
.RB \[lq] 1m \[rq]
by definition.
.
Do not confuse the
.RB \[lq] s \[rq]
and
.RB \[lq] z \[rq]
scaling units.
.
.
.br
.ne 2v
.P
Output devices may be limited in the type sizes they can employ.
.
The
.B .s
and
.B .ps
registers represent the type size as selected by the output driver as it
understands a device's capability.
.
The last
.I requested
type size is interpolated in scaled points by the read-only register
.B .psr
and in points as a decimal fraction by the read-only string-valued
register
.BR .sr .
.
Both are associated with the environment.
.
For example,
if a type size of 10.95\~points is requested,
and the nearest size permitted by a
.B sizes
request
(or by the
.B sizes
or
.B \%sizescale
directives in the device's
.I DESC
file)
is 11\~points,
the output driver uses the latter value.
.\" END Keep (roughly) parallel with groff.texi node "Using Fractional
.\" Type Sizes".
.
.
.P
A further two new measurement units available in
.I groff
are
.RB \[lq] M \[rq],
which indicates hundredths of an em,
and
.RB \[lq] f \^\[rq],
which multiplies by 65,536.
.
The latter provides convenient fractions for color definitions with the
.B \%defcolor
request.
.
For example,
0.5f equals 32768u.
.
.
.\" ====================================================================
.SS "Numeric expressions"
.\" ====================================================================
.
GNU
.I troff \" GNU
permits spaces in a numeric expression within parentheses,
and offers three new operators.
.
.
.TP
.IB e1 >? e2
Interpolate the greater of
.I e1
and
.IR e2 .
.
.
.TP
.IB e1 <? e2
Interpolate the lesser of
.I e1
and
.IR e2 .
.
.
.TP
.BI ( c ; e )
Evaluate
.I e
using
.I c
as the default scaling unit,
ignoring scaling units in
.I e
if
.I c
is empty.
.
.
.\" ====================================================================
.SS "Conditional expressions"
.\" ====================================================================
.
More conditions can be tested with the
.RB \[lq]\| if \|\[rq]
and
.B ie
requests,
as well as the new
.RB \[lq] while \[rq]
request.
.
.
.TP
.BI c\~ chr
True if a character
.I chr
is available,
where
.I chr
is an ordinary character
(Unicode basic Latin excluding control characters and the space),
a special character,
or
.BI \[rs]N\[aq] index\c
.BR \[aq] .
.
.
.TP
.BI d\~ nam
True if a string,
macro,
diversion,
or request
.I nam
is defined.
.
.
.TP
.BI F\~ fnt
True if a font
.I fnt
is available;
.I fnt
can be an abstract style
or a font name.
.
.I fnt
is handled as if it
were accessed with the
.B ft
request
(that is,
abstract styles and font translation are applied),
but
.I fnt
cannot be a mounting position,
and no font is mounted.
.
.
.TP
.BI m\~ col
True if a color
.I col
is defined.
.
.
.TP
.BI r\~ reg
True if a register
.I reg
is defined.
.
.
.TP
.BI S\~ sty
True if a style
.I sty
is registered.
.
Font translation applies.
.
.
.TP
.B v
Always false.
.
This condition is for compatibility with certain other
.I troff
implementations only.
.
(This refers to
.IR vtroff ,
a translator that would convert the C/A/T output from early-vintage AT&T
.I troff \" AT&T
to a form suitable for Versatec and Benson-Varian plotters.)
.
.
.\" ====================================================================
.SS "Drawing commands"
.\" ====================================================================
.
GNU
.I troff \" GNU
offers drawing commands to create filled
circles and ellipses,
and polygons.
.\" CSTR #54 did not countenance polygons, but DWB 3.3 had outlined ones
.\" as \D'p' as we do.  Filled polygons appear to be a GNU innovation.
.
Stroked (outlined) objects are drawn with the stroke color and
filled (solid) ones shaded with the fill color.
.
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 a stroked one because the former
is drawn only within its defined area,
whereas strokes have a line thickness
(set with another new drawing command,
.BR \[rs]D\[aq]t\[aq] ).
.
.
.\" ====================================================================
.SS "Escape sequences"
.\" ====================================================================
.
.\" TODO: Some of the synopses here and in "New requests" get pretty
.\" discursive.  It would be better to lift the introduction of new
.\" concepts in groff programming to new subsections above.  Examples
.\" include: string parameterization, user-definable characters,
.\" character properties (cflags), character classes; the hyphenation
.\" language, code, and pattern file system; file stream manipulation...
.\"
.\" _Maybe_ output suppression.  It's a big enough concept, but only
.\" well understood by retired contributors, only used by the grohtml
.\" output driver (still beta after 20 years), and we have some Savannah
.\" tickets that point the way to radically simplifying its design,
.\" eliminating its need to groff before you groff.
.I groff
introduces several new escape sequences
and extends the syntax of a few AT&T
.I troff \" AT&T
escape sequences
(namely,
.BR \[rs]D ,
.BR \[rs]f ,
.BR \[rs]k ,
.BR \[rs]n ,
.BR \[rs]s ,
.BR \[rs]$ ,
and
.BR \[rs]* ).
.
In the following list,
escape sequences are collated alphabetically at first,
and then by symbol roughly in Unicode code point order.
.\" Exceptions are made to group closely-related escape sequences in an
.\" order more agreeable to the development of a topic.
.
.
.TP 7.5 \" sinfully obtain better pagination on typesetters
.BI \[rs]A\[aq] anything \[aq]
Interpolate 1 if
.I anything
is a valid identifier,
and\~0 otherwise.
.
Because invalid input characters are removed,
invalid identifiers are empty or contain spaces,
tabs,
or newlines.
.
You can employ
.B \[rs]A
to validate a macro argument before using it to construct another escape
sequence or identifier.
.
.TP
.BI \[rs]B\[aq] anything \[aq]
Interpolate 1 if
.I anything
is a valid numeric expression,
and\~0 otherwise.
.
You might use
.B \[rs]B
along with the
.RB \[lq]\| if \|\[rq]
request to filter out invalid macro arguments.
.
.
.TP
.BI \[rs]D\[aq]C\~ "d" \[aq]
Draw filled circle of diameter
.I d
with its leftmost point at the drawing position.
.
.
.TP
.BI \[rs]D\[aq]E\~ "h v" \[aq]
Draw filled ellipse with
.I h
and
.I v
as the axes and the leftmost point at the drawing position.
.
.
.TP
.BI \[rs]D\[aq]p\~ "h1 v1"\~\c
.RI .\|.\|.\~ "hn vn"\c
.B \[aq]
Draw polygon with vertices at drawing position and each point
in sequence.
.
GNU
.I troff \" GNU
closes the polygon by drawing a line from
.RI ( hn ,\~ vn )
back to the initial drawing position;
DWB and Heirloom
.IR troff s \" DWB, Heirloom
do not.
.
.\" XXX: This would be the "STUPID_DRAWING_POSITIONING" complained of in
.\" src/libs/libdriver/input.cpp.  It is neither the rightmost point
.\" of the figure nor the initial drawing position that GNU troff
.\" automatically returned to to close the figure.
Afterward,
the drawing position is left at
.RI ( hn ,\~ vn ).
.
.
.TP
.BI \[rs]D\[aq]P\~ "h1 v1"\~\c
.RI .\|.\|.\~ "hn vn"\c
.B \[aq]
As
.BR \[rs]D\[aq]p\[aq] ,
but the polygon is filled.
.
.
.TP
.BI \[rs]D\[aq]t\~ "n" \[aq]
Set line thickness of geometric objects to
.RI to\~ n
basic units.
.
A zero
.I n
selects the minimal supported thickness.
.
A negative
.I n
selects a thickness proportional to the type size;
this is the default.
.
.
.TP
.B \[rs]E
Embed an escape character that is not interpreted in copy mode
(compare with
.B \[rs]a
and
.BR \[rs]t ).
.
You can use it to ease the writing of nested macro definitions.
.
It is also convenient to define strings containing escape sequences that
need to work when used in copy mode
(for example,
as macro arguments),
or which will be interpolated at varying macro nesting depths.
.
.
.TP
.BI \[rs]f[ font ]
Select
.IR font ,
which may be a mounting position,
abstract style,
or font name,
to choose the typeface.
.
.B \[rs]f[]
and
.B \[rs]fP
are synonyms;
we recommend the former.
.
.
.TP
.BI \[rs]F f
.TQ
.BI \[rs]F( fm
.TQ
.BI \[rs]F[ family ]
Select default font family.
.
.B \[rs]F[]
makes the previous font family the default.
.
.B \[rs]FP
is unlike
.BR \[rs]fP ;
it selects font family \[lq]P\[rq] as the default.
.
See the
.B fam
request below.
.
.
.TP
.BI \[rs]k( rg
.TQ
.BI \[rs]k[ reg ]
Mark horizontal drawing position in
two-character register
.RI name\~ rg
or arbitrary register
.RI name\~ reg .
.
.
.TP
.BI \[rs]m c
.TQ
.BI \[rs]m( cl
.TQ
.BI \[rs]m[ col ]
Set the stroke color.
.
.B \[rs]m[]
restores the previous stroke color,
or the default if there is none.
.
.
.TP
.BI \[rs]M c
.TQ
.BI \[rs]M( cl
.TQ
.BI \[rs]M[ col ]
Set the fill color.
.
.B \[rs]M[]
restores the previous fill color,
or the default if there is none.
.
.
.TP
.BI \[rs]n[ reg ]
Interpolate register
.IR reg .
.
.
.TP
.BI \[rs]O n
.TQ
.BI \[rs]O[ n ]
Suppress
.I \%troff
output of glyphs and geometric objects.
.
The sequences
.BR \[rs]O2 ,
.BR \[rs]O3 ,
.BR \[rs]O4 ,
and
.B \[rs]O5
are intended for internal use by
.MR grohtml 1 .
.
.
.RS
.TP
.B \[rs]O0
.TQ
.B \[rs]O1
Disable and enable,
respectively,
the emission of glyphs and geometric objects to the output driver,
provided that this sequence occurs at the outermost suppression level
(see
.B \[rs]O3
and
.BR \[rs]O4 ).
.
Horizontal motions corresponding to non-overstruck glyph widths still
occur.
.
These sequences also reset the registers
.BR opminx ,
.BR opminy ,
.BR opmaxx ,
and
.B opmaxy
to\~\-1.
.
These four registers mark the top left and bottom right hand corners of
a box encompassing all written or drawn output.
.
.
.TP
.B \[rs]O2
At the outermost suppression level,
enable emission of glyphs and geometric objects,
and write to the standard error stream the page number and values of the
four aforementioned registers encompassing glyphs written since the last
interpolation of a
.B \[rs]O
sequence,
as well as the page offset,
line length,
image file name
(if any),
horizontal and vertical device motion quanta,
and input file name.
.
Numeric values are in basic units.
.
.
.TP
.B \[rs]O3
.TQ
.B \[rs]O4
Begin and end a nested suppression level,
respectively.
.
.I \%grohtml
uses this mechanism to create images of output preprocessed with
.IR \%pic ,
.IR \%eqn ,
and
.IR \%tbl .
.
At startup,
.I \%troff
is at the outermost suppression level.
.
.I \%pre\-grohtml
generates these sequences when processing the document,
using
.I \%troff
with the
.B ps
output device,
Ghostscript,
and the PNM tools to produce images in PNG format.
.
These sequences start a new page if the device is not
.B html
or
.BR xhtml ,
to reduce the number of images crossing a page boundary.
.
.
.TP
.BI \[rs]O5[ Pfile ]
At the outermost suppression level,
write the name
.I file
to the standard error stream at position
.IR P ,
which must be one of
.BR l ,
.BR r ,
.BR c ,
or
.BR i ,
corresponding to
left,
right,
centered,
and inline alignments within the document,
respectively.
.
.I file
is is a name associated with the production of the next image.
.RE
.
.
.TP
.BI \[rs]R\[aq] name\~\[+-]n \[aq]
Synonymous with
.RB \[lq] .nr
.IR name\~\[+-]n \[rq].
.
.
.TP
.BI \[rs]s[ \[+-]n ]
.TQ
.BI \[rs]s \[+-] [ n ]
.TQ
.BI \[rs]s\[aq] \[+-]n \[aq]
.TQ
.BI \[rs]s \[+-] \[aq] n \[aq]
Set the type size to,
or increment or decrement it by,
.I n
scaled points.
.
.
.br
.ne 5v
.TP
.BI \[rs]V e
.TQ
.BI \[rs]V( ev
.TQ
.BI \[rs]V[ env ]
Interpolate contents of the environment variable
.IR env ,
as returned by
.MR getenv 3 .
.
.B \[rs]V
is interpreted even in copy mode.
.
.
.TP
.BI \[rs]X\[aq] anything \[aq]
Within
.B \[rs]X
arguments,
the escape sequences
.BR \[rs]& ,
.BR \[rs]) ,
.BR \[rs]% ,
and
.B \[rs]:
are ignored;
.BI \[rs] space
and
.B \[rs]\[ti]
are converted to single space characters;
and
.B \[rs]\[rs]
is reduced to
.BR \[rs] .
.
So that the basic Latin subset of the Unicode character set
(that is,
ISO\~646:1991-IRV or,
popularly,
\[lq]US-ASCII\[rq])
can be reliably encoded in
.I anything,
the special character escape sequences
.BR \[rs]\- ,
.BR \[rs][aq] ,
.BR \[rs][dq] ,
.BR \[rs][ga] ,
.BR \[rs][ha] ,
.BR \[rs][rs] ,
and
.B \[rs][ti]
are mapped to basic Latin characters;
see
.MR groff_char 7 .
.
For this transformation,
character translations and definitions are ignored.
.
Other escape sequences are not supported.
.
.
.IP
If the
.B \%use_charnames_in_special
directive appears in the output device's
.I DESC
file,
the use of special character escape sequences is
.I not
an error;
they are simply output verbatim
(with the exception of the seven mapped to Unicode basic Latin
characters,
discussed above).
.
.B \%use_charnames_in_special
is currently employed only by
.MR grohtml 1 .
.
.
.TP
.BI \[rs]Y m
.TQ
.BI \[rs]Y( ma
.TQ
.BI \[rs]Y[ mac ]
Interpolate a macro as a device control command.
.
This is similar to
.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\f[R],
except the contents of
.I mac
are not interpreted,
and
.I mac
can be a macro and thus contain newlines,
whereas the argument to
.B \[rs]X
cannot.
.
This inclusion of newlines requires an extension to the AT&T
.I troff \" AT&T
output format,
and will confuse postprocessors that do not know about it.
.
.
.TP
.BI \[rs]Z\[aq] anything \[aq]
Save the drawing position,
format
.IR anything ,
then restore it.
.
Tabs and leaders in the argument are ignored with an error diagnostic.
.
.
.TP
.B \[rs]#
Everything up to and including the next newline is ignored.
.
This escape sequence is interpreted even in copy mode.
.
.B \[rs]#
is like
.BR \[rs]" ,
except that
.B \[rs]"
does not ignore a newline;
the latter therefore cannot be used by itself for a whole-line
comment\[em]it leaves a blank line on the input stream.
.
.
.\" Keep \$0 before \$( in spite of collation.
.TP
.B \[rs]$0
Interpolate the name by which the macro being interpreted was called.
.
In GNU
.I troff \" GNU
this name can vary;
see the
.B als
request.
.
.
.TP
.BI \[rs]$( nn
.TQ
.BI \[rs]$[ nnn ]
In a macro or string definition,
interpolate
the
.IR nn th
or
.IR nnn th
argument.
.
Macros and strings can have an unlimited number of arguments.
.
.
.TP
.B \[rs]$*
In a macro or string definition,
interpolate the catenation of all arguments,
separated by spaces.
.
.
.TP
.B \[rs]$@
In a macro or string definition,
interpolate the catenation of all arguments,
with each surrounded by double quotes and separated by spaces.
.
.
.TP
.B \[rs]$\[ha]
In a macro or string definition,
interpolate the catenation of all arguments
constructed in a form suitable for passage to the
.B ds
request.
.
.
.TP
.B \[rs])
Interpolate a
.I transparent
dummy character\[em]one that is ignored by end-of-sentence detection.
.
It behaves as
.BR \[rs]& ,
except that
.B \[rs]&
is treated as letters and numerals normally are after
\[lq].\[rq],
\[lq]?\[rq],
and
\[lq]!\[rq];
.B \[rs]&
cancels end-of-sentence detection,
and
.B \[rs])
does not.
.
.
.TP
.BI \[rs]*[ "string\~\c
.RI [ arg \~.\|.\|.]\c
.B ]
Interpolate
.I string,
passing it
.I arg
\&.\|.\|.\&
as arguments.
.
.
.\" Keep \/ before \, in spite of collation.
.TP
.B \[rs]/
Apply an
.IR "italic correction" :
modify the spacing of the preceding glyph so that the distance between
it and the following glyph is correct if the latter is of upright shape.
.
For example,
if an italic\~\[lq]f\^\[rq] is followed immediately by a roman right
parenthesis,
then in many fonts the top right portion of the\~\[lq]f\^\[rq] overlaps
the top left of the right parenthesis,
.if t producing \f[I]f\f[R]),
which is ugly.
.
Inserting
.B \[rs]\^/
between them
.if t \{\
.  nop produces
.  ie \n(.g \f[I]f\/\f[R])
.  el       \f[I]f\|\f[R])
.  nop and
.\}
avoids this problem.
.
Use this escape sequence whenever an oblique glyph is immediately
followed by an upright glyph without any intervening space.
.
.
.TP
.B \[rs],
Apply a
.IR "left italic correction" :
modify the spacing of the following glyph so that the distance between
it and the preceding glyph is correct if the latter is of upright shape.
.
For example,
if a roman left parenthesis is immediately followed by an
italic\~\[lq]f\^\[rq],
then in many fonts the bottom left portion of the\~\[lq]f\^\[rq]
overlaps the bottom of the left parenthesis,
.if t producing \f[R](\f[I]f\f[R],
which is ugly.
.
Inserting
.B \[rs],
between them
.if t \{\
.  nop produces
.  ie \n(.g \f[R](\,\f[I]f\f[R]
.  el       \f[R](\^\f[I]f\f[R]
.  nop and
.\}
avoids this problem.
.
Use this escape sequence whenever an upright glyph is followed
immediately by an oblique glyph without any intervening space.
.
.
.TP
.B \[rs]:
Insert a non-printing break point.
.
That is,
a word can break there,
but the soft hyphen character does not mark the break point if it does
(in contrast to
.RB \[lq]\^ \[rs]% \[rq]).
.
This escape sequence is an input word boundary,
so the remainder of the word is subject to hyphenation as normal.
.
.
.TP
.BI \[rs]? anything \[rs]?
When used in a diversion,
this transparently embeds
.I anything
in the diversion.
.I anything
is read in copy mode.
.
When the diversion is reread,
.I anything
is interpreted.
.I anything
may not contain newlines;
use
.B \[rs]!\&
if you want to embed newlines in a diversion.
.
The escape sequence
.B \[rs]?\&
is also recognized in copy mode and becomes an internal code;
it is this code that terminates
.IR anything .
Thus
.
.
.RS
.IP
.EX
.ne 14v+\n(.Vu
\&.nr x 1
\&.nf
\&.di d
\&\[rs]?\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]\[rs]\[rs]\[rs]\[rs]\
\[rs]\c
\&\[rs]nx\[rs]\[rs]\[rs]\[rs]?\[rs]\[rs]?\[rs]?
\&.di
\&.nr x 2
\&.di e
\&.d
\&.di
\&.nr x 3
\&.di f
\&.e
\&.di
\&.nr x 4
\&.f
.EE
.RE
.
.
.IP
prints\~\c
.BR 4 .
.
.
.TP
.BI \[rs][ char ]
Typeset the special character
.IR char .
.
.
.TP
.BI \[rs][ "base-char combining-component\~"\c
.RB .\|.\|. ]
Typeset a composite glyph consisting of
.I base-char
overlaid with one or more
.IR combining-component s.
.
For example,
.RB \[lq]\| \[rs][A\~ho] \^\[rq]
is a capital letter \[lq]A\[rq] with a \[lq]hook accent\[rq] (ogonek).
.
See the
.B \%composite
request below;
.IR "Groff: The GNU Implementation of troff" ,
the
.I groff
Texinfo manual,
for details of composite glyph name construction;
and
.MR groff_char 7
for a list of components used in composite glyph names.
.
.
.TP
.B \[rs]\[ti]
Insert an unbreakable space that is adjustable like an ordinary space.
.
It is discarded from the end of an output line if a break is forced.
.
.
.\" ====================================================================
.SS "Restricted requests"
.\" ====================================================================
.
To mitigate risks from untrusted input documents,
the
.B pi
and
.B sy
requests are disabled by default.
.
.MR \%troff 1 's
.B \-U
option enables the formatter's \[lq]unsafe mode\[rq],
restoring their function
(and enabling additional
.I groff
extension requests,
.BR open ,
.BR opena ,
and
.BR pso ).
.
.
.\" ====================================================================
.SS "New requests"
.\" ====================================================================
.
.TP
.BI .aln\~ "new old"
Create alias
.I new
for existing register named
.IR old ,
causing the names to refer to the same stored value.
.
If
.I old
is undefined,
a warning in category
.RB \[lq] reg \[rq]
is generated and the request is ignored.
.
To remove a register alias,
invoke
.B rr
on its name.
.
A register's contents do not become inaccessible until it has no more
names.
.
.
.TP
.BI .als\~ "new old"
Create alias
.I new
for existing request,
string,
macro,
or diversion named
.IR old ,
causing the names to refer to the same stored object.
.
If
.I old
is undefined,
a warning in category
.RB \[lq] mac \[rq]
is produced,
and the request is ignored.
.
The
.RB \[lq] am \[rq],
.RB \[lq] as \[rq],
.BR da ,
.BR de ,
.BR di ,
and
.B ds
requests
(together with their variants)
create a new object only if the name of the macro,
diversion,
or string is currently undefined
or if it is defined as a request;
normally,
they modify the value of an existing object.
.
To remove an alias,
invoke
.B rm
on its name.
.
The object itself is not destroyed until it has no more names.
.
.
.IP
When a request,
macro,
string,
or diversion is aliased,
redefinitions and appendments \[lq]write through\[rq] alias names.
.
To replace an alias with a separately defined object,
you must use the
.B rm
request on its name first.
.
.
.TP
.BI .am1\~ name\~\c
.RI [ end-name ]
As
.RB \[lq] am \[rq],
but compatibility mode is disabled while the appendment to
.I name
is interpreted:
a \[lq]compatibility save\[rq] token is inserted at its beginning,
and a \[lq]compatibility restore\[rq] token at its end.
.
As a consequence,
the requests
.RB \[lq] am \[rq],
.BR am1 ,
.BR de ,
and
.B de1
can be intermixed freely since the compatibility save/\:restore tokens
affect only the parts of the macro populated by
.B am1
and
.BR de1 .
.
.
.TP
.BI .ami\~ name\~\c
.RI [ end-name ]
Append to macro indirectly.
.
See
.B dei
below.
.
.
.TP
.BI .ami1\~ name\~\c
.RI [ end-name ]
As
.BR ami ,
but compatibility mode is disabled during interpretation of the
appendment.
.
.
.TP
.BI .as1\~ name\~\c
.RI [ contents ]
As
.RB \[lq] as \[rq],
but compatibility mode is disabled while the appendment to
.I name
is interpreted:
a \[lq]compatibility save\[rq] token is inserted at the beginning of
.IR contents ,
and a \[lq]compatibility restore\[rq] token after it.
.
As a consequence,
the requests
.RB \[lq] as \[rq],
.BR as1 ,
.BR ds ,
and
.B ds1
can be intermixed freely since the compatibility save/\:restore tokens
affect only the portions of the strings populated by
.B as1
and
.BR ds1 .
.
.
.TP
.BI .asciify\~ div
.I Unformat
the diversion
.I div
in a way such that Unicode basic Latin (ASCII) characters,
characters translated with the
.B trin
request,
space characters,
and some escape sequences,
that were formatted in the diversion
.I div
are treated like ordinary input characters when
.I div
is reread.
.
Doing so can be useful in conjunction with the
.B writem
request.
.
.B asciify
can be also used for gross hacks;
for example,
the following sets
.RB register\~ n
to\~1.
.
.
.RS
.IP
.EX
.ne 8v+\n(.Vu
\&.tr @.
\&.di x
\&@nr n 1
\&.br
\&.di
\&.tr @@
\&.asciify x
\&.x
.EE
.RE
.
.
.IP
.B asciify
cannot return all items in a diversion to their source equivalent:
nodes such as those produced by
.BR \[rs]N[ .\|.\|.\& ]
will remain nodes,
so the result cannot be guaranteed to be a pure string.
.
See section \[lq]Copy mode\[rq] in
.MR groff 7 .
.
Glyph parameters such as the type face and size are not preserved;
use
.B unformat
to achieve that.
.
.
.TP
.B .backtrace
Write backtrace of input stack to the standard error stream.
.
See the
.B \-b
option of
.MR \%troff 1 .
.
.
.TP
.BR .blm\~ [\c
.IR name ]
Set a blank line macro (trap).
.
If a blank line macro is thus defined,
.I groff
executes
.I macro
when a blank line is encountered in the input file,
instead of the usual behavior.
.
A line consisting only of spaces is also treated as blank and subject to
this trap.
.
If no argument is supplied,
the default blank line behavior is (re-)established.
.
.
.TP
.BR .box\~ [\c
.IR name ]
.TQ
.BR .boxa\~ [\c
.IR name ]
Divert
(or append)
output to
.I name,
similarly to the
.B di
and
.B da
requests,
respectively.
.
Any pending output line is
.I not
included in the diversion.
.
Without an argument,
stop diverting output;
any pending output line inside the diversion is discarded.
.
.
.TP
.B .break
Exit a
.RB \[lq] while \[rq]
loop.
.
Do not confuse this request with a typographical break or the
.B br
request.
.
See
.RB \[lq] continue \[rq].
.
.
.TP
.B .brp
Break and adjust line;
this is the AT&T
.I troff \" AT&T
escape sequence
.B \[rs]p
in request form.
.
.
.TP
.BI .cflags\~ "n c1 c2\~"\c
\&.\|.\|.
Assign properties encoded by the number
.I n
to characters
.IR c1 ,
.IR c2 ,
and so on.
.
Ordinary and special characters have certain associated properties.
.
(Glyphs don't:
to GNU
.IR troff , \" GNU
like AT&T device-independent
.IR troff , \" AT&T
a glyph is an identifier corresponding to a rectangle with some metrics;
see
.MR groff_font 5 .)
.
The first argument is the sum of the desired flags and the remaining
arguments are the characters to be assigned those properties.
.
Spaces between the
.I cn
arguments are optional.
.
Any argument
.I cn
can be a character class defined with the
.B class
request rather than an individual character.
.
.
.IP
The non-negative integer
.I n
is the sum of any of the following.
.
Some combinations are nonsensical,
such as
.RB \[lq] 33 \[rq]
(1 + 32).
.
.
.RS
.IP 1
Recognize the character as ending a sentence if followed by a newline
or two spaces.
.
Initially,
characters
.RB \[lq] .?! \[rq]
have this property.
.
.
.IP 2
Enable breaks before the character.
.
A line is not broken at a character with this property unless the
characters on each side both have non-zero hyphenation codes.
.
This exception can be overridden by adding 64.
.
Initially,
no characters have this property.
.
.
.IP 4
Enable breaks after the character.
.
A line is not broken at a character with this property unless the
characters on each side both have non-zero hyphenation codes.
.
This exception can be overridden by adding 64.
.
Initially,
characters
.RB \[lq] \-\[rs][hy]\[rs][em] \^\[rq]
have this property.
.
.
.IP 8
Mark the glyph associated with this character as overlapping other
instances of itself horizontally.
.
Initially,
characters
.RB \[lq]\^ \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]\
\& \^\[rq]
have this property.
.
.
.IP 16
Mark the glyph associated with this character as overlapping other
instances of itself vertically.
.
Initially,
the character
.RB \[lq]\^ \[rs][br] \^\[rq]
has this property.
.
.
.IP 32
Mark the character as transparent for the purpose of end-of-sentence
recognition.
.
In other words,
an end-of-sentence character followed by any number of characters with
this property is treated as the end of a sentence if followed by a
newline or two spaces.
.
This is the same as having a zero space factor in \*[tx].
.
Initially,
characters
.\" The following is ordered with the apostrophe and (single) closing
.\" quote on the ends so they are more easily visually distinguished
.\" from the double quotation marks in roman.
.RB \[lq]\| \[aq]\|"\|)]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs]\^[cq] \|\[rq]
have this property.
.
.
.IP 64
Ignore hyphenation codes of the surrounding characters.
.
Use this value in combination with values 2 and\~4.
.
Initially,
no characters have this property.
.
.
.IP
For example,
if you need an automatic break point after
the en-dash in numeric ranges like \[lq]3000\[en]5000\[rq],
insert
.RS
.RS
.EX
\&.cflags 68 \[rs][en]
.EE
.RE
into your document.
.
However,
this can lead to bad layout if done without thinking;
in most situations,
a better solution than
changing the
.B cflags
value is inserting
.RB \[lq] \[rs]: \[rq]
right after the hyphen at the places that really need a break point.
.RE
.
.
.P
The remaining values were implemented for East Asian language support;
those who use alphabetic scripts exclusively can disregard them.
.
.
.IP 128
Prohibit a break before the character,
but allow a break after the character.
.
This works only in combination with values 256 and 512 and has no effect
otherwise.
.
Initially,
no characters have this property.
.
.
.IP 256
Prohibit a break after the character,
but allow a break before the character.
.
This works only in combination with values 128 and 512 and has no effect
otherwise.
.
Initially,
no characters have this property.
.
.
.IP 512
Allow a break before or after the character.
.
This works only in combination with values 128 and 256 and has no effect
otherwise.
.
Initially,
no characters have this property.
.RE
.
.
.IP
In contrast to values 2 and\~4,
the values 128,
256,
and 512 work
pairwise.
.
If,
for example,
the left character has value 512,
and the right character 128,
no break will be automatically inserted between them.
.
If we use value\~6 instead for the left character,
a break after the character can't be suppressed since the neighboring
character on the right doesn't get examined.
.
.
.TP
.BI .char\~ "c contents"
Define the ordinary or special
.RI character\~ c
as
.IR contents ,
which can be empty.
.
More precisely,
.B char
defines a
.I groff
object
(or redefines an existing one)
that is accessed with the
.RI name\~ c
on input,
and produces
.I contents
on output.
.
Every time
.I c
is to be formatted,
.I contents
is processed in a temporary environment and the result is wrapped up
into a single object.
.
Compatibility mode is turned off and the escape character is
set
.RB to\~ \[rs]
while
.I contents
is processed.
.
Any emboldening,
constant spacing,
or track kerning is applied to this object as a whole,
not to each character in
.IR contents .
.
.
.IP
An object defined by this request can be used just like a glyph
provided by the output device.
.
In particular,
other characters can be translated to it with the
.B tr
request;
it can be made the tab or leader fill character with the
.B tc
and
.B lc
requests;
sequences of it can be drawn with the
.B \[rs]l
and
.B \[rs]L
escape sequences;
and,
if the
.B hcode
request is used on
.IR c ,
it is subject to automatic hyphenation.
.
.
.IP
To prevent infinite recursion,
occurrences of
.I c
within its own definition are treated normally
(as if it were not being defined with
.BR char ).
.
The
.B tr
and
.B trin
requests take precedence if
.B char
both apply
.RI to\~ c .
.
A character definition can be removed with the
.B rchar
request.
.
.
.TP
.BI .chop\~ object
Remove the last character from the macro,
string,
or diversion
.IR object .
.
This is useful for removing the newline from the end of a diversion that
is to be interpolated as a string.
.
This request can be used repeatedly on the same
.IR object ;
see section \[lq]gtroff Internals\[rq] in
.IR "Groff: The GNU Implementation of troff" ,
the
.I groff
Texinfo manual,
for discussion of nodes inserted by
.IR groff .
.
.
.TP
.BI .class\~ "name c1 c2\~"\c
\&.\|.\|.
Define a character class
(or simply \[lq]class\[rq])
.I name
comprising the characters or range expressions
.IR c1 ,
.IR c2 ,
and so on.
.
.
.IP
A class thus defined can then be referred to in lieu of listing all the
characters within it.
.
Currently,
only the
.B cflags
request can handle references to character classes.
.
.
.IP
In the request's simplest form,
each
.I cn
is a character
(or special character).
.
.RS
.RS
.EX
\&.class [quotes] \[aq] \[rs][aq] \[rs][dq] \[rs][oq] \[rs][cq] \
\[rs][lq] \[rs][rq]
.EE
.RE
.RE
.
.
.IP
Since class and special character names share the same name space,
we recommend starting and ending the class name with
.RB \[lq] [ \[rq]
and
.RB \[lq] ] \[rq],
respectively,
to avoid collisions with existing character names defined by
.I groff
or the user
(with
.B char
and related requests).
.
This practice applies the presence of
.RB \[lq] ] \[rq]
in the class name to prevent the usage of the special character escape
form
.RB \[lq] \[rs][ .\|.\|. ] \[rq],
thus you must use the
.B \[rs]C
escape to access a class with such a name.
.
.
.IP
You can also use a character range expression consisting of a start
character followed by
.RB \[lq] \- \[rq]
and then an end character.
.
Internally,
GNU
.I troff \" GNU
converts these two character names to Unicode code points
(according to the
.I groff
glyph list [GGL]),
which determine the start and end values of the range.
.
If that fails,
the class definition is skipped.
.
Furthermore,
classes can be nested.
.
.RS
.RS
.EX
\&.class [prepunct] , : ; > }
\&.class [prepunctx] \[rs]C\[aq][prepunct]\[aq] \
\[rs][u2013]\-\[rs][u2016]
.EE
.RE
The class
.RB \[lq] [prepunctx] \[rq]
thus contains the contents of the class
.RB \[lq] [prepunct] \[rq]
and characters in the range U+2013\[en]U+2016.
.RE
.
.
.IP
If you want to include
.RB \[lq] \- \[rq]
in a class,
it must be the first character value in the argument list,
otherwise it gets misinterpreted as part of the range syntax.
.
.
.IP
It is not possible to use class names as end points of range
definitions.
.
.
.IP
A typical use of the
.B class
request is to control line-breaking and hyphenation rules as defined by
the
.B cflags
request.
.
For example,
to inhibit line breaks before the characters belonging to the
.RB \[lq] [prepunctx] \[rq]
class defined in the previous example,
you can write the following.
.
.RS
.RS
.EX
\&.cflags 2 \[rs]C\[aq][prepunctx]\[aq]
.EE
.RE
.RE
.
.
.TP
.BI .close\~ stream
Close the stream named
.IR stream ,
invalidating it as an argument to the
.B write
request.
.
See
.BR open .
.
.
.TP
.BI .composite\~ c1\~c2
Map character name
.I c1
to character name
.I c2
when
.I c1
is a combining component in a composite glyph.
.
Typically,
this remaps a spacing glyph to a combining one.
.
.
.TP
.B .continue
Skip the remainder of a
.RB \[lq] while \[rq]
loop's body,
immediately starting the next iteration.
.
See
.BR break .
.
.
.TP
.BI .color\~ n
If
.I n
is non-zero or missing,
enable colors
(the default),
otherwise disable them.
.
.
.TP
.BI .cp\~ n
If
.I n
is non-zero or missing,
enable compatibility mode,
otherwise disable it.
.
In compatibility mode,
long names are not recognized,
and the incompatibilities they cause do not arise.
.
.
.TP
.BI .defcolor\~ "ident scheme color-component\~\c"
\&.\|.\|.
Define a color named
.I ident.
.
.I scheme
identifies a color space and determines the number of required
.IR color-component s;
it must be one of
.RB \[lq] rgb \[rq]
(three components),
.RB \[lq] cmy \[rq]
(three components),
.RB \[lq] cmyk \[rq]
(four components),
or
.RB \[lq] gray \[rq]
(one component).
.
.RB \[lq] grey \[rq]
is accepted as a synonym of
.RB \[lq] gray \[rq].
.
The color components can be encoded as a hexadecimal value starting
with
.B #
or
.BR ## .
.
The former indicates that each component is in the range 0\[en]255
(0\[en]FF),
the latter the range 0\[en]65535 (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
.RB of\~\[lq] f \[rq],
which multiplies its value by 65,536
(but clamps it at 65,535).
.
.
.IP
Each output device has a color named
.RB \[lq] default \[rq],
which cannot be redefined.
.
A device's default stroke and fill colors are not necessarily the same.
.
.
.TP
.BI .de1\~ name\~\c
.RI [ end-name ]
Define a macro to be interpreted with compatibility mode disabled.
.
When
.I name
is called,
compatibility mode enablement status is saved;
it is restored when the call completes.
.
.
.TP
.BI .dei\~ name\~\c
.RI [ end-name ]
Define macro indirectly,
with the name of the macro to be defined in string
.I name
and the name of the end macro terminating its definition in string
.IR end-name .
.
.
.TP
.BI .dei1\~ name\~\c
.RI [ end-name ]
As
.BR dei ,
but compatibility mode is disabled while the definition of the macro
named in string
.I name
is interpreted.
.
.
.TP
.BI .device\~ anything
Write
.IR anything ,
read in copy mode,
to
.I \%troff
output as a device control command.
.
An initial neutral double quote is stripped to allow the embedding of
leading spaces.
.
.
.TP
.BI .devicem\~ name
Write contents of macro or string
.I name
to
.I \%troff
output as a device control command.
.
.
.TP
.BI .do\~ name\~\c
.RI [ arg \~.\|.\|.]
Interpret the string,
request,
diversion,
or macro
.I name
(along with any arguments)
with compatibility mode disabled.
.
Compatibility mode is restored
(only if it was active)
when the
.I expansion
of
.I name
is interpreted;
that is,
the restored compatibility state applies to the contents of the macro,
string,
or diversion
.I name
as well as data read from files or pipes if
.I name
is any of the
.BR so ,
.BR soquiet ,
.BR mso ,
.BR msoquiet ,
or
.B pso
requests.
.
.
.IP
For example,
.RS
.RS \" one "extra" RS to get us inboard of this indented paragraph
.EX
\&.de mac1
FOO
\&..
\&.de1 mac2
groff
\&.mac1
\&..
\&.de mac3
compatibility
\&.mac1
\&..
\&.de ma
\[rs]\[rs]$1
\&..
\&.cp 1
\&.do mac1
\&.do mac2 \[rs]" mac2, defined with .de1, calls "mac1"
\&.do mac3 \[rs]" mac3 calls "ma" with argument "c1"
\&.do mac3 \[rs][ti] \[rs]" groff syntax accepted in .do arguments
.EE
.RE
results in
.RS
.EX
FOO groff FOO compatibility c1 \[ti]
.EE
.RE
as output.
.RE \" this "extra" RE avoids indentation of the remaining paragraphs
.
.
.TP
.BI .ds1\~ "name contents"
As
.BR ds ,
but compatibility mode is disabled while
.I name
is interpreted:
a \[lq]compatibility save\[rq] token is inserted at the beginning of
.IR contents ,
and a \[lq]compatibility restore\[rq] token after it.
.
.
.TP
.B .ecr
Restore the escape character saved with
.BR ecs ,
or set escape character to
.RB \[lq]\| \[rs] \[rq]
if none has been saved.
.
.
.TP
.B .ecs
Save the current escape character.
.
.
.TP
.BI .evc\~ env
Copy the properties of environment
.I env
to the current environment,
except for the following data.
.
.
.RS
.IP \[bu] 2n
a partially collected line,
if present;
.
.
.IP \[bu]
the interruption status of the previous input line
(due to use of the
.B \[rs]c
escape sequence);
.
.
.IP \[bu]
the count of remaining lines to center,
to right-justify,
or to underline
(with or without underlined spaces)\[em]these are set to zero;
.
.
.IP \[bu]
the activation status of temporary indentation;
.
.
.IP \[bu]
input traps and their associated data;
.
.
.IP \[bu]
the activation status of line numbering
(which can be reactivated with
.RB \[lq] .nm\~+0 \[rq]);
and
.
.
.IP \[bu]
the count of consecutive hyphenated lines
(set to zero).
.RE
.
.
.TP
.BR .fam\~ [\c
.IR family ]
Set default font family to
.IR family .
.
If no argument is given,
the previous font family is selected,
or the formatter's default family if there is none.
.
The formatter's default font family is \[lq]T\[rq] (Times),
but it can be overridden by the output device\[em]see
.MR groff_font 5 .
.
The default font family is associated with the environment.
.
See
.BR \[rs]F .
.
.
.TP
.BI .fchar\~ c\~contents
Define fallback
.RI character\~ c
as
.IR contents .
.
The syntax of this request is the same as the
.B char
request;
the difference is that a character defined with
.B char
hides a glyph with the same name in the selected font,
whereas characters defined with
.B fchar
are checked only if
.I c
isn't found in the selected font.
.
This test happens before special fonts are searched.
.
.
.TP
.BI .fcolor\~ color
Set the fill color to
.IR color .
.
Without an argument,
the previous fill color is selected.
.
.
.TP
.BI .fschar\~ f\~c\~contents
Define fallback special
.RI character\~ c
for font\~\c
.I f
as
.IR contents .
.
A character defined by
.B fschar
is located after the list of fonts declared with
.B \%fspecial
is searched but before those declared with the
.RB \%\[lq] special \[rq]
request.
.
.TP
.BI .fspecial\~ "f s1 s2\~"\c
\&.\|.\|.
When
.RI font\~ f
is selected,
fonts
.IR s1 ,
.IR s2 ,
\&.\|.\|.\&
are treated as special;
that is,
they are searched for glyphs not found in
.IR f .
.
Any fonts specified in the
.RB \%\[lq] special \[rq]
request are searched after
.IR s1 ,
.IR s2 ,
and so on.
.
Without
.I s
arguments,
.B \%fspecial
clears the list of fonts treated as special when
.I f
is selected.
.
.
.TP
.BI .ftr\~ f\~g
Translate
.RI font\~ f
.RI to\~ g .
.
Whenever a font
.RI named\~ f
is referred to in an
.B \[rs]f
escape sequence,
in the
.B F
and
.B S
conditional expression operators,
or in the
.BR ft ,
.BR ul ,
.BR bd ,
.BR cs ,
.BR tkf ,
.BR \%special ,
.BR \%fspecial ,
.BR fp ,
or
.B sty
requests,
.RI font\~ g
is used.
If
.I g
is missing or identical
.RI to\~ f ,
then
.RI font\~ f
is not translated.
.
.
.TP
.BI .fzoom\~ f\~zoom
Set zoom factor
.I zoom
for font\~\c
.IR f .
.I zoom
must a non-negative integer multiple of 1/1000th.
.
If it is missing or is equal to zero,
it means the same as 1000,
namely no magnification.
.
.IR f \~\c
must be a resolved font name,
not an abstract style.
.\" XXX: What about a mounting position?  It's not rejected...
.
.
.TP
.BI .gcolor\~ color
Set the stroke color to
.IR color .
.
Without an argument,
the previous stroke color is selected.
.
.
.TP
.BI .hcode\~ "c1 code1\~"\c
.RI [ "c2 code2" "] .\|.\|."
Set the hyphenation code of character
.I c1
to
.IR code1 ,
that of
.I c2
to
.IR code2 ,
and so on.
.
A hyphenation code must be an ordinary character
(not a special character escape sequence)
other than a digit.
.
The request is ignored if given no arguments.
.
.
.IP
For hyphenation to work,
hyphenation codes must be set up.
.
At startup,
.I groff
assigns hyphenation codes to the letters \[lq]a\[en]z\[rq]
(mapped to themselves),
to the letters \[lq]A\[en]Z\[rq]
(mapped to \[lq]a\[en]z\[rq]),
and zero to all other characters.
.
Normally,
hyphenation patterns contain only lowercase letters which should be
applied regardless of case.
.
In other words,
they assume that the words \[lq]ABBOT\[rq] and \[lq]Abbot\[rq] should be
hyphenated exactly as \[lq]abbot\[rq] is.
.
.B hcode
extends this principle to letters outside the Unicode basic Latin
alphabet;
without it,
words containing such letters won't be hyphenated properly even if the
corresponding hyphenation patterns contain them.
.
.
.TP
.BI .hla\~ lang
Set the hyphenation language to
.IR lang .
.
Hyphenation exceptions specified with the
.B hw
request and hyphenation patterns and exceptions specified with the
.B hpf
and
.B hpfa
requests are associated with the hyphenation language.
.
The
.B hla
request is usually invoked by a localization file,
which is in turn loaded by the
.I troffrc
or
.I troffrc\-end
file;
see the
.B hpf
request below.
.
The hyphenation language is associated with the environment.
.
.
.TP
.BR .hlm\~ [\c
.IR n ]
Set the maximum number of consecutive hyphenated lines
.RI to\~ n .
.
If
.I n
is negative,
there is no maximum.
.
If omitted,
.I n
is\~\-1.
.
This value is associated with the environment.
.
Only lines output from a given environment count towards the maximum
associated with that environment.
.
Hyphens resulting from
.B \[rs]%
are counted;
explicit hyphens are not.
.
.
.TP
.BI .hpf\~ pattern-file
Read hyphenation patterns from
.IR pattern-file .
.
This file is sought in the same way that macro files are with the
.B mso
request or the
.BI \-m name
command-line option to
.MR groff 1
and
.MR \%troff 1 .
.
.
.IP
The
.I pattern-file
should have the same format as (simple) \*[tx] pattern files.
.
The following scanning rules are implemented.
.
.
.RS
.IP \[bu] 2n
A percent sign starts a comment
(up to the end of the line)
even if preceded by a backslash.
.
.
.IP \[bu]
\[lq]Digraphs\[rq] like
.B \[rs]$
are not supported.
.
.
.IP \[bu]
.RB \[lq] \[ha]\[ha]\c
.IR xx \[rq]
(where each
.I x
is 0\[en]9 or a\[en]f) and
.BI \[ha]\[ha] c
.RI (character\~ c
in the code point range 0\[en]127 decimal)
are recognized;
other uses
.RB of\~ \[ha]
cause an error.
.
.
.IP \[bu]
No macro expansion is performed.
.
.
.IP \[bu]
.B hpf
checks for the expression
.BR \[rs]patterns{ .\|.\|. }
(possibly with whitespace before or after the braces).
.
Everything between the braces is taken as hyphenation patterns.
.
Consequently,
.RB \[lq] { \[rq]
and
.RB \[lq] } \[rq]
are not allowed in patterns.
.
.
.IP \[bu]
Similarly,
.BR \[rs]hyphenation{ .\|.\|. }
gives a list of hyphenation exceptions.
.
.
.IP \[bu]
.B \[rs]endinput
is recognized also.
.
.
.IP \[bu]
For backwards compatibility,
if
.B \[rs]patterns
is missing,
the whole file is treated as a list of hyphenation patterns
(but the
.RB \[lq] % \[rq]
character is still recognized as the start of a comment).
.RE
.
.
.IP
Use the
.B hpfcode
request
(see below)
to map the encoding used in hyphenation pattern files to
.IR groff 's
input encoding.
.
.
.IP
The set of hyphenation patterns is associated with the hyphenation
language set by the
.B hla
request.
.
The
.B hpf
request is usually invoked by a localization file loaded by the
.I troffrc
file.
.
By default,
.I troffrc
loads the localization file for English.
.
(As of
.I groff
1.23.0,
localization files for Czech
.RI ( cs ),
German
.RI ( de ),
English
.RI ( en ),
French
.RI ( fr ),
Japanese
.RI ( ja ),
Swedish
.RI ( sv ),
and Chinese
.RI ( zh )
exist.)
.
For Western languages,
the localization file sets the hyphenation mode and loads hyphenation
patterns and exceptions.
.
.
.IP
A second call to
.B hpf
(for the same language)
replaces the old patterns with the new ones.
.
.
.IP
Invoking
.B hpf
causes an error if there is no hyphenation language.
.
.
.IP
If no
.B hpf
request is specified
(either in the document,
in a file loaded at startup,
or in a macro package),
GNU
.I troff \" GNU
won't automatically hyphenate at all.
.
.
.TP
.BI .hpfa\~ pattern-file
As
.BR hpf ,
except that the hyphenation patterns and exceptions from
.I pattern-file
are appended to the patterns already applied to the hyphenation language
of the environment.
.
.
.TP
.BI .hpfcode\~ "a b"\c
.RI \~[ "c d" "] .\|.\|."
Define mapping values for character codes in pattern files.
.
This is an older mechanism no longer used by
.IR groff 's
own macro files;
for its successor,
see
.B hcode
above.
.
.B hpf
or
.B hpfa
apply the mapping
after reading or appending to the active list of patterns.
.
Its arguments are pairs of character codes\[em]integers from 0 to\~255.
.
The request maps character
.RI code\~ a
to
.RI code\~ b ,
.RI code\~ c
to
.RI code\~ d ,
and so on.
.
Character codes that would otherwise be invalid in
.I groff
can be used.
.
By default,
every code maps to itself except those for letters \[lq]A\[rq] to
\[lq]Z\[rq],
which map to those for \[lq]a\[rq] to \[lq]z\[rq].
.
.
.TP
.BR .hym\~ [\c
.IR length ]
Set the (right) hyphenation margin
.RI to\~ length .
.
If the adjustment mode is not
.RB \[lq] b \[rq]
or
.RB \[lq] n \[rq],
the line is not hyphenated if it is shorter than
.IR length .
.
Without an argument,
the default hyphenation margin is reset to its default value,
0.
.
The default scaling unit
.RB is\~\[lq] m \[rq].
.
The hyphenation margin is associated with the environment.
.
A negative argument resets the hyphenation margin to zero,
emitting a warning in category
.RB \[lq] range \[rq].
.
.
.TP
.BR .hys\~ [\c
.IR hyphenation-space ]
Suppress hyphenation of the line in adjustment modes
.RB \[lq] b \[rq]
or
.RB \[lq] n \[rq],
if it can be justified by adding no more than
.I hyphenation-space
extra space to each inter-word space.
.
Without an argument,
the hyphenation space adjustment threshold is set to its default value,
0.
.
The default scaling unit
.RB is\~\[lq] m \[rq].
.
The hyphenation space adjustment threshold is associated with the
current environment.
.
A negative argument resets the hyphenation space adjustment threshold to
zero,
emitting a warning in category
.RB \[lq] range \[rq].
.
.
.TP
.BI .itc\~ n\~name
As
.RB \[lq] it \[rq],
but lines interrupted with the
.B \[rs]c
escape sequence are not applied to the line count.
.
.
.TP
.BI .kern\~ n
If
.I n
is non-zero or missing,
enable pairwise kerning
(the default),
otherwise disable it.
.
.
.TP
.BI .length\~ "reg anything"
Compute the number of characters in
.I anything
and return the count in the register
.IR reg .
.
If
.I reg
doesn't exist,
it is created.
.
.I anything
is read in copy mode.
.
.
.RS
.IP
.EX
.B .ds xxx abcd\eh\[aq]3i\[aq]efgh
.B .length yyy \e*[xxx]
.B \en[yyy]
14
.EE
.RE
.
.
.TP
.BI .linetabs\~ n
.RS
If
.I n
is non-zero or missing,
enable line-tabs mode,
otherwise disable it
(the default).
.
In this mode,
tab stops are computed relative to the start of the pending output line,
instead of the drawing position corresponding to the start of the input
line.
.
Line-tabs mode is a property of the environment.
.
.
.P
For example,
the following
.
.
.RS
.P
.ne 6v+\n(.Vu
.EX
\&.ds x a\[rs]t\[rs]c
\&.ds y b\[rs]t\[rs]c
\&.ds z c
\&.ta 1i 3i
\&\[rs]*x
\&\[rs]*y
\&\[rs]*z
.EE
.RE
.
yields
.
.RS
.EX
a         b         c
.EE
.RE
.
whereas in line-tabs mode,
the same input gives
.
.RS
.EX
a         b                   c
.EE
.RE
.
instead.
.RE
.
.
.TP
.BR .lsm\~ [\c
.IR name ]
Set the leading space macro (trap) to
.IR name .
.
If there are leading space characters on an input line,
.I name
is invoked in lieu of the usual
.I roff
behavior;
the leading spaces are removed.
.
The count of leading spaces on an input line is stored in
.BR \[rs]n[lsn] ,
and the amount of corresponding horizontal motion in
.BR \[rs]n[lss] ,
irrespective of whether a leading space trap is set.
.
When it is,
the leading spaces are removed from the input line,
and no motion is produced before calling
.IR name .
.
If no argument is supplied,
the default leading space behavior is (re-)established.
.
.
.TP
.BI .mso\~ file
As
.RB \[lq] so \[rq],
except that
.I file
is sought in the same directories as arguments to the
.MR groff 1
and
.MR \%troff 1
.B \-m
command-line option are
(the \[lq]tmac path\[rq]).
.
If the file name to be interpolated has the form
.IB name .tmac
and it isn't found,
.B mso
tries to include
.BI tmac. name
instead and vice versa.
.
If
.I file
does not exist,
a warning in category
.RB \[lq] file \[rq]
is emitted
and the request has no other effect.
.
.
.TP
.BI .msoquiet\~ file
As
.BR mso ,
but no warning is emitted if
.I file
does not exist.
.
.
.TP
.BI .nop \~anything
Interpret
.I anything
as if it were an input line.
.
.B nop
resembles
.RB \[lq] ".if 1" \[rq];
it puts a break on the output if
.I anything
is empty.
.
Unlike
.RB \[lq]\| if \|\[rq],
it cannot govern conditional blocks.
.
Its application is to maintain consistent indentation within macro
definitions even when producing text lines.
.
.
.TP
.B .nroff
Make the
.B n
conditional expression evaluate true and
.B t
false.
.
See
.BR troff .
.
.
.TP
.BI .open\~ "stream file"
Open
.I file
for writing and associate
.I stream
with it.
.
See
.B write
and
.BR close .
.
.
.TP
.BI .opena\~ "stream file"
As
.BR open ,
but if
.I file
exists,
append to it instead of truncating it.
.
.
.TP
.BI .output\~ contents
Emit
.IR contents ,
which are read in copy mode,
to the formatter output;
this is similar to
.B \[rs]!\&
used in the top-level diversion.
.
An initial neutral double quote in
.I contents
is stripped to allow the embedding of leading spaces.
.\" XXX: useless request warning if no argument?
.
.
.TP
.B .pev
Report the state of the current environment followed by that of all
other environments to the standard error stream.
.
.
.TP
.B .pnr
Write the names and values of all currently defined registers to the
standard error stream.
.
.
.TP
.BI .psbb \~file
Get the bounding box of a PostScript image
.IR file .
.
This file must conform to Adobe's Document Structuring Conventions;
the request attempts to extract the bounding box values from a
.B \%%%BoundingBox
comment.
.
After invocation,
the
.I x
and
.I y
coordinates
(in PostScript units)
of the lower left and upper right corners can be found in the registers
.BR \[rs]n[llx] ,
.BR \[rs]n[lly] ,
.BR \[rs]n[urx] ,
and
.BR \[rs]n[ury] ,
respectively.
.
If an error occurs,
these four registers are set to zero.
.
.
.TP
.BI .pso \~command
As
.RB \[lq] so \[rq],
except that input comes from the standard output stream of
.IR command .
.
.
.TP
.B .ptr
Report the names and vertical positions of all page location traps
to the standard error stream.
.
Empty slots in the list are shown as well,
because they can affect the visibility of subsequently planted traps.
.
.
.TP
.BI .pvs \~\[+-]n
Set the post-vertical line spacing
.RI to\~ n ;
default scaling unit
.RB is\~\[lq] p \[rq].
.
With no argument,
the post-vertical line space is set to its previous value.
.
.
.IP
In GNU
.IR troff , \" GNU
the distance between text baselines consists of the extra pre-vertical
line spacing set by the most negative
.B \[rs]x
argument on the pending output line,
the vertical spacing
.RB ( vs ),
the extra post-vertical line spacing set by the most positive
.B \[rs]x
argument on the pending output line,
and the post-vertical line spacing set by this request.
.
.
.TP
.BI .rchar\~ c\~\c
\&.\|.\|.
Remove definition of each ordinary or special character
.IR c ,
undoing the effect of a
.BR char ,
.BR fchar ,
or
.B schar
request.
.
Glyphs,
which are defined by font description files,
cannot be removed.
.
Spaces and tabs may separate
.I c
arguments.
.
.
.TP
.B .return
Within a macro,
return immediately.
.
If called with an argument,
return twice,
namely from the current macro and from the macro one level higher.
.
No effect otherwise.
.\" XXX: useless request warning?
.
.
.TP
.BI .rfschar\~ "f c\~"\c
\&.\|.\|.
Remove each fallback special
.RI character\~ c
for font
.IR f .
.
Spaces and tabs may separate
.I c
arguments.
.
See
.BR fschar .
.
.
.TP
.BR .rj\~ [\c
.IR n ]
Right-align the
.RI next\~ n
input lines.
.
Without an argument,
right-align the next input line.
.
.B rj
implies
.RB \[lq] ".ce 0" \[rq],
and
.B ce
implies
.RB \[lq] ".rj 0" \[rq].
.
.
.TP
.BI .rnn \~r1\~r2
Rename register
.I r1
to
.IR r2 .
.
If
.I r1
doesn't exist,
the request is ignored.
.
.
.TP
.BI .schar\~ c\~contents
Define global fallback character
.I c
as
.IR contents .
.
See
.BR char ;
the distinction is that a character defined with
.B schar
is located after the list of fonts declared with the
.B \%special
request but before any mounted special fonts.
.
.
.TP
.BR .shc \~\c
.RI [ c ]
Set the soft hyphen character,
inserted when a word is hyphenated automatically or at a hyphenation
character,
.RI to\~ c .
.
If
.I c
is omitted,
the soft hyphen character is set to the default,
.BR \[rs][hy] .
.
If the selected glyph does not exist in the font in use at a potential
hyphenation point,
then the line is not broken at that point.
.
Neither character definitions
.RB ( char
and similar)
nor translations
.RB ( tr
and similar)
are considered when assigning the soft hyphen character.
.
.
.TP
.BI .shift\~ n
In a macro,
shift the arguments by
.I n
positions:
.RI argument\~ i
becomes argument
.IR i \|\-\| n ;
arguments 1
.RI to\~ n
are no longer available.
.
.RI If\~ n
is missing,
arguments are shifted by\~1.
.
No effect otherwise.
.\" XXX: useless request warning?
.
.
.TP
.BI .sizes\~ "s1 s2\~"\c
.RI .\|.\|.\~ sn\~\c
.RB [ 0 ]
Set the available type sizes to
.IR s1 ,
.IR s2 ,
\&.\|.\|.\&
.I sn
scaled points.
.
The list of sizes can be terminated by an
.RB optional\~\[lq] 0 \[rq].
.
Each
.I si
can also be a range
.IR m \(en n .
.
In contrast to the device description file directive of the same name
(see
.MR groff_font 5 ),
the argument list can't extend over more than one line.
.
.
.TP
.BI .soquiet\~ file
As
.RB \[lq] so \[rq],
but no warning is emitted if
.I file
does not exist.
.
.
.TP
.BI .special\~ f\~\c
\&.\|.\|.
Declare each font
.I f
as special,
searching it for glyphs not found in the selected font.
.
Without arguments,
this list of special fonts is made empty.
.
.
.TP
.BR .spreadwarn\~ [\c
.IR limit ]
Emit a
.B break
warning if the additional space inserted for each space between words in
an output line adjusted to both margins with
.RB \[lq] .ad\~b \[rq]
is larger than or equal to
.IR limit .
.
A negative value is treated as zero;
an absent argument toggles the warning on and off without changing
.IR limit .
.
The default scaling unit is
.BR m .
.
At startup,
.B spreadwarn
is inactive and
.I limit
is 3\~m.
.
.
.IP
For example,
.RB \[lq] ".spreadwarn 0.2m" \[rq]
causes a warning if
.B break
warnings are not suppressed and
.I \%troff
must add 0.2\~m or more for each inter-word space in a line.
.
.
.TP
.BI .stringdown \~str
.TQ
.BI .stringup \~str
Alter the string named
.I str
by replacing each of its bytes with its
lowercase
.RB ( down )
or uppercase
.RB ( up )
version
(if one exists).
.
Special characters
(see
.MR groff_char 7 )
will often transform in the expected way due to the regular naming
convention for accented characters.
.
When they do not,
use substrings and/or catenation.
.
.
.IP
.RS
.RS
.EX
.B .ds resume R\e[\[aq]e]sum\e[\[aq]e]\e"
.B \e*[resume]
.B .stringdown resume
.B \e*[resume]
.B .stringup resume
.B \e*[resume]
R\['e]sum\['e] r\['e]sum\['e] R\['E]SUM\['E]
.EE
.RE
.RE
.
.
.TP
.BI .sty\~ n\~s
Associate abstract
.RI style\~ s
with font mounting
.RI position\~ n .
.
.
.TP
.BI .substring\~ "string start\~"\c
.RI [ end ]
Replace the string named
.I string
with its substring bounded by the indices
.I start
and
.IR end ,
inclusively.
.
The first character in the string has index\~0.
.
If
.I end
is omitted,
it is implicitly set to the largest valid value
(the string length minus one).
.
Negative indices count backwards from the end of the string:
the last character has index\~\-1,
the character before the last has index\~\-2,
and so on.
.
.
.RS
.IP
.EX
.B .ds xxx abcdefgh
.B .substring xxx 1 \-4
.B \e*[xxx]
bcde
.B .substring xxx 2
.B \e*[xxx]
de
.EE
.RE
.
.
.TP
.BI .tkf\~ f\~s1\~n1\~s2\~n2
Enable track kerning for font\~\c
.IR f .
When the current font is\~\c
.I f
the width of every glyph is increased by an amount between
.I n1
and
.IR n2 ;
when the current type size is less than or equal to
.I s1
the width is increased by
.IR n1 ;
when it is greater than or equal to
.I s2
the width is increased by
.IR n2 ;
when the type size is greater than or equal to
.I s1
and less than or equal to
.I s2
the increase in width is a linear function of the type size.
.
.
.TP
.BI .tm1\~ message
As
.B tm
request,
but strips a leading neutral double quote from
.I message
to allow the embedding of leading spaces.
.
.
.TP
.BI .tmc\~ message
As
.B tm1
request,
but does not append a newline.
.
.
.TP
.BI .trf\~ file
Transparently output the contents of file
.IR file .
.
Each line is output as if preceded by
.BR \[rs]! ;
however,
the lines are not subject to copy-mode interpretation.
.
If the file does not end with a newline,
then a newline is added.
.
Unlike
.BR cf ,
.I file
cannot contain characters
that are invalid as input to GNU
.IR troff . \" GNU
.
.
.IP
For example,
you can define a macro\~\c
.I x
containing the contents of file\~\c
.IR f ,
using
.
.
.RS
.IP
.ne 2v+\n(.Vu
.EX
\&.di x
\&.trf f
\&.di
.EE
.RE
.
.
.TP
.BI .trin\~ abcd
This is the same as the
.B tr
request except that the
.B asciify
request uses the character code
(if any)
before the character translation.
.
Example:
.
.
.RS
.IP
.EX
\&.trin ax
\&.di xxx
\&a
\&.br
\&.di
\&.xxx
\&.trin aa
\&.asciify xxx
\&.xxx
.EE
.RE
.
.
.IP
The result is \[lq]x\~a\[rq].
.
Using
.BR tr ,
the result would be \[lq]x\~x\[rq].
.
.
.TP
.BI .trnt\~ abcd
This is the same as the
.B tr
request except that the translations do not apply to text that is
transparently throughput into a diversion with
.BR \[rs]! .
For example,
.
.
.RS
.IP
.EX
\&.tr ab
\&.di x
\&\[rs]!.tm a
\&.di
\&.x
.EE
.RE
.
.
.IP
prints\~\c
.BR b ;
if
.B trnt
is used instead of
.B tr
it prints\~\c
.BR a .
.
.
.TP
.B .troff
Make the
.B t
conditional expression evaluate true and
.B n
false.
.
See
.BR nroff .
.
.
.TP
.BI .unformat\~ div
Unformat the diversion
.IR div .
.
Unlike
.BR asciify ,
.B unformat
handles only tabs and spaces between words,
the latter usually arising from spaces or newlines in the input.
.
Tabs are treated as input tokens,
and spaces become adjustable again.
.
The vertical sizes of lines are not preserved,
but glyph information
(font,
type size,
space width,
and so on)
is retained.
.
.
.TP
.BI .vpt\~ n
If
.I n
is non-zero or missing,
enable vertical position traps
(the default),
otherwise disable them.
.
Vertical position traps are those set by the
.BR ch ,
.BR wh ,
and
.B dt
requests.
.
.
.TP
.BR .warn\~ [\c
.IR n ]
Select the categories,
or \[lq]types\[rq],
of reported warnings.
.
.IR n \~is
the sum of the numeric codes associated with each warning category that
is to be enabled;
all other categories are disabled.
.
The categories and their associated codes are listed in section
\[lq]Warnings\[rq] of
.MR \%troff 1 .
.\" TODO: Maybe move that table to groff(7).
.
For example,
.RB \[lq] ".warn 0" \[rq]
disables all warnings,
and
.RB \[lq] ".warn 1" \[rq]
disables all warnings except those about missing glyphs.
.
If no argument is given,
all warning categories are enabled.
.
.
.TP
.BI .warnscale\~ si
Set the scaling unit used in warnings to
.IR si .
.
Valid values for
.I si
are
.BR u ,
.B i
(the default),
.BR c ,
.BR p ,
.RB and\~ P .
.
.
.TP
.BI .while \~cond-expr\~anything
Evaluate the conditional expression
.IR cond-expr ,
and repeatedly execute
.I anything
unless and until
.I cond-expr
evaluates false.
.
.I anything,
which is often a conditional block,
is referred to as the
.B while
request's
.I body.
.
.
.IP
.I \%troff
treats the body of a
.B while
request similarly to that of a
.B 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
.B while
request can slow significantly if the
.B while
body is large.
.
Each time the macro is executed,
the
.B while
body is parsed and stored again.
.
An often better solution\[em]and one that is more portable,
since AT&T
.I troff \" AT&T
lacked the
.B while
request\[em]is to instead write a recursive macro.
.
It will be parsed only once (unless you redefine it).
.
To prevent infinite loops,
the default number of available recursion levels is 1,000 or somewhat
less (because things other than macro calls can be on the input stack).
.
You can disable this protective measure,
or raise the limit,
by setting the
.B slimit
register.
.
See section \[lq]Debugging\[rq] below.
.
.
.IP
If a
.B while
body begins with a conditional block,
its closing brace must end an input line.
.
.
.IP
The
.B break
and
.B continue
requests alter a
.B while
loop's flow of control.
.
.
.TP
.BI .write\~ stream\~anything
Write
.I anything
to
.IR stream ,
which must previously have been the subject of an
.B open
request,
followed by a newline.
.
.I anything
is read in copy mode.
.
An initial neutral double quote in
.I anything
is stripped to allow the embedding of leading spaces.
.
.
.TP
.BI .writec\~ stream\~anything
As
.BR write ,
but without a trailing newline.
.
.
.TP
.BI .writem\~ "stream name"
Write the contents of the macro or string
.I name
to
.IR stream ,
which must previously have been the subject of an
.B open
request.
.
.I name
is read in copy mode.
.
.
.br
.ne 6v
.\" ====================================================================
.SS "Extended requests"
.\" ====================================================================
.
.\" XXX: .cf might better belong in "Implementation differences".
.TP
.BI .cf\~ file
In a diversion,
embed an object which,
when reread,
will cause the contents of
.I file
to be copied verbatim to the output.
.
In AT&T
.IR troff ,
the contents of
.I file
are immediately copied to the output regardless of whether a diversion
is being written to;
this behavior is so anomalous that it must be considered a bug.
.
.
.TP
.BI .de\~ name\~\c
.RI [ end-name ]
.TQ
.BI .am\~ name\~\c
.RI [ end-name ]
.TQ
.BI .ds\~ name\~\c
.RI [ contents ]
.TQ
.BI .as\~ name\~\c
.RI [ contents ]
In compatibility mode,
these requests behave similarly to
.BR de1 ,
.BR am1 ,
.BR ds1 ,
and
.BR as1 ,
respectively:
a \[lq]compatibility save\[rq] token is inserted at the beginning,
and a \[lq]compatibility restore\[rq] token at the end,
with compatibility mode switched on during execution.
.
.
.TP
.BI .hy\~ n
New values 16 and\~32 are available;
the former enables hyphenation before the last character in a word,
and the latter enables hyphenation after the first character in a word.
.
.
.TP
.BI .ss\~ word-space-size\~\c
.RI [ additional-sentence-space-size ]
A second argument sets the amount of additional space separating
sentences on the same output line.
.
If omitted,
this amount is set to
.IR word-space-size .
.
Both arguments are in twelfths of current font's space width
(typically one-fourth to one-third em for Western scripts;
see
.MR groff_font 5 ).
.
The default for both parameters is\~12.
.
Negative values are erroneous.
.
.
.TP
.BR .ta\~ [[\c
.IR "n1 n2\~" .\|.\|.\~ nn \~]\c
.BR T \~\c \" space in roman because we must use 2-font macro with \c
.IR "r1 r2\~" .\|.\|.\~ rn ]
.I groff
supports an extended syntax to specify repeating tab stops after
the
.RB \[lq] T \[rq]
mark.
.
These values are always taken as relative distances from the previous
tab stop.
.
This is the idiomatic way to specify tab stops at equal intervals in
.IR groff .
.
.
.IP
The syntax summary above instructs
.I groff
to set tabs at positions
.IR n1 ,
.IR n2 ,
\&.\|.\|.\|,
.IR nn ,
then at
.IR nn \|+\| r1 ,
.IR nn \|+\| r2 ,
\&.\|.\|.\|,
.IR nn \|+\| rn ,
then at
.IR nn \|+\| rn \|+\| r1 ,
.IR nn \|+\| rn \|+\| r2 ,
\&.\|.\|.\|,
.IR nn \|+\| rn \|+\| rn ,
and so on.
.
.
.\" ====================================================================
.SS "New registers"
.\" ====================================================================
.
GNU
.I troff \" GNU
exposes more formatter state via many new read-only registers.
.
Their names often correspond to the requests that affect them.
.
.
.TP 12n
.B \[rs]n[.br]
Within a macro call,
interpolate\~1
if the macro is called with the \[lq]normal\[rq] control character
(\[lq].\[rq] by default),
and\~0 otherwise.
.
This facility allows the reliable modification of requests.
.
Using this register outside of a macro definition makes no sense.
.
.
.RS
.IP
.ne 6v+\n(.Vu
.EX
\&.als bp*orig bp
\&.de bp
\&.tm before bp
\&.ie \[rs]\[rs]n[.br] .bp*orig
\&.el \[aq]bp*orig
\&.tm after bp
\&..
.EE
.RE
.
.
.TP
.B \[rs]n[.C]
Interpolate 1\~if compatibility mode is in effect,
0\~otherwise.
.
See
.BR cp .
.
.
.TP
.B \[rs]n[.cdp]
Interpolate depth of last glyph added to the environment.
.
It is positive if the glyph extends below the baseline.
.
.
.TP
.B \[rs]n[.ce]
Interpolate number of input lines remaining to be centered.
.
.
.TP
.B \[rs]n[.cht]
Interpolate height of last glyph added to the environment.
.
It is positive if the glyph extends above the baseline.
.
.
.TP
.B \[rs]n[.color]
Interpolate 1\~if colors are enabled,
0\~otherwise.
.
.
.TP
.B \[rs]n[.cp]
Within a
.RB \[lq] do \[rq]
request,
interpolate the saved value of compatibility mode
(see
.B \[rs]n[.C]
above).
.
.
.TP
.B \[rs]n[.csk]
Interpolate skew of last glyph added to the environment.
.
The
.I skew
of a glyph is how far to the right of the center of a glyph the center
of an accent over that glyph should be placed.
.
.
.TP
.B \[rs]n[.ev]
Interpolate name of current environment.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.fam]
Interpolate name of default font family.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.fn]
Interpolate resolved name of the selected font.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.fp]
Interpolate next free font mounting position.
.
.
.TP
.B \[rs]n[.g]
Interpolate\~1.
.
Test with
.RB \[lq]\| if \|\[rq]
or
.B ie
to check whether GNU
.I troff \" GNU
is the formatter.
.
.
.TP
.B \[rs]n[.height]
Interpolate font height.
.
See
.BR \[rs]H .
.
.
.TP
.B \[rs]n[.hla]
Interpolate hyphenation language of the environment.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.hlc]
Interpolate count of immediately preceding consecutive hyphenated lines
in the environment.
.
.
.TP
.B \[rs]n[.hlm]
Interpolate maximum number of consecutive hyphenated lines allowed in
the environment.
.
.
.TP
.B \[rs]n[.hy]
Interpolate hyphenation mode of the environment.
.
.
.TP
.B \[rs]n[.hym]
Inteprolate hyphenation margin of the environment.
.
.
.TP
.B \[rs]n[.hys]
Interpolate hyphenation space adjustment threshold of the environment.
.
.
.TP
.B \[rs]n[.in]
Interpolate indentation amount applicable to the pending output line.
.
.
.TP
.B \[rs]n[.int]
Interpolate\~1 if the previous output line was interrupted
(ended with
.BR \[rs]c ),
0\~otherwise.
.
.
.TP
.B \[rs]n[.kern]
Interpolate\~1 if pairwise kerning is enabled,
0\~otherwise.
.
.
.TP
.B \[rs]n[.lg]
Interpolate ligature mode.
.
.
.TP
.B \[rs]n[.linetabs]
Interpolate\~1 if line-tabs mode is enabled,
0\~otherwise.
.
.
.TP
.B \[rs]n[.ll]
Interpolate line length applicable to the pending output line.
.
.
.TP
.B \[rs]n[.lt]
Interpolate title line length.
.
.
.TP
.B \[rs]n[.m]
Interpolate name of the selected stroke color.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.M]
Interpolate name of the selected fill color.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.ne]
Interpolate amount of space demanded by the most recent
.B ne
request that caused a page location trap to be sprung.
.
See
.BR \[rs]n[.trunc] .
.
.
.TP
.B \[rs]n[.nm]
Interpolate\~1 if output line numbering is enabled
(even if temporarily suppressed),
0\~otherwise.
.
.
.TP
.B \[rs]n[.ns]
Interpolate\~1 if no-space mode is enabled,
0\~otherwise.
.
.
.TP
.B \[rs]n[.O]
Interpolate output suppression level.
.
See
.BR \[rs]O .
.
.
.TP
.B \[rs]n[.P]
Interpolate\~1 if the current page is selected for output.
.
See
.B \-o
command-line option to
.MR \%troff 1 .
.
.
.TP
.B \[rs]n[.pe]
Interpolate\~1 during page ejection,
0\~otherwise.
.
.
.TP
.B \[rs]n[.pn]
Interpolate next page number
(either that set by
.BR pn ,
or that of the current page plus\~1).
.
.
.TP
.B \[rs]n[.ps]
Interpolate type size in scaled points.
.
.
.TP
.B \[rs]n[.psr]
Interpolate most recently requested type size in scaled points.
.
.
.TP
.B \[rs]n[.pvs]
Interpolate post-vertical line spacing amount.
.
.
.TP
.B \[rs]n[.rj]
Interpolate number of input lines remaining to be right-aligned.
.
.
.TP
.B \[rs]n[.slant]
Interpolate font slant.
.
See
.BR \[rs]S .
.
.
.TP
.B \[rs]n[.sr]
Interpolate most recently requested type size in points as a decimal
fraction.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.ss]
.TQ
.B \[rs]n[.sss]
Interpolate values of minimal inter-word space and additional
inter-sentence space,
respectively,
in twelfths of the space width of the selected font.
.
.
.TP
.B \[rs]n[.sty]
Interpolate selected abstract font style,
if any.
.
This is a string-valued register.
.
.
.TP
.B \[rs]n[.tabs]
Interpolate representation of the tab stop settings in a form suitable
for passage to the
.B ta
request.
.
.
.TP
.B \[rs]n[.trunc]
Interpolate amount of vertical space truncated by the most recently
sprung page location trap,
or,
if the trap was sprung by an
.B ne
request,
minus the amount of vertical motion produced by the
.B ne
request.
.
In other words,
at the point a trap is sprung,
.B \[rs]n[.trunc]
represents the difference of what the vertical position would have
been but for the trap,
and what the vertical position actually is.
.
See
.BR \[rs]n[.ne] .
.
.
.TP
.B \[rs]n[.U]
Interpolate\~1 if in unsafe mode,
0\~otherwise.
.
See
.B \-U
command-line option to
.MR \%troff 1 .
.
.
.TP
.B \[rs]n[.vpt]
Interpolate\~1 if vertical position traps are enabled,
0\~otherwise.
.
.
.TP
.B \[rs]n[.warn]
Interpolate warning mode.
.
See section \[lq]Warnings\[rq] of
.MR \%troff 1 .
.\" TODO: Maybe move that table to groff(7).
.
.
.TP
.B \[rs]n[.x]
Interpolate major version number of the running
.I \%troff
formatter.
.
For example,
if the version number is 1.23.0,
then
.B \[rs]n[.x]
contains\~1.
.
.
.TP
.B \[rs]n[.y]
Interpolate minor version number of the running
.I \%troff
formatter.
.
For example,
if the version number is 1.23.0,
then
.B \[rs]n[.y]
contains\~23.
.
.
.TP
.B \[rs]n[.Y]
Interpolate revision number of the running
.I \%troff
formatter.
.
For example,
if the version number is 1.23.0,
then
.B \[rs]n[.Y]
contains\~0.
.
.
.TP
.B \[rs]n[.zoom]
Interpolate magnification of font,
in thousandths,
or\~0 if magnification unused.
.
See
.BR fzoom .
.
.
.P
The following (writable) registers are set by the
.B psbb
request.
.
.
.TP
.B \[rs]n[llx]
.TQ
.B \[rs]n[lly]
.TQ
.B \[rs]n[urx]
.TQ
.B \[rs]n[ury]
Interpolate the
(upper,
lower,
left,
right)
bounding box values
(in PostScript units) of the most recently processed PostScript image.
.
.
.P
The following (writable) registers are set by the
.B \[rs]w
escape sequence.
.
.
.TP 8n
.B \[rs]n[rst]
.TQ
.B \[rs]n[rsb]
Like
.B \[rs]n[st]
and
.BR \[rs]n[sb] ,
but taking account of the heights and depths of glyphs.
.
In other words,
these registers store the highest and lowest vertical positions attained
by the argument formatted by the
.B \[rs]w
escape sequence,
doing what AT&T
.I troff \" AT&T
documented
.B \[rs]n[st]
and
.B \[rs]n[sb]
as doing.
.
.
.TP
.B \[rs]n[ssc]
The amount of horizontal space (possibly negative) that should be
added to the last glyph before a subscript.
.
.
.TP
.B \[rs]n[skw]
How far to right of the center of the last glyph in the
.B \[rs]w
argument,
the center of an accent from a roman font should be placed
over that glyph.
.
.
.P
Other writable registers are as follows.
.
Those relating to date and time are initialized using
.MR localtime 3
at formatter startup.
.
.
.\" The `c.` register was documented in the January 1981 "Addendum to
.\" the Nroff/Troff User's Manual" (presumably by Kernighan), and is
.\" widely supported by descendants of his device-independent troff, but
.\" appears to have been overlooked in his 1992 revision of CSTR #54.
.TP 12n
.B \[rs]n[c.]
Interpolate input line number.
.
.B \[rs]n[.c]
is a read-only alias of this register.
.
.
.TP
.B \[rs]n[hours]
Interpolate number of hours elapsed since midnight.
.
.
.TP
.B \[rs]n[hp]
Interpolate horizontal position relative to that at the start of the
input line.
.
.
.br
.ne 3v
.TP
.B \[rs]n[lsn]
.TQ
.B \[rs]n[lss]
Interpolate count of leading spaces on input line and amount of
corresponding horizontal motion,
respectively.
.
.
.TP
.B \[rs]n[minutes]
Interpolate number of minutes elapsed in the hour.
.
.
.TP
.B \[rs]n[seconds]
Interpolate number of seconds elapsed in the minute.
.
.
.TP
.B \[rs]n[systat]
Interpolate return value of
.MR system 3
function executed by most recent
.B sy
request.
.
.
.TP
.B \[rs]n[slimit]
Interpolates maximum quantity of objects on
.IR \%troff 's
internal input stack
(default: 1000).
.
If non-positive,
there is no limit:
recursion can continue until program memory is exhausted.
.
.
.TP
.B \[rs]n[year]
Interpolate Gregorian year.
.
AT&T
.IR troff 's \" AT&T
.B \[rs][yr]
interpolates the Gregorian year minus 1900.
.
.
.\" ====================================================================
.SS Miscellaneous
.\" ====================================================================
.
GNU
.I troff \" GNU
predefines one string,
.BR .T ,
containing the argument given to the
.B \-T
command-line option,
namely the output device
(for example,
.B pdf
or
.BR utf8 ).
.
The (read-only)
.I register
.B .T
interpolates\~1 if GNU
.I troff \" GNU
is run with the
.B \-T
command-line option,
and 0\~otherwise.
.
.
.P
A font not listed in the output device's
.I DESC
file's
.B fonts
directive is automatically mounted at the next available font position
when it is selected.
.
If you mount a font explicitly with the
.B fp
request,
you should do so on the first unused position,
which can be found in the
.B .fp
register.
.
.
.P
Unparameterized string interpolation does not conceal the arguments to a
macro being interpreted.
.
Thus,
in a macro definition,
the call of another macro with the existing argument list,
.
.RS
.EX
.BI . xx\~ \[rs]\[rs]$@
.EE
.RE
.
is more efficiently done with
.
.RS
.EX
.BI \[rs]\[rs]*[ xx ]\[rs]\[rs]
.EE
.RE
.
(that is,
with string interpolation).
.
The trailing backslashes prevent the final newline in the macro
definition from being interpolated,
potentially putting an unwanted blank line on the output.
.
See section \[lq]Punning Names\[rq] in
.MR groff 7 .
.
.
.\" XXX: Is this really not an AT&T troff feature?
.P
If a font description file contains pairwise kerning information,
glyphs from that font are kerned.
.
Kerning between two glyphs can be inhibited by placing a dummy character
.B \[rs]&
between them.
.
.
.P
GNU
.I troff \" GNU
keeps track of the nesting depth of escape sequence
interpolations and other uses of delimiters,
as in the
.B tl
request and the output comparison operator
(that is,
input like
.B \[aq]foo\[aq]bar\[aq]
as a conditional expression),
so the only characters you need to avoid using as
delimiters are those that appear in the arguments you input,
not any that result from interpolation.
.
Typically,
.B \[aq]
works fine.
.
Use visible characters as delimiters in GNU
.IR troff , \" GNU
not \[lq]ASCII\[rq] controls like BEL (Control+G).
.
The implementation of
.B \[rs]$@
ensures that the double quotes surrounding an argument appear at an
interpolation depth different from that of the arguments themselves.
.
Similarly,
in bracket-form escape sequences like
.B \[rs]f[ZCMI],
a right bracket
.B ]
does not end the sequence unless it occurs at the same interpolation
depth as the
.RB opening\~ [ ,
so input like
.
.RS
.EX
\[rs]f[\[rs]*[my-family]\[rs]*[my-style]]
.EE
.RE
.
works as desired.
.
In compatibility mode,
no attention is paid to the interpolation depth.
.
.
.P
In
GNU
.IR troff , \" GNU
the
.B tr
request can map characters to the unbreakable space escape sequence
.B \[rs]\[ti]
as a special case
.RB ( tr
normally operates only on
.IR characters ).
.
This feature replaces the odd-parity
.B tr
mapping trick used in AT&T
.I troff \" AT&T
documents,
where a character,
often
.BR \[ti] ,
was \[lq]sacrificed\[rq] by mapping it to \[lq]nothing\[rq],
drafting it into use as an unadjustable,
unbreakable space.
.
(This feature was gratuitous even in early AT&T
.I troff, \" AT&T
which supported the
.BI \[rs] space
escape sequence by 1976.) \" see CSTR #54 of that year
.
Often,
it makes more sense to use
GNU
.IR troff 's \" GNU
.B \[rs]\[ti]
escape sequence instead,
which has been adopted by every other active
.I troff
implementation except that of Illumos,
as well as by the
.RI non -troff
.IR mandoc .
.
Translation of a character to
.B \[rs]\[ti]
is unnecessary.
.
.
.P
GNU
.I troff \" GNU
permits tabs and spaces after the first dot on a control line that ends
a macro definition.
.
.RS
.ne 5v+\n(.Vu
.EX
\&.if t \[rs]{\[rs]
\&.\&  de bar
\&.\&    nop Hello, I\[aq]m \[aq]bar\[aq].
\&.\&  .
\&.\[rs]}
.EE
.RS
.
.
.\" ====================================================================
.SH "Formatter output"
.\" ====================================================================
.
The page description language output by GNU
.I troff \" GNU
is modeled after that used by AT&T
.I troff \" AT&T
once the latter adopted a device-independent approach in the early
1980s.
.
Only the differences are documented here.
.
For a fuller discussion,
see
.MR groff_out 5 .
.\"
.\"
.\" XXX: This feature is unused and documenting it gives a valuable
.\" hostage to fortune.
.\".P
.\"Note that single characters can have the eighth bit set, as can the
.\"names of fonts and special characters.
.
.
.P
Glyph and font names can be of arbitrary length;
postprocessors should not assume that they are at most two characters.
.
A glyph to be formatted is always drawn from the current font;
in contrast to AT&T device-independent
.IR troff , \" AT&T
drivers need not search special fonts to find a glyph.
.
.
.\" ====================================================================
.SS Units
.\" ====================================================================
.
The argument to the
.BR s \~command
is in scaled points
(units of
.RI points/ n ,
where
.I n
is the argument to the
.B sizescale
command in the
.I DESC
file).
.
The argument to the
.RB \[lq] "x H" \[rq]
command is also in scaled points.
.
.
.\" ====================================================================
.SS "Simple commands"
.\" ====================================================================
.
.\" BEGIN Keep in sync with relevant portions of section "Simple
.\" commands" from groff_out(5).
.P
If the
.B tcommand
directive is present in the output device's
.I DESC
file,
GNU
.I troff \" GNU
employs the following two commands.
.
.
.TP
.BI t\~ xyz\c
\&.\|.\|.
Typeset word
.IR xyz ;
that is,
set a sequence of ordinary glyphs named
.IR x ,
.IR y ,
.IR z ,
\&.\|.\|.\|,
terminated by a space or newline;
an optional second integer argument is ignored
(this allows the formatter to generate an even number of arguments).
.\" XXX: Why?
.
Each glyph is set at the current drawing position,
and the position is then advanced horizontally by the glyph's width.
.
A glyph's width is read from its metrics in the font description file,
scaled to the current type size,
and rounded to a multiple of the horizontal motion quantum.
.
Use the
.B C
command to emplace glyphs of special characters.
.
.
.TP
.BI u\~ "n xyz"\c
\&.\|.\|.
Typeset word
.I xyz
with track kerning.
.
As
.BR t ,
but after placing each glyph,
the drawing position is further advanced horizontally
.RI by\~ n
basic units.
.\" END Keep in sync with relevant portions of section "Simple commands"
.\" from groff_out(5).
.
.
.P
New commands implement color support.
.
.
.TP
.BI mc\~ "cyan magenta yellow"
.TQ
.B md
.TQ
.BI mg\~ gray
.TQ
.BI mk\~ "cyan magenta yellow black"
.TQ
.BI mr\~ "red green blue"
Set the components of the stroke color with respect to various color
spaces.
.
.B md
resets the stroke color to the default value.
.
The arguments are integers in the range 0 to 65535.
.
.
.P
A new device control subcommand is available.
.
.
.TP
.BI "x u\~" n
If
.I n
is\~1,
start underlining of spaces.
.
If
.I n
is\~0,
stop underlining of spaces.
.
This facility is needed for the
.B cu
request in
.I nroff \" mode
mode and is ignored otherwise.
.
.
.\" ====================================================================
.SS "Extended drawing commands"
.\" ====================================================================
.
GNU
.I pic \" GNU
does not produce
.I \%troff
escape sequences employing these extensions if its
.B \-n
option is given.
.
.
.TP
.BI Df\~ n
Set the shade of gray used to fill geometric objects to
.IR n ,
which must be an integer.
.
0 corresponds to white and 1000 to black.
.
A grayscale ramp spans the two.
.
A value outside this range uses the stroke color as the fill color.
.
The fill color is opaque.
.
Normally the default is black,
but some drivers may provide a way of changing this.
.
.B Df
is obsolete since 2002, \" commit ea5a42d080, 2002-01-24
superseded by
.B DFg
below.
.
.
.IP
The corresponding
.B \[rs]D\[aq]f\^\[aq]
escape sequence should not be used:
its argument is rounded to an integer multiple of the horizontal motion
quantum,
which can limit the precision
.RI of\~ n .
.
.
.TP
.BI DC\~ d
Draw a filled circle of diameter
.I d
with its leftmost point at the drawing position.
.
.
.TP
.BI DE\~ "h v"
Draw a filled ellipse,
of horizontal axis
.I h
and vertical axis
.IR v ,
with its leftmost point at the drawing position.
.
.
.br
.ne 4v
.EQ
delim $$
.EN
.TP
.\" `BR`, not `BI`, here, because eqn will take care of font changes.
.BR Dp\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$"
Draw a polygon with,
for $i = 1 , ldots , n + 1$,
its
.IR i th
vertex at the drawing position
.
$+ sum from { j = 1 } to { i - 1 } ( dx sub j , dy sub j )$.
.
.\" The following is implied by the math above, but let's be kind.
.I groff
output drivers automatically close polygons,
drawing a line from $( dx sub n , dy sub n )$ back to
$( dx sub 1 , dy sub 1 )$.
.
The drawing position is left at the last
.I specified
vertex,
but this may change in a future version of GNU
.IR troff . \" GNU
.
Heirloom Doctools
.IR troff , \" Heirloom
like DWB
.IR troff , \" DWB
by default does not close the polygon.
.
In its
.I groff
compatibility mode,
Heirloom closes the polygon but leaves the drawing position
.IR unchanged \[em]that
is,
at the polygon's
.I initial
drawing position.
.
.
.IP
At the moment,
GNU
.I pic \" GNU
uses this command only to generate triangles and rectangles.
.
.
.TP
.BR DP\~ "$dx sub 1 ~ dy sub 1 ~ ldots ~ dx sub n ~ dy sub n$"
As
.BR Dp ,
but draw a filled rather than a stroked polygon.
.
.
.TP
.BI Dt\~ n
Set the line thickness to
.IR n \~\c
basic units.
.
AT&T
.I troff \" AT&T
output drivers use a thickness proportional to the type size;
this is the GNU
.I troff \" GNU
default.
.
A
.RI negative\~ n
requests this explicitly.
.
.RI An\~ n
of zero selects the smallest available line thickness.
.
.
.P
A difficulty arises in how the drawing position should be changed after
the execution of these commands.
.
This has little importance to most users,
since the output of GNU
.I grn \" GNU
and
.I pic \" GNU
does not depend on it.
.
Given a drawing command of the form
.BI D z
$x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$,
where
.I z
is not
.B c
or
.BR e ,
AT&T
.I troff \" AT&T
treats each $x sub i$ as a horizontal motion,
each $y sub i$ as a vertical one,
and therefore assumes that the width of the drawn object is
$sum from { i = 1 } to n x sub i$,
and its height is $sum from { i = 1 } to n y sub i$.
.
(Verify its assumption about height by examining the
.B st
and
.B sb
registers after using such a drawing command in a
.B \[rs]w
escape sequence).
.
For the sake of compatibility,
GNU
.I troff \" GNU
also follows this rule,
even though it frustrates extensions to the
.B D
command that set drawing parameters rather than rendering objects,
producing ugly results in the case of
.B Dt
and
.BR Df ,
or otherwise don't parameterize objects as a series of vertices,
as with
GNU
.IR troff 's \" GNU
filled ellipse,
.BR DE .
.
Thus after executing a
.BR D \~command
of the form
.BI D z
$x sub 1 ~ y sub 1 ~ ldots ~ x sub n ~ y sub n$,
the drawing position should be increased by
.
$( sum from { i = 1 } to n x sub i , sum from { i = 1 } to n y sub i )$.
.EQ
delim off
.EN
.
In a future release,
GNU
.I troff \" GNU
and its output drivers may abandon the application of this assumption to
drawing commands not explicitly specified in the AT&T \[lq]Troff User's
Manual\[rq].
.
.
.P
Fill color selection is implemented with another set of extensions.
.
.
.TP
.BI DFc\~ "cyan magenta yellow"
.TQ
.B DFd
.TQ
.BI DFg\~ gray
.TQ
.BI DFk\~ "cyan magenta yellow black"
.TQ
.BI DFr\~ "red green blue"
Set the components of the fill color as described under the
.B \[rs]M
escape sequence above.
.
.B DFd
restores the device's default fill color.
.
The drawing position is not updated,
in contrast to
.BR Df .
.
.
.\" ====================================================================
.SS "Device control syntax extension"
.\" ====================================================================
.
GNU
.I troff \" GNU
introduces a line continuation convention,
permitting the argument to the
.B x X
command to contain newlines.
.
A newline in the input is transformed to the sequence
.RI \[lq] newline\c
.BR + \[rq].
.
When interpreting an
.B x X
command,
a postprocessor should therefore be prepared for a plus sign after a
newline;
if it occurs,
preserve the newline,
discard the plus sign,
and continue to collect the input into the argument of the
.B x X
command.
.
A newline
.I not
followed by a plus sign terminates the
.B x X
command.
.
An application of this feature is the embedding of PostScript or PDF
language command streams into
.I troff \"
output.
.
.
.P
GNU
.I troff \" GNU
guarantees that the first three output commands it emits are as follows.
.
.
.P
.RS
.EX
.RI x\~T\~ device
.RI x\~res\~ n\~h\~v
x init
.EE
.RE
.
.
.br
.ne 4v
.\" ====================================================================
.SH Debugging
.\" ====================================================================
.
In addition to AT&T
.IR troff 's \" AT&T
debugging features,
GNU
.I troff \" GNU
emits more error diagnostics when syntactical or semantic nonsense is
encountered and supports several warning categories;
the output of these can be selected with
.BR warn .
.
Also see the
.BR \-E ,
.BR \-w ,
and
.B \-W
options of
.MR \%troff 1 .
.
Backtraces can be automatically produced when errors or warnings occur
(the
.B \-b
option of
.MR \%troff 1 )
or generated on demand
.RB ( backtrace ).
.
.
.P
.I groff
also adds more flexible diagnostic output requests
.RB ( tmc
and
.BR tm1 ).
.
More aspects of formatter state can be examined with requests that write
lists of
defined registers
.RB ( pnr ),
environments
.RB ( pev ),
and page location traps
.RB ( ptr )
to the standard error stream.
.
.
.\" ====================================================================
.SH "Implementation differences"
.\" ====================================================================
.
.\" TODO: Resync with the node of this name in our Texinfo manual.
GNU
.IR troff 's \" GNU
features sometimes cause incompatibilities with documents written
assuming old implementations of
.IR troff . \" generic
.
Some GNU extensions to
.I troff \" generic
are supported by other implementations.
.
.
.P
When adjusting to both margins,
AT&T
.I troff \" AT&T
at first adjusts spaces starting from the right;
GNU
.I troff \" GNU
begins from the left.
.
Both implementations adjust spaces from opposite ends on alternating
output lines to prevent \[lq]rivers\[rq] in the text.
.
.
.P
GNU
.I troff \" GNU
does not always hyphenate words as AT&T
.I troff \" AT&T
does.
.
The AT&T implementation uses a set of hard-coded rules specific to
U.S.\& English,
while GNU
.I troff \" GNU
uses language-specific hyphenation pattern files derived from \*[tx].
.
In some versions of
.I troff \" generic
there was limited space to store hyphenation exceptions
(arguments to the
.B hw
request);
GNU
.I troff \" GNU
has no such restriction.
.
.
.P
Long names may be GNU
.IR troff 's \" GNU
most obvious innovation.
.
AT&T
.I troff \" AT&T
interprets
.RB \[lq] .dsabcd \[rq]
as defining a string
.RB \[lq] ab \[rq]
with contents
.RB \[lq] cd \[rq].
.
Normally,
GNU
.I troff \" GNU
interprets this as a call of a macro named
.RB \[lq] dsabcd \[rq].
.
AT&T
.I troff \" AT&T
also interprets
.B \[rs]*[
and
.B \[rs]n[
as an interpolation of a string or register,
respectively,
called
.RB \[lq] [ \[rq].
.
In GNU
.IR troff , \" GNU
however,
the
.RB \[lq] [ \[rq]
is normally interpreted as beginning the enclosure of a long identifier.
.
In compatibility mode,
GNU
.I troff \" GNU
interprets names in the traditional way,
which means that they are limited to one or two characters.
.
See the
.B \-C
option in
.MR \%troff 1
and,
above,
the
.B .C
and
.B .cp
registers,
and
.B cp
and
.RB \[lq] do \[rq]
requests,
for more on compatibility mode.
.
.
.P
The register
.B \[rs]n[.cp]
is specialized and may require a statement of rationale.
.
When writing macro packages or documents that use GNU
.I troff \" GNU
features and which may be mixed with other packages or documents that do
not\[em]common scenarios include serial processing of man pages or use
of the
.RB \[lq] so \[rq]
or
.B mso
requests\[em]you may desire correct operation regardless of
compatibility mode enablement in the surrounding context.
.
It may occur to you to save the existing value of
.B \[rs]n(.C
into a register,
say,
.BR _C ,
at the beginning of your file,
turn compatibility mode off with
.RB \[lq] .cp\~0 \[rq],
then restore it from that register at the end with
.RB \[lq] .cp\~\[rs]n(_C \[rq].
.
At the same time,
a modular design of a document or macro package may lead you to multiple
layers of inclusion.
.
You cannot use the same register name everywhere lest you
\[lq]clobber\[rq] the value from a preceding or enclosing context.
.
The two-character register name space of AT&T
.I troff \" AT&T
is confining and mnemonically challenging;
you may wish to use
GNU
.IR troff 's \" GNU
more capacious name space.
.
However,
attempting
.RB \[lq] ".nr _my_saved_C \[rs]n(.C" \[rq]
will not work in compatibility mode;
the register name is too long.
.
\[lq]This is exactly what
.B .do
is for,\[rq] you think,
.RB \[lq] ".do nr _my_saved_C \[rs]n(.C" \[rq].
.
The foregoing will always save zero to your register,
because
.RB \[lq] do \[rq]
turns compatibility mode
.I off
while it interprets its argument list.
.
What you need is:
.
.RS
.EX
\&.do nr _my_saved_C \[rs]n[.cp]
\&.cp 0
.EE
.RE
.
at the beginning of your file,
followed by
.RS
.EX
\&.cp \[rs]n[_my_saved_C]
\&.do rr _my_saved_C
.EE
.RE
at the end.
.
As in the C language,
we all have to share one big name space,
so choose a register name that is unlikely to collide with other uses.
.
.
.P
The existence of the
.B .T
string is a common feature of post-CSTR\~#54
.IR troff s\[em]DWB\~3.3, \" others
Solaris,
Heirloom Doctools,
and Plan\~9
.I troff \" foreign
all support it\[em]but valid values are specific to each implementation.
.
The behavior of the
.B .T
register in GNU
.I troff \" GNU
differs from AT&T
.IR troff , \" AT&T
which interpolated\~1 only if
.I nroff \" AT&T
was the formatter and was called with
.BR \-T .
.
.
.P
The
.B lf
request sets the number of the
.I current
input line in AT&T
.IR troff ,\" AT&T
and the
.I next
in GNU
.IR troff .\" GNU
.
.
.br
.ne 2v
.P
AT&T
.I troff
had only environments named
.RB \[lq] 0 \[rq],
.RB \[lq] 1 \[rq],
and
.RB \[lq] 2 \[rq].
.
In GNU
.IR troff ,
any number of environments may exist,
using any valid identifiers for their names.
.
.
.P
GNU
.I troff \" GNU
normally tracks the interpolation depth of escape sequence parameters
and other delimited structures,
but not in compatibility mode.
.
See section \[lq]Miscellaneous\[rq] above.
.
.
.P
In compatibility mode,
the escape sequences
.BR \[rs]f ,
.BR \[rs]H ,
.BR \[rs]m ,
.BR \[rs]M ,
.BR \[rs]R ,
.BR \[rs]s ,
and
.B \[rs]S
are transparent at the beginning of an input line for the purpose of
recognizing a control character,
because they modify formatter state
.RB ( \[rs]R )
or properties of the environment
(the rest)
and therefore do not create output nodes.
.
For example,
this code produces bold output in both cases,
but the text differs,
.
.RS
.EX
\&.de xx \[aq]
Hello!
\&..
\&\[rs]fB.xx\[rs]fP
.EE
.RE
.
formatting \[lq].xx\[rq] normally and \[lq]Hello!\[rq] in compatibility
mode.
.
.
.P
GNU
.I troff \" GNU
request names unrecognized by other
.I troff \" generic
implementations will likely be ignored;
escape sequences that are GNU
.I troff \" GNU
extensions are liable to format their function selector character.
.
For example,
the adjustable,
non-breaking space escape sequence
.B \[rs]\[ti]
.\" BEGIN Keep in sync with groff.texi node "Other Differences" and
.\" groff_man_style(7).
is also supported by Heirloom Doctools
.I troff \" Heirloom
050915 (September 2005),
.I mandoc
1.9.5 (2009-09-21),
.I neatroff
(commit 1c6ab0f6e,
2016-09-13),
and Plan\~9 from User Space
.I troff \" Plan 9
(commit 93f8143600,
2022-08-12),
but not by Solaris/Illumos
.IR troff s, \" Solaris/Illumos
which will render it as
.BR \[ti] .
.\" as of this writing, 2022-08-13
.\" END Keep in sync with groff.texi node "Other Differences" and
.\" groff_man_style(7).
.
.
.P
GNU
.I troff \" GNU
does not allow the use of the escape sequences
.BR \[rs]| ,
.BR \[rs]\[ha] ,
.BR \[rs]& ,
.BR \[rs]{ ,
.BR \[rs]} ,
.BI \[rs] space\c
,
.BR \[rs]\[aq] ,
.BR \[rs]\[ga] ,
.BR \[rs]\- ,
.BR \[rs]_ ,
.BR \[rs]! ,
.BR \[rs]% ,
or
.B \[rs]c
in identifiers;
AT&T
.I troff \" AT&T
does.
.
The
.B \[rs]A
escape sequence
(see subsection \[lq]Escape sequences\[rq] above)
may be helpful in avoiding their use.
.
.
.P
Normally,
the syntax form
.BI \[rs]s n
accepts only a single character
(a digit)
for
.IR n ,
consistently with other forms that originated in AT&T
.IR troff , \" AT&T
like
.BR \[rs]* ,
.BR \[rs]$ ,
.BR \[rs]f ,
.BR \[rs]g ,
.BR \[rs]k ,
.BR \[rs]n ,
and
.BR \[rs]z .
.
In compatibility mode only,
a
.RI non-zero\~ n
must be in the range 4\[en]39.
.
Legacy documents relying upon this quirk of parsing should be migrated
to another
.B \[rs]s
form.
.
[Background:
The Graphic Systems C/A/T phototypesetter
(the original device target for AT&T
.IR troff ) \" AT&T
supported only a few discrete type sizes in the range 6\[en]36 points,
so Ossanna contrived a special case in the parser to do what the user
must have meant.
.
Kernighan warned of this in the 1992 revision of CSTR\~#54 (\[sc]2.3),
and more recently,
McIlroy referred to it as a \[lq]living fossil\[rq].]
.
.
.P
Fractional type sizes cause one noteworthy incompatibility.
.
In AT&T
.I troff \" AT&T
the
.B ps
request ignores scaling units and thus
.RB \[lq] .ps\~10u \[rq]
sets the type size to 10\~points,
whereas in GNU
.I troff \" GNU
it sets the type size to
.RI 10\~ scaled
points,
which may be a much smaller measurement.
.
See subsection \[lq]Fractional type sizes and new scaling units\[rq]
above.
.
.
.P
The
.B ab
request differs from AT&T
.IR troff : \" AT&T
GNU
.I troff \" GNU
writes no message to the standard error stream if no arguments are
given,
and it exits with a failure status instead of a successful one.
.
.
.P
The
.B bp
request differs from AT&T
.IR troff : \" AT&T
GNU
.I troff \" GNU
does not accept a scaling unit on the argument,
a page number;
the former
(somewhat uselessly)
does.
.
.
.P
In AT&T
.I troff \" AT&T
the
.B pm
request reports
macro,
string,
and
diversion
sizes in units of 128-byte blocks,
and an argument reduces the report to a sum of the above in the same
units.
.
GNU
.I troff \" GNU
ignores any arguments and reports the sizes in bytes.
.
.
.P
Unlike AT&T
.IR troff , \" AT&T
GNU
.I troff \" GNU
does not ignore the
.B ss
request if the output is a terminal device;
instead,
the values of minimum inter-word and additional inter-sentence space are
each rounded down to the nearest multiple of\~12.
.
.
.P
In GNU
.I troff \" GNU
there is a fundamental difference between (unformatted) characters and
(formatted) glyphs.
.
Everything that affects how a glyph is output is stored with the glyph
node;
once a glyph node has been constructed,
it is unaffected by any subsequent requests that are executed,
including
.BR bd ,
.BR cs ,
.BR tkf ,
.BR tr ,
or
.B fp
requests.
.
Normally,
glyphs are constructed from characters immediately before the glyph is
added to an output line.
.
Macros,
diversions,
and strings are all,
in fact,
the same type of object;
they contain a sequence of intermixed character and glyph nodes.
.
Special characters transform from one to the other:
before being added to the output,
they behave as characters;
afterward,
they are glyphs.
.
A glyph node does not behave like a character node when it is processed
by a macro:
it does not inherit any of the special properties that the character
from which it was constructed might have had.
.
For example,
the input
.
.br
.ne 5v
.RS
.EX
\&.di x
\[rs]\[rs]\[rs]\[rs]
\&.br
\&.di
\&.x
.EE
.RE
.
produces
.RB \[lq]\^ \[rs]\[rs] \[rq]
in GNU
.IR troff . \" GNU
Each pair of backslashes becomes one backslash
.I glyph;
the resulting backslashes are thus not interpreted as escape
.I characters
when they are reread as the diversion is output.
.
AT&T
.I troff \" AT&T
.I would
interpret them as escape characters when rereading them and end up
printing one
.RB \[lq] \[rs] \[rq].
.
.
.P
One way to format a backslash in most documents is with the
.B \[rs]e
escape sequence;
this formats the glyph of the current escape character,
regardless of whether it is used in a diversion;
it also works in both GNU
.I troff \" GNU
and AT&T
.IR troff . \" AT&T
.
(Naturally,
if you've changed the escape character,
you need to prefix the
.RB \[lq] e \[rq]
with whatever it is\[em]and you'll likely get something other than a
backslash in the output.)
.
.
.P
The other correct way,
appropriate in contexts independent of the backslash's common use as a
.I roff
escape character\[em]perhaps in discussion of character sets or other
programming languages\[em]is the character escape
.B \[rs](rs
or
.BR \[rs][rs] ,
for \[lq]reverse solidus\[rq],
from its name in the ECMA-6 (ISO/IEC\~646) standard.
.
[This escape sequence is not portable to AT&T
.IR troff , \" AT&T
but is to its lineal descendant,
Heirloom Doctools
.IR troff ,
as of its 060716 release (July 2006).]
.
.
.P
To store an escape sequence in a diversion that is interpreted when the
diversion is reread,
either use the traditional
.B \[rs]!\&
transparent output facility,
or,
if this is unsuitable,
the new
.B \[rs]?\&
escape sequence.
.
See subsection \[lq]Escape sequences\[rq] above and sections
\[lq]Diversions\[rq] and \[lq]gtroff Internals\[rq] in
.IR "Groff: The GNU Implementation of troff" ,
the
.I groff
Texinfo manual.
.
.
.P
In the somewhat pathological case where a diversion exists containing a
partially collected line and a partially collected line at the top-level
diversion has never existed,
AT&T
.I troff
will output the partially collected line at the end of input;
GNU
.I troff \" GNU
will not.
.
.
.\" ====================================================================
.SS "Formatter output incompatibilities"
.\" ====================================================================
.
Its extensions notwithstanding,
the
.I groff
intermediate output format has some incompatibilities
with that of AT&T
.IR troff , \" AT&T
but better compatibility is sought;
problem reports and patches are welcome.
.
The following incompatibilities are known.
.
.
.IP \[bu] 2n
The drawing position after rendering polygons is inconsistent with AT&T
.I troff \" AT&T
practice.
.
Other implementations have diverged on this point as well.
.
.
.IP \[bu]
The output cannot be easily rescaled to other devices as AT&T
.IR troff 's \" AT&T
could.
.\" XXX: Why?  What's the problem?  sizescale?  That could be written
.\" into the output as a comment or x command.  --GBR
.
.
.\" ====================================================================
.SH Authors
.\" ====================================================================
.
This document was written by
.MT jjc@\:jclark\:.com
James Clark
.ME ,
.MT wl@\:gnu\:.org
Werner Lemberg
.ME ,
.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.ME ,
and
.MT g.branden\:.robinson@\:gmail\:.com
G.\& Branden Robinson
.ME .
.
.
.\" ====================================================================
.SH "See also"
.\" ====================================================================
.
.IR "Groff: The GNU Implementation of troff" ,
by Trent A.\& Fisher and Werner Lemberg,
is the primary
.I groff
manual.
.
You can browse it interactively with \[lq]info groff\[rq].
.
.
.br
.ne 4v
.P
\[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 output format
referred to collectively in
.I groff
documentation as AT&T
.IR troff . \" AT&T
.
.
.P
\[lq]A Typesetter-independent TROFF\[rq]
by Brian W.\& Kernighan,
1982,
AT&T Bell Laboratories Computing Science Technical Report No.\& 97,
provides additional insights into the
device and font description file formats
and output format.
.
.
.P
.MR groff 1 ,
.MR groff 7 ,
.MR roff 7
.
.
.\" Clean up.
.rm tx
.rm ic
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_diff_7_man_C]
.do rr *groff_groff_diff_7_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: