path: root/man/groff.7.man

'\" t
.TH groff @MAN7EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
groff \- GNU roff language reference
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 2000-2018, 2020-2021 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_7_man_C \n[.cp]
.cp 0
.
.
.\" ====================================================================
.\" Setup
.\" ====================================================================
.
.
.\" ====================================================================
.\" start of macro definitions
.
.de TPx
.  TP 10n
..
.\" ====================================================================
.\" .Text anything ...
.\"
.\" All arguments are printed as text.
.\"
.de Text
.  nop \)\\$*
..
.
.\" ========= command=line option =========
.
.de option
.  Text \f[CB]\\$*
.  ft P
..
.
.\" ========= characters =========
.
.de squoted_char
.  Text \[oq]\f[CB]\\$1\f[]\[cq]\\$2
..
.de dquoted_char
.  Text \[lq]\f[CB]\\$1\f[]\[rq]\\$2
..
.\" ========= requests =========
.
.\" synopsis of a request
.de REQ
.  ie \\n[.$]=1 \{\
.    Text \f[CB]\\$1\f[]
.  \}
.  el \{\
.    Text \f[CB]\\$1\~\f[]\f[I]\\$2\f[]
.  \}
..
.
.\" reference of a request
.de request
.  ie (\\n[.$] < 2) \
.    B \\$*
.  el \
.    BR \\$*
..
.
.\" ========= numerical elements =========
.
.\" number with a trailing unit
.de scalednumber
.  Text \\$1\^\f[CB]\\$2\f[]\\$3\f[R]
.  ft P
..
.
.\" representation of units within the text
.de scaleindicator
.  Text \f[CB]\\$1\f[]\\$2\f[R]
.  ft P
..
.
.\" representation of mathematical operators within the text
.de operator
.  squoted_char \\$@
..
.
.
.\" ========= escape sequences =========
.
.\" ====================================================================
.\" .ESC name [arg]
.\"
.\" Synopsis of an escape sequence, optionally with argument
.\" Args   : 1 or 2; 'name' obligatory, 'arg' optional
.\"   name : suitable name for an escape sequence (c, (xy, [long])
.\"   arg  : arbitrary word
.\" Result : prints \namearg, where 'name' is in CB, 'arg' in I
.\"
.de ESC
.  Text "\f[CB]\e\\$1\,\f[I]\\$2\/\fR"
..
.\" ====================================================================
.\" .ESC[] name arg
.\"
.\" Synopsis for escape sequence with a bracketed long argument
.\" Args   : 2 obligatory
.\"   name : suitable name for an escape sequence (c, (xy, [long])
.\"   arg  : arbitrary text
.\" Result : prints \name[arg], where 'name' is in CB, 'arg' in I
.\"
.de ESC[]
.  Text "\f[CB]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[rB]\f[]"
..
.\" ====================================================================
.\" .ESCq name arg
.\"
.\" Synopsis for escape sequence with a bracketed long argument
.\" Args   : 2 obligatory
.\"   name : suitable name for an escape sequence (c, (xy, [long])
.\"   arg  : arbitrary text
.\" Result : prints \name'arg', where 'name' is in CB, 'arg' in I
.\"
.de ESCq
.  Text "\f[CB]\e\\$1\[aq]\f[]\,\f[I]\\$2\/\f[]\f[CB]\[aq]\f[]"
..
.\" ====================================================================
.\" .ESC? arg
.\"
.\" Synopsis for escape sequence with a bracketed long argument
.\" Args   : 1 obligatory
.\"   arg  : arbitrary text
.\" Result : prints '\?arg?', where the '?' are in CB, 'arg' in I
.\"
.de ESC?
.  Text "\f[CB]\e?\,\f[I]\\$1\/\f[CB]?\f[R]"
..
.\" ====================================================================
.\" .esc name [punct]
.\"
.\" Reference of an escape sequence (no args), possibly punctuation
.\" Args    : 1 obligatory
.\"   name  : suitable name for an escape sequence (c, (xy, [long])
.\"   punct : arbitrary
.\" Result  : prints \name, where 'name' is in B, 'punct' in R
.\"
.de esc
.  ie (\\n[.$] < 2) \
.    B "\e\\$1"
.  el \
.    BR "\e\\$1" \\$2
..
.\" ====================================================================
.\" .escarg name arg [punct]
.\"
.\" Reference of an escape sequence (no args)
.\" Args    : 1 obligatory, 1 optional
.\"   name  : suitable name for an escape sequence (c, (xy, [long])
.\"   arg   : arbitrary word
.\" Result  : prints \namearg, where
.\"           'name' is in B, 'arg' in I
.\"
.de escarg
.  Text \f[B]\e\\$1\f[]\,\f[I]\\$2\/\f[]\\$3
..
.\" ====================================================================
.\" .esc[] name arg [punct]
.\"
.\" Reference for escape sequence with a bracketed long argument
.\" Args   : 2 obligatory
.\"   name : suitable name for an escape sequence (c, (xy, [long])
.\"   arg  : arbitrary text
.\" Result : prints \name[arg], where 'name' is in CB, 'arg' in CI
.\"
.de esc[]
.  Text \f[CB]\e\\$1\[lB]\f[]\,\f[CI]\\$2\/\f[]\f[CB]\[rB]\f[]\\$3
..
.
.\" ========= strings =========
.
.\" synopsis for string, with \*[]
.de STRING
.  Text \[rs]*[\f[CB]\\$1\f[]] \\$2
..
.\" synopsis for a long string
.de string
.  if \n[.$]=0 \
.    return
.  Text \f[CB]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
..
.
.\" ========= registers =========
.
.\" synopsis for registers, with \n[]
.de REG
.  Text \[rs]n[\f[CB]\\$1\f[]]
..
.\" reference of a register, without decoration
.de register
.  Text register
.  ie (\\n[.$] < 2) \
.    B \\$*
.  el \
.    BR \\$*
..
.
.\" end of macro definitions
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
.P
The name
.I groff
stands for
.I GNU roff
and is the free implementation of the roff type-setting system.
.
See
.BR roff (@MAN7EXT@)
for a survey and the background of the groff system.
.
.
.P
This document provides only short descriptions of roff language
elements.
.
.IR "Groff: The GNU Implementation of troff" ,
by Trent A.\& Fisher and Werner Lemberg,
is the primary
.I groff
manual,
and is written in Texinfo.
.
You can browse it interactively with \[lq]info groff\[rq].
.
.
.P
Historically, the
.I roff language
was called
.IR troff .
.I groff
is compatible with the classical system and provides proper
extensions.
.
So in GNU, the terms
.IR roff ,
.IR troff ,
and
.I groff language
could be used as synonyms.
.
However
.I troff
slightly tends to refer more to the classical aspects, whereas
.I groff
emphasizes the GNU extensions, and
.I roff
is the general term for the language.
.
.
.P
The general syntax for writing groff documents is relatively easy, but
writing extensions to the roff language can be a bit harder.
.
.
.P
The roff language is line-oriented.
.
There are only two kinds of lines, control lines and text lines.
.
The control lines start with a control character, by default a period
.dquoted_char .
or a single quote
.dquoted_char \[aq] ;
all other lines are text lines.
.
.
.P
.B Control lines
represent commands, optionally with arguments.
.
They have the following syntax.
.
The leading control character can be followed by a command name;
arguments, if any, are separated by spaces (but not tab characters)
from the command name and among themselves, for example,
.RS
.P
.Text .command_name arg1 arg2
.RE
.
.
.P
For indentation, any number of space or tab characters can be inserted
between the leading control character and the command name, but the
control character must be on the first position of the line.
.
.
.P
.B Text lines
represent the parts that is printed.
They can be modified by escape sequences, which are recognized by a
leading backslash
.squoted_char \[rs] .
These are in-line or even in-word formatting elements or functions.
.
Some of these take arguments separated by single quotes
.dquoted_char \[aq] ,
others are regulated by a length encoding introduced by an open
parenthesis
.squoted_char (
or enclosed in brackets
.squoted_char [
and
.squoted_char ] .
.
.
.P
The roff language provides flexible instruments for writing language
extension, such as macros.
.
When interpreting macro definitions, the roff system enters a special
operating mode, called the
.BR "copy mode" .
.
.
.P
The copy mode behaviour can be quite tricky, but there are some rules
that ensure a safe usage.
.
.IP 1.
Printable backslashes must be denoted as
.esc e .
To be more precise,
.esc e
represents the current escape character.
.
To get a backslash glyph, use
.esc (rs
or
.esc [rs] .
.IP 2.
Double all backslashes.
.IP 3.
Begin all text lines with the non-printing input break
.esc & .
.
.
.P
This does not produce the most efficient code, but it should work as a
first measure.
.
For better strategies, see the
.I groff
Texinfo manual and
.BR groff_tmac (@MAN5EXT@).
.
.
.P
Reading roff source files is easier, just reduce all double backslashes
to a single one in all macro definitions.
.
.
.\" ====================================================================
.SH "groff Elements"
.\" ====================================================================
.
The roff language elements add formatting information to a text file.
.
The fundamental elements are predefined commands and variables that
make roff a full-blown programming language.
.
.
.P
There are two kinds of roff commands, possibly with arguments.
.B Requests
are written on a line of their own starting with a dot
.squoted_char .\&
or a
.dquoted_char \[aq] ,
whereas
.B Escape sequences
are in-line functions and in-word formatting elements starting with a
backslash
.squoted_char \[rs] .
.
.
.P
The user can define her own formatting commands using the
.request .de
request.
.
These commands are called
.BR macros ,
but they are used exactly like requests.
.
Macro packages are pre-defined sets of macros written in the groff
language.
.
A user's possibilities to create escape sequences herself is very
limited, only special characters can be mapped.
.
.
.P
The groff language provides several kinds of variables with
different interfaces.
.
There are pre-defined variables, but the user can define her own
variables as well.
.
.
.P
.B String
variables store character sequences.
.
They are set with the
.request .ds
request and retrieved by the
.esc *
escape sequences.
.
Strings can have variables.
.
.
.P
.B Register
variables can store numerical values, numbers with a scale unit, and
occasionally string-like objects.
.
They are set with the
.request .nr
request and retrieved by the
.esc n
escape sequences.
.
.
.P
.B Environments
allow the user to temporarily store global formatting parameters like
line length, font size, etc.\& for later reuse.
.
This is done by the
.request .ev
request.
.
.
.P
.B Fonts
are identified either by a name or by an internal number.
.
The current font is chosen by the
.request .ft
request or by the
.esc f
escape sequences.
.
Each device has special fonts, but the following fonts are available
for all devices.
.B R
is the standard font Roman.
.B B
is its
.B bold
counterpart.
.
The
.I italic
font is called
.B I
and is available everywhere, but on text devices it is displayed as an
underlined Roman font.
.
For the graphical output devices, there exist constant-width pendants
of these fonts,
.BR CR ,
.BR CI ,
and
.BR CB .
On text devices, all glyphs have a constant width anyway.
.
.
.P
.B Glyphs
are visual representation forms of
.BR characters .
In groff, the distinction between those two elements is not always
obvious (and a full discussion is beyond the scope of this man page).
.
A first approximation is that glyphs have a specific size and
colour and are taken from a specific font; they can't be modified any
more \[en] characters are the input, and glyphs are the output.
.
As soon as an output line has been generated, it no longer contains
characters but glyphs.
.
In this man page, we use either \[oq]glyph\[cq] or
\[oq]character\[cq], whatever is more appropriate.
.
A few characters commonly seen on keyboards are treated
specially by
.I roff
languages and may not look correct in output;
they are
the (double) quotation mark
.RB ( \[dq] ),
the apostrophe
.RB ( \[aq] ),
the hyphen-minus
.RB ( \- ),
the backslash
.RB ( \[rs] ),
the caret or circumflex accent
.RB ( \[ha] ),
the grave accent
.RB ( \[ga] ),
and the tilde
.RB ( \[ti] ).
.
All are available if required;
see
.IR groff_char (@MAN7EXT@).
.
.
.P
Moreover, there are some advanced roff elements.
.
A
.B diversion
stores (formatted) information into a macro for later usage.
See
.BR groff_tmac (@MAN5EXT@)
for more details.
.
A
.B trap
is a positional condition like a certain number of lines from page top
or in a diversion or in the input.
.
Some action can be prescribed to be run automatically when the
condition is met.
.
.
.P
More detailed information and examples can be found in the
.I groff
Texinfo manual.
.
.
.\" ====================================================================
.SH "Control characters"
.\" ====================================================================
.
There is a small set of characters that have a special controlling
task in certain conditions.
.
.TP
\&\f[CB].\f[]
A dot is only special at the beginning of a line or after the
condition in the requests
.request .if ,
.request .ie ,
.request .el ,
and
.request .while .
.
There it is the control character that introduces a request (or macro).
.
By using the
.request .cc
request, the control character can be set to a different character,
making the dot
.squoted_char .\&
a non-special character.
.
.IP
In all other positions, it just means a dot character.
.
In text paragraphs, it is advantageous to start each sentence at a
line of its own.
.
.TP
\&\f[CB]\[aq]\f[]
The apostrophe has two controlling tasks.
.
At the beginning of a line and in the conditional requests it is the
non-breaking control character.
.
That means that it introduces a request like the dot, but with the
additional property that this request doesn't cause a linebreak.
.
By using the
.request .c2
request, the non-break control character can be set to a different
character.
.
.IP
As a second task, it is the most commonly used argument separator in
some functional escape sequences (but any pair of characters not part
of the argument do work).
.
In all other positions, it denotes a single quote or apostrophe
character, depending on the output device's glyph repertoire.
.
.I groff
provides a printable representation with the
.esc (aq
escape sequence.
.
.TP
\&\f[CB]\[dq]\f[]
The double quote can be used to enclose arguments to macros and strings,
but not requests.
.
In the
.request .ds ,
.request .ds1 ,
.request .as ,
and
.request .as1
requests,
a leading double quote in the second argument is stripped off,
enabling the inclusion of leading space characters in the string
definition or appendment.
.
The escaped double quote
.esc \[dq]
introduces a comment.
.
Otherwise, it is not special.
.
.I groff
provides a printable representation with the
.esc [dq]
escape sequence.
.
.TP
\&\f[CB]\e\f[]
The backslash usually introduces an escape sequence (this can be
changed with the
.request .ec
request).
.
A printed version of the escape character is the
.esc e
escape; a backslash glyph can be obtained by
.esc (rs .
.
.TP
\&\f[CB](\f[]
The open parenthesis is only special in escape sequences when
introducing an escape name or argument consisting of exactly two
characters.
.
In groff, this behaviour can be replaced by the \f[CB][]\f[] construct.
.
.TP
\&\f[CB][\f[]
The opening bracket is only special in groff escape sequences; there
it is used to introduce a long escape name or long escape argument.
.
Otherwise, it is non-special, e.g., in macro calls.
.
.TP
\&\f[CB]]\f[]
The closing bracket is only special in groff escape sequences; there
it terminates a long escape name or long escape argument.
.
Otherwise, it is non-special.
.
.
.TP
\f[CI]space\f[]
Space characters separate arguments in request invocations,
macro calls,
and string interpolations.
.
In text,
they separate words.
.
Multiple adjacent space characters in text cause
.I groff
to attempt end-of-sentence detection on the preceding word
(and trailing punctuation).
.
The amount of space between words and sentences is controlled by the
.request .ss
request.
.
When filling is enabled
(the default),
a line may be broken at a space.
.
When adjustment is enabled and set to both margins
(the default),
inter-word spaces may be expanded to justify the line.
.
To get a space of definite width,
use the escape sequences
.squoted_char "\[rs]\ "
(this is the escape character followed by a space),
.esc 0 ,
.esc | ,
.esc \[ha] ,
or
.esc h ;
see section \[lq]Escape Sequences\[rq] below.
.
An adjustable but non-breaking space is available with
.esc \[ti] .
.
.
.IP \f[CI]newline\f[]
In text,
a newline puts an inter-word space onto the output and triggers
end-of-sentence recognition on the preceding text.
.
.esc c
at the end of an input line suppresses these functions.
.
Continuation lines can be specified by an escaped newline, i.e., by
specifying a backslash
.squoted_char \[rs]
as the last character of a line.
.
.IP \f[CI]tab\f[]
If a tab character occurs during text the interpreter makes a
horizontal jump to the next pre-defined tab position.
.
There is a sophisticated interface for handling tab positions.
.
.
.\" ====================================================================
.SH "Numerical expressions"
.\" ====================================================================
.
A
.B numerical value
is a signed or unsigned integer or float with or without an appended
scaling indicator.
.
A
.B scaling indicator
is a one-character abbreviation for a unit of measurement.
.
A number followed by a scaling indicator signifies a size value.
.
By default, numerical values do not have a scaling indicator, i.e., they
are normal numbers.
.
.
.P
The
.I roff
language defines the following scaling indicators.
.
.
.P
.PD 0
.RS
.
.TPx
.B c
centimeter
.
.TPx
.B i
inch
.
.TPx
.B P
pica\ \[eq]\ 1/6\ inch
.
.TPx
.B p
point\ \[eq]\ 1/72\ inch
.
.TPx
.B m
em\ \[eq]\ \f[R]the font size in points (approx.\& width of letter
\[oq]\f[CR]m\f[R]\[cq])
.
.TPx
.B M
100\^th \f[R]of an \f[CR]em
.
.TPx
.B n
en\ \[eq]\ em/2
.
.TPx
.B u
Basic unit for actual output device
.
.TPx
.B v
Vertical line space in basic units
.
.TPx
.B s
scaled point\ \[eq]\ 1/\f[CI]sizescale\f[R] of a point (defined in
font \f[I]DESC\f[] file)
.
.TPx
.B f
Scale by 65536.
.RE
.PD
.
.
.P
.B Numerical expressions
are combinations of the numerical values defined above with the
following arithmetical operators already defined in classical troff.
.
.
.P
.PD 0
.RS
.
.TPx
.B +
Addition
.
.TPx
.B \-
Subtraction
.
.TPx
.B *
Multiplication
.
.TPx
.B /
Division
.
.TPx
.B %
Modulo
.
.TPx
.B =
Equals
.
.TPx
.B ==
Equals
.
.TPx
.B <
Less than
.
.TPx
.B >
Greater than
.
.TPx
.B <=
Less or equal
.
.TPx
.B >=
Greater or equal
.
.TPx
.B &
Logical and
.
.TPx
.B :
Logical or
.
.TPx
.B !
Logical not
.
.TPx
.B (
Grouping of expressions
.
.TPx
.B )
Close current grouping
.
.RE
.PD
.
.
.P
Moreover,
.I groff
added the following operators for numerical expressions:
.
.
.P
.PD 0
.RS
.
.TPx
\f[I]e1\/\f[CB]>?\,\f[I]e2\f[R]
The maximum of
.I e1
and
.IR e2 .
.
.TPx
\f[I]e1\/\f[CB]<?\,\f[I]e2\f[R]
The minimum of
.I e1
and
.IR e2 .
.
.TPx
\f[CB](\,\f[I]c\/\f[CB];\,\f[I]e\/\f[CB])\f[R]
Evaluate
.I e
using
.I c
as the default scaling indicator.
.
.RE
.PD
.
.
.P
For details see the
.I groff
Texinfo manual.
.
.
.\" ====================================================================
.SH Conditions
.\" ====================================================================
.
.B Conditions
are expressions tested by the
.request .if ,
.request .ie ,
and the
.request .while
requests.
.
The following table characterizes the different types of conditions.
.
.P
.
.PD 0
.RS
.
.TPx
.I N
A numerical expression
.I N
yields true if its value is greater than\~0.
.
.TPx
.BI ! N
True if the value of
.I N
is \[<=]\~0
(see below).
.
.TPx
.BI \[aq] s1 \[aq] s2 \[aq]
True if string\~\c
.I s1
is identical to string\~\c
.IR s2 .
.
.TPx
.BI !\[aq] s1 \[aq] s2 \[aq]
True if string\~\c
.I s1
is not identical to string\~\c
.I s2
(see below).
.
.TPx
.BI c\~ g
True if a glyph
.I g
is available.
.
.TPx
.BI d\~ name
True if there is a string,
macro,
diversion,
or request called
.IR name .
.
.TPx
.B e
Current page number is even.
.
.TPx
.BI F\~ font
True if a font called
.I font
exists.
.
.TPx
.BI m\~ color
True if there is a color called
.IR color .
.
.TPx
.B n
Formatter is
.IR nroff .
.
.TPx
.B o
Current page number is odd.
.
.TPx
.BI r\~ reg
True if there is a number register called
.IR reg .
.
.TPx
.BI S\~ style
True if a style called
.I style
has been registered.
.
.TPx
.B t
Formatter is
.IR troff .
.
.TPx
.B v
Always false
(for compatibilty with other
.I troff
implementations).
.
.RE
.PD
.
.
.P
Note that the
.B !\&
operator may only appear at the beginning of an expression,
and negates the entire expression.
This maintains bug-compatibility with AT&T
.IR troff .
.
.
.\" ====================================================================
.SH Requests
.\" ====================================================================
.
This section provides a short reference for the predefined requests.
.
In groff, request, macro, and string names can be arbitrarily long.
.
No bracketing or marking of long names is needed.
.
.
.P
Most requests take one or more arguments.
.
The arguments are separated by space characters (no tabs!); there is
no inherent limit for their length or number.
.
.
.P
Some requests have optional arguments with a different behaviour.
.
Not all of these details are outlined here.
.
Refer to the
.I groff
Texinfo manual and
.BR groff_diff (@MAN7EXT@)
for all details.
.
.
.P
In the following request specifications, most argument names were
chosen to be descriptive.
.
Only the following denotations need clarification.
.
.
.P
.PD 0
.RS
.
.TPx
.I c
denotes a single character.
.
.TPx
.I font
a font either specified as a font name or a font number.
.
.TPx
.I anything
all characters up to the end of the line or within
.esc {
and
.esc } .
.
.TPx
.I n
is a numerical expression that evaluates to an integer value.
.
.TPx
.I N
is an arbitrary numerical expression, signed or unsigned.
.
.TPx
.I \[+-]N
has three meanings depending on its sign, described below.
.
.RE
.PD
.
.
.P
If an expression defined as
.I \[+-]N
starts with a
.squoted_char +
sign the resulting value of the expression is added to an already
existing value inherent to the related request, e.g., adding to a
number register.
.
If the expression starts with a
.squoted_char -
the value of the expression is subtracted from the request value.
.
.
.P
Without a sign,
.I N
replaces the existing value directly.
.
To assign a negative number either prepend\~0 or enclose the negative
number in parentheses.
.
.
.\" ====================================================================
.SS "Request short reference"
.\" ====================================================================
.
.PD 0
.
.TPx
.REQ .
Empty line, ignored.
.
Useful for structuring documents.
.
.TPx
.REQ .\e\[dq] "anything"
Complete line is a comment.
.
.TPx
.REQ .ab "string"
Print
.I string
on standard error, exit program.
.
.
.TPx
.REQ .ad
Enable output line adjustment.
.
.
.TPx
.REQ .ad c
Adjust output lines in mode
.I c
.RI ( c =\c
.BR b , c , l , n , r ).
.
Sets
.BR \[rs]n[.j] .
.
.
.TPx
.REQ .af "register c"
Assign format
.I c
to
.IR register ,
where
.I c
is
.RB \[lq] i \[rq],
.RB \[lq] I \[rq],
.RB \[lq] a \[rq],
.RB \[lq] A \[rq],
or a sequence of decimal digits whose quantity denotes the minimum width
in digits to be used when the register is interpolated.
.
.RB \[lq] i \[rq]
and
.RB \[lq] a \[rq]
indicate Roman numerals and base-26 Latin alphabetics,
respectively,
in the lettercase specified.
.
The default is \[lq]0\[rq].
.
.
.TPx
.REQ .aln "new old"
Create alias
(additional name)
.I new
for existing number register named
.IR old .
.
.TPx
.REQ .als "new old"
Create alias
(additional name)
.I new
for existing request,
string,
macro,
or diversion
.IR old .
.
.TPx
.REQ .am "macro"
Append to
.I macro
until
.B ..\&
is encountered.
.
.TPx
.REQ .am "macro end"
Append to
.I macro
until
.BI . end
is called.
.
.TPx
.REQ .am1 "macro"
Same as
.request .am
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .am1 "macro end"
Same as
.request .am
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .ami "macro"
Append to a macro whose name is contained in the string register
.I macro
until
.B ..\&
is encountered.
.
.TPx
.REQ .ami "macro end"
Append to a macro indirectly.
.I macro
and
.I end
are string registers whose contents are interpolated for the macro name
and the end macro, respectively.
.
.TPx
.REQ .ami1 "macro"
Same as
.request .ami
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .ami1 "macro end"
Same as
.request .ami
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .as "name \fR[\fPstring\fR]\fP"
Append
.I string
to the string
.IR name ;
no operation if
.I string
is omitted.
.
.
.TPx
.REQ .as1 "name \fR[\fPstring\fR]\fP"
Same as
.request .as
but with compatibility mode switched off during string expansion.
.
.
.TPx
.REQ .asciify "diversion"
Unformat ASCII characters, spaces, and some escape sequences in
.IR diversion .
.
.TPx
.REQ .backtrace
Write a backtrace of the input stack to the standard error stream.
.
Also see the
.B \-b
option of
.IR groff (@MAN1EXT@).
.
.TPx
.REQ .bd "font N"
Embolden
.I font
by
.IR N \-1
units.
.
.TPx
.REQ .bd "S font N"
Embolden Special Font
.I S
when current font is
.IR font .
.
.
.TPx
.REQ .blm
Unset blank line macro (trap).
.
Restore default handling of blank lines.
.
.
.TPx
.REQ .blm name
Set blank line macro (trap) to
.IR name .
.
.
.TPx
.REQ .box
End current diversion.
.
.TPx
.REQ .box "macro"
Divert to
.IR macro ,
omitting a partially filled line.
.
.TPx
.REQ .boxa
End current diversion.
.
.TPx
.REQ .boxa "macro"
Divert and append to
.IR macro ,
omitting a partially filled line.
.
.TPx
.REQ .bp
Eject current page and begin new page.
.
.TPx
.REQ .bp "\[+-]N"
Eject current page; next page number
.IR \[+-]N .
.
.TPx
.REQ .br
Line break.
.
.TPx
.REQ .brp
Break output line; adjust if applicable.
.
.TPx
.REQ .break
Break out of a while loop.
.
.TPx
.REQ .c2
Reset no-break control character to
.dquoted_char \[aq] .
.
.TPx
.REQ .c2 "c"
Set no-break control character to
.IR c .
.
.TPx
.REQ .cc
Reset control character to
.squoted_char . .
.
.TPx
.REQ .cc "c"
Set control character to
.IR c .
.
.TPx
.REQ .ce
Center the next input line.
.
.TPx
.REQ .ce "N"
Center following
.I N
input lines.
.
.TPx
.REQ .cf "filename"
Copy contents of file
.I filename
unprocessed to stdout or to the diversion.
.
.TPx
.REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP"
Assign properties encoded by the number
.I n
to characters
.IR c1 ,
.IR c2 ,
and so on.
.
.
.TPx
.REQ .ch "name N"
Change location of page location trap by moving macro
.I name
to new location
.IR N ,
or by unplanting it altogether if
.I N
absent.
.
.
.TPx
.REQ .char "c anything"
Define entity
.I c
as string
.IR anything .
.
.TPx
.REQ .chop object
Remove the last character from the macro,
string,
or diversion
named
.IR object .
.
.TPx
.REQ .class "name c1 c2 \fR\&.\|.\|.\&\fP"
Define a (character) class
.I name
comprising the characters or range expressions
.IR c1 ,
.IR c2 ,
and so on.
.
.TPx
.REQ .close "stream"
Close the
.IR stream .
.
.TPx
.REQ .color
Enable colors.
.
.TPx
.REQ .color "N"
If
.I N
is zero disable colors, otherwise enable them.
.
.TPx
.REQ .composite "from to"
Map glyph name
.I from
to glyph name
.I to
while constructing a composite glyph name.
.
.TPx
.REQ .continue
Finish the current iteration of a while loop.
.
.TPx
.REQ .cp
Enable compatibility mode.
.
.TPx
.REQ .cp "N"
If
.I N
is zero disable compatibility mode, otherwise enable it.
.
.TPx
.REQ .cs "font N M"
Set constant character width mode for
.I font
to
.IR N /36
ems with em
.IR M .
.
.TPx
.REQ .cu "N"
Continuous underline in nroff, like
.request .ul
in troff.
.
.TPx
.REQ .da
End current diversion.
.
.TPx
.REQ .da "macro"
Divert and append to
.IR macro .
.
.TPx
.REQ .de "macro"
Define or redefine
.I macro
until
.B ..\&
is encountered.
.
.TPx
.REQ .de "macro end"
Define or redefine
.I macro
until
.BI . end
is called.
.
.TPx
.REQ .de1 "macro"
Same as
.request .de
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .de1 "macro end"
Same as
.request .de
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .defcolor "color scheme component"
Define or redefine a color with name
.IR color .
.I scheme
can be
.BR rgb ,
.BR cym ,
.BR cymk ,
.BR gray ,
or
.BR grey .
.I component
can be single components specified as fractions in the range 0 to 1
(default scaling indicator\~\c
.scaleindicator f ),
as a string of two-digit hexadecimal color components with a leading
.BR # ,
or as a string of four-digit hexadecimal components with two leading
.BR # .
The color
.B default
can't be redefined.
.
.TPx
.REQ .dei "macro"
Define or redefine a macro whose name is contained in the string
register
.I macro
until
.B ..\&
is encountered.
.
.TPx
.REQ .dei "macro end"
Define or redefine a macro indirectly.
.I macro
and
.I end
are string registers whose contents are interpolated for the macro name
and the end macro, respectively.
.
.TPx
.REQ .dei1 "macro"
Same as
.request .dei
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .dei1 "macro end"
Same as
.request .dei
but with compatibility mode switched off during macro expansion.
.
.TPx
.REQ .device "anything"
Write
.I anything
to the intermediate output as a device control function.
.
.TPx
.REQ .devicem "name"
Write contents of macro or string
.I name
uninterpreted to the intermediate output as a device control function.
.
.TPx
.REQ .di
End current diversion.
.
.TPx
.REQ .di "macro"
Divert to
.IR macro .
See
.BR groff_tmac (@MAN5EXT@)
for more details.
.
.TPx
.REQ .do "name \fR\&.\|.\|.\&\fP"
Interpret the string,
request,
diversion,
or macro
.I name
(along with any arguments)
with compatibility mode disabled.
.
Note that compatibility mode is restored
(if and only if it was active)
when the
.I expansion
of
.I name
is interpreted.
.
.TPx
.REQ .ds "name \fR[\fPstring\fR]\fP"
Define a string variable
.I name
with contents
.IR string ,
or as empty if
.I string
is omitted.
.
.
.TPx
.REQ .ds1 "name \fR[\fPstring\fR]\fP"
Same as
.request .ds
but with compatibility mode switched off during string expansion.
.
.
.TPx
.REQ .dt
Clear diversion trap.
.
.
.TPx
.REQ .dt "N name"
Set diversion trap to
macro
.I name
at position
.I N
(default scaling indicator\~\c
.scaleindicator v ).
.
.
.TPx
.REQ .ec
Reset escape character to
.squoted_char \[rs] .
.
.TPx
.REQ .ec "c"
Set escape character to
.IR c .
.
.TPx
.REQ .ecr
Restore escape character saved with
.request .ecs .
.
.TPx
.REQ .ecs
Save current escape character.
.
.TPx
.REQ .el "anything"
Else part for if-else (\c
.request .ie )
request.
.
.
.TPx
.REQ .em name
Invoke macro
.I name
after the end of input.
.
.
.TPx
.REQ .eo
Turn off escape character mechanism.
.
.TPx
.REQ .ev
Switch to previous environment and pop it off the stack.
.
.TPx
.REQ .ev "env"
Push down environment number or name
.I env
to the stack and switch to it.
.
.TPx
.REQ .evc "env"
Copy the contents of environment
.I env
to the current environment.
No pushing or popping.
.
.TPx
.REQ .ex
Exit from roff processing.
.
.TPx
.REQ .fam
Return to previous font family.
.
.TPx
.REQ .fam "name"
Set the current font family to
.IR name .
.
.TPx
.REQ .fc
Disable field mechanism.
.
.TPx
.REQ .fc "a"
Set field delimiter to\~\c
.I a
and pad glyph to space.
.
.TPx
.REQ .fc "a b"
Set field delimiter to\~\c
.I a
and pad glyph to\~\c
.IR b .
.
.TPx
.REQ .fchar "c anything"
Define fallback character (or glyph)
.I c
as string
.IR anything .
.
.TPx
.REQ .fcolor
Set fill color to previous fill color.
.
.TPx
.REQ .fcolor "c"
Set fill color to
.IR c .
.
.TPx
.REQ .fi
Fill output lines.
.
.TPx
.REQ .fl
Flush output buffer.
.
.TPx
.REQ .fp "n font"
Mount
.I font
on position
.IR n .
.
.TPx
.REQ .fp "n internal external"
Mount font with long
.I external
name to short
.I internal
name on position
.IR n .
.
.TPx
.REQ .fschar "f c anything"
Define fallback character (or glyph)
.I c
for font
.I f
as string
.IR anything .
.
.TPx
.REQ .fspecial "font"
Reset list of special fonts for
.I font
to be empty.
.
.TPx
.REQ .fspecial "font s1 s2 \fR\&.\|.\|.\&\fP"
When the current font is
.IR font ,
then the fonts
.IR s1 ,
.IR s2 ,
\&.\|.\|.\&
are special.
.
.TPx
.REQ .ft
Return to previous font.
Same as
.esc f[]
or
.esc fP .
.
.TPx
.REQ .ft "font"
Change to font name or number
.IR font ;
same as
.esc[] f font
escape sequence.
.
.TPx
.REQ .ftr "font1 font2"
Translate
.I font1
to
.IR font2 .
.
.TPx
.REQ .fzoom "font"
Don't magnify
.IR font .
.
.TPx
.REQ .fzoom "font zoom"
Set zoom factor for
.I font
(in multiples of 1/1000th).
.
.TPx
.REQ .gcolor
Set glyph color to previous glyph color.
.
.TPx
.REQ .gcolor "c"
Set glyph color to
.IR c .
.
.TPx
.REQ .hc
Reset the hyphenation character
.RB to\~ \[rs]%
(the default).
.
.TPx
.REQ .hc char
Change the hyphenation character
.RI to\~ char .
.
.TPx
.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP"
Set the hyphenation code of character
.I c1
to
.IR code1 ,
that of
.I c2
to
.IR code2 ,
and so on.
.
.TPx
.REQ .hla lang
Set the hyphenation language to
.IR lang .
.
.TPx
.REQ .hlm n
Set the maximum number of consecutive hyphenated lines to
.IR n .
.
.TPx
.REQ .hpf pattern-file
Read hyphenation patterns from
.IR pattern-file .
.
.TPx
.REQ .hpfa pattern-file
Append hyphenation patterns from
.IR pattern-file .
.
.TPx
.REQ .hpfcode "a b \fR[\fPc d\fR] .\|.\|.\fP"
Define mapping values for character codes in pattern files read with the
.request .hpf
and
.request .hpfa
requests.
.
.TPx
.REQ .hw "word \fR.\|.\|.\fP"
Define how each
.I  word
is to be hyphenated,
with each hyphen
.RB \[lq] \- \[rq]
indicating a hyphenation point.
.
.
.TPx
.REQ .hy
Set automatic hyphenation mode to
.BR 1 .
.
.
.TPx
.REQ .hy \fB0\fP
Disable automatic hyphenation;
same as
.BR .nh .
.
.
.TPx
.REQ .hy mode
Set automatic hyphenation mode to
.IR mode ;
see section \[lq]Hyphenation\[rq] below.
.
.
.TPx
.REQ .hym
Set the (right) hyphenation margin to
.B 0
(the default).
.
.TPx
.REQ .hym length
Set the (right) hyphenation margin to
.I length
(default scaling indicator\~\c
.scaleindicator m ).
.
.TPx
.REQ .hys
Set the hyphenation space to
.B 0
(the default).
.
.TPx
.REQ .hys 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
(default scaling indicator\~\c
.scaleindicator m ).
.
.TPx
.REQ .ie "cond anything"
If
.I cond
then
.IR anything ,
otherwise skip to
.request .el .
.
.TPx
.REQ .if "cond anything"
If
.I cond
then
.IR anything ;
otherwise do nothing.
.
.TPx
.REQ .ig
Ignore text until
.B ..\&
is encountered.
.
.TPx
.REQ .ig "end"
Ignore text until
.BI . end
is called.
.
.TPx
.REQ .in
Change to previous indentation value.
.
.TPx
.REQ .in "\[+-]N"
Change indentation according to
.I \[+-]N
(default scaling indicator\~\c
.scaleindicator m ).
.
.
.TPx
.REQ .it "n name"
Set an input line trap,
calling macro
.IR name ,
after the next
.IR n\~ lines
lines of text input have been read.
.
.
.TPx
.REQ .itc "n name"
As
.request .it ,
but don't count lines interrupted with
.esc c .
.
.
.TPx
.REQ .kern
Enable pairwise kerning.
.
.TPx
.REQ .kern "n"
If
.I n
is zero, disable pairwise kerning, otherwise enable it.
.
.
.TPx
.REQ .lc
Remove leader repetition glyph.
.
.
.TPx
.REQ .lc "c"
Set leader repetition glyph
.RI to\~ c
(default:
.RB \[lq] . \[rq]).
.
.
.TPx
.REQ .length "reg anything"
Compute the number of characters of
.I anything
and store the count
in the number register
.IR reg .
.
.TPx
.REQ .linetabs
Enable line-tabs mode (i.e., calculate tab positions relative to output
line).
.
.TPx
.REQ .linetabs "n"
If
.I n
is zero, disable line-tabs mode, otherwise enable it.
.
.TPx
.REQ .lf "N"
Set input line number to
.IR N .
.
.TPx
.REQ .lf "N file"
Set input line number to
.I N
and filename to
.IR file .
.
.TPx
.REQ .lg "N"
Ligature mode on if
.IR N >0.
.
.TPx
.REQ .ll
Change to previous line length.
.
.TPx
.REQ .ll "\[+-]N"
Set line length according to
.I \[+-]N
(default length
.scalednumber 6.5 i ,
default scaling indicator\~\c
.scaleindicator m ).
.
.
.TPx
.REQ .lsm
Unset the leading space macro (trap).
.
Restore default handling of lines with leading spaces.
.
.
.TPx
.REQ .lsm name
Set the leading space macro (trap) to
.IR name .
.
.
.TPx
.REQ .ls
Change to the previous value of additional intra-line skip.
.
.TPx
.REQ .ls "N"
Set additional intra-line skip value to
.IR N ,
i.e.,
.IR N \-1
blank lines are inserted after each text output line.
.
.TPx
.REQ .lt "\[+-]N"
Length of title (default scaling indicator\~\c
.scaleindicator m ).
.
.TPx
.REQ .mc
Margin glyph off.
.
.TPx
.REQ .mc "c"
Print glyph\~\c
.I c
after each text line at actual distance from right margin.
.
.TPx
.REQ .mc "c N"
Set margin glyph to\~\c
.I c
and distance to\~\c
.I N
from right margin (default scaling indicator\~\c
.scaleindicator m ).
.
.TPx
.REQ .mk "\fR[\fPregister\fR]\fP"
Mark current vertical position in
.IR register ,
or in an internal register used by
.B .rt
if no argument.
.
.
.TPx
.REQ .mso "file"
As
.request .so ,
except that
.I file
is sought in the
.I tmac
directories.
.
.
.TPx
.REQ .msoquiet "file"
As
.request .mso ,
but no warning is emitted if
.I file
does not exist.
.
.
.TPx
.REQ .na
Disable line adjustment.
.
.
.TPx
.REQ .ne
Need a one-line vertical space.
.
.TPx
.REQ .ne "N"
Need
.I N
vertical space (default scaling indicator\~\c
.scaleindicator v ).
.
.TPx
.REQ .nf
No filling or adjusting of output lines.
.
.TPx
.REQ .nh
Disable automatic hyphenation;
same as
.RB \[lq] ".hy 0" \[rq].
.
.TPx
.REQ .nm
Number mode off.
.
.TPx
.REQ .nm "\[+-]N \fR[\fPM \fR[\fPS \fR[\fPI\fR]]]\fP"
In line number mode, set number, multiple, spacing, and indentation.
.
.TPx
.REQ .nn
Do not number next line.
.
.TPx
.REQ .nn "N"
Do not number next
.I N
lines.
.
.TPx
.REQ .nop "anything"
Always process
.IR anything .
.
.TPx
.REQ .nr "register \[+-]N \fR[\fPM\fR]\fP"
Define or modify
.I register
using
.I \[+-]N
with auto-increment
.IR M .
.
.TPx
.REQ .nroff
Make the built-in conditions
.B n
true and
.B t
false.
.
.TPx
.REQ .ns
Turn on no-space mode.
.
.TPx
.REQ .nx
Immediately jump to end of current file.
.
.TPx
.REQ .nx "filename"
Immediately continue processing with file
.IR file .
.
.TPx
.REQ .open "stream filename"
Open
.I filename
for writing and associate the stream named
.I stream
with it.
.
.TPx
.REQ .opena "stream filename"
Like
.request .open
but append to it.
.
.TPx
.REQ .os
Output vertical distance that was saved by the
.request .sv
request.
.
.TPx
.REQ .output "string"
Emit
.I string
directly to intermediate output, allowing leading whitespace if
.I string
starts with
\&\f[CB]\[dq]\f[]
(which is stripped off).
.
.TPx
.REQ .pc
Reset page number character to\~\c
.squoted_char % .
.
.TPx
.REQ .pc "c"
Page number character.
.
.TPx
.REQ .pev
Print the current environment and each defined environment
state to stderr.
.
.TPx
.REQ .pi "program"
Pipe output to
.I program
(nroff only).
.
.TPx
.REQ .pl
Set page length to default
.scalednumber 11 i .
The current page length is stored in register
.BR .p .
.
.TPx
.REQ .pl "\[+-]N"
Change page length to
.I \[+-]N
(default scaling indicator\~\c
.scaleindicator v ).
.
.TPx
.REQ .pm
Report,
to the standard error stream,
the names and sizes in bytes of
defined
macros,
strings,
and
diversions.
.
.TPx
.REQ .pn "\[+-]N"
Next page number
.IR N .
.
.TPx
.REQ .pnr
Print the names and contents of all currently defined number registers
on stderr.
.
.TPx
.REQ .po
Change to previous page offset.
.
The current page offset is available in register
.BR .o .
.
.TPx
.REQ .po "\[+-]N"
Page offset
.IR N .
.
.TPx
.REQ .ps
Return to previous point size.
.TPx
.
.REQ .ps "\[+-]N"
Set/increase/decrease the point size to/by
.I N
scaled points
(a non-positive resulting point size is set to 1\~u);
also see
.esc[] s \[+-]N .
.
.TPx
.REQ .psbb "filename"
Get the bounding box of a PostScript image
.IR filename .
.
.TPx
.REQ .pso "command"
This behaves like the
.request .so
request except that input comes from the standard output of
.IR command .
.
.
.TPx
.REQ .ptr
Report names and positions of all page location traps to the standard
error stream.
.
.
.TPx
.REQ .pvs
Change to previous post-vertical line spacing.
.
.TPx
.REQ .pvs "\[+-]N"
Change post-vertical line spacing according to
.I \[+-]N
(default scaling indicator\~\c
.scaleindicator p ).
.
.TPx
.REQ .rchar "c1 c2 \fR\&.\|.\|.\&\fP"
Remove the definitions of entities
.IR c1 ,
.IR c2 ,
\&.\|.\|.\&
.
.TPx
.REQ .rd "prompt"
Read insertion.
.
.TPx
.REQ .return
Return from a macro.
.
.TPx
.REQ .return "anything"
Return twice, namely from the macro at the current level and from the
macro one level higher.
.
.TPx
.REQ .rfschar "f c1 c2 \fR\&.\|.\|.\&\fP"
Remove the font-specific definitions of glyphs
.IR c1 ,
.IR c2 ,
\&.\|.\|.\& for
.RI font\~ f .
.
.TPx
.REQ .rj "n"
Right justify the next
.I n
input lines.
.
.TPx
.REQ .rm "name"
Remove request, macro, diversion, or string
.IR name .
.
.TPx
.REQ .rn "old new"
Rename request, macro, diversion, or string
.I old
to
.IR new .
.
.TPx
.REQ .rnn "reg1 reg2"
Rename register
.I reg1
to
.IR reg2 .
.
.TPx
.REQ .rr "ident"
Remove name of number register
.IR ident .
.
.TPx
.REQ .rs
Restore spacing; turn no-space mode off.
.
.TPx
.REQ .rt
Return
.I (upward only)
to vertical position marked by
.B .mk
on the current page.
.
.TPx
.REQ .rt "\[+-]N"
Return
.I (upward only)
to specified distance from the top of the page (default scaling
indicator\~\c
.scaleindicator v ).
.
.TPx
.REQ .schar "c anything"
Define global fallback character (or glyph)\~\c
.I c
as string
.IR anything .
.
.
.TPx
.REQ .shc
Reset the soft hyphen glyph to
.esc [hy] .
.
.
.TPx
.REQ .shc c
Set the soft hyphen glyph
.RI to\~ c .
.
.
.TPx
.REQ .shift "n"
In a macro, shift the arguments by
.IR n \~\c
positions.
.
.TPx
.REQ .sizes "s1 s2 \fR\&.\|.\|.\&\fP s\fRn\fP \fR[\fB0\fP\fR]\fP"
Set available font sizes similar to the
.B sizes
command in a
.I DESC
file.
.
.
.TPx
.REQ .so file
Interpolate (\[lq]source\[rq])
.IR file .
.
.
.TPx
.REQ .soquiet file
As
.request .so ,
but no warning is emitted if
.I file
does not exist.
.
.
.TPx
.REQ .sp
Skip one line vertically.
.
.TPx
.REQ .sp "N"
Space vertical distance
.I N
up or down according to sign of
.I N
(default scaling indicator\~\c
.scaleindicator v ).
.
.TPx
.REQ .special
Reset global list of special fonts to be empty.
.
.TPx
.REQ .special "s1 s2 \fR\&.\|.\|.\&\fR"
Fonts
.IR s1 ,
.IR s2 ,
etc.\& are special and are searched for glyphs not in the
current font.
.
.TPx
.REQ .spreadwarn
Toggle the spread warning on and off (the default) without changing its
value.
.
.TPx
.REQ .spreadwarn N
Emit a
.B break
warning if the additional space inserted for each space between words in
an output line adjusted to both margins is larger than or equal to
.IR N .
.
A negative
.I N
is treated as 0.
.
The default scaling indicator is\~\c
.scaleindicator m .
.
At startup,
.request .spreadwarn
is inactive and
.I N
is
.scalednumber "3 m" .
.
.TPx
.REQ .ss N
Set minimal inter-word spacing to
.IR N \~12ths
of the space width of the current font.
.
.TPx
.REQ .ss "N M"
As
.B .ss\~\c
.IR N ,
and set additional inter-sentence spacing to
.IR M \~12ths
of the space width of the current font.
.
.TPx
.REQ .stringdown stringvar
Replace each byte in the string named
.I stringvar
with its lowercase version.
.
.TPx
.REQ .stringup stringvar
Replace each byte in the string named
.I stringvar
with its uppercase version.
.
.TPx
.REQ .sty "n style"
Associate
.I style
with font position
.IR n .
.
.TPx
.REQ .substring "str start \fR[\fPend\fR]\fP"
Replace the string named
.I str
with its substring bounded by the indices
.I start
and
.IR end ,
inclusive.
.
Negative indices count backwards from the end of the string.
.
.
.TPx
.REQ .sv
Save
.scalednumber "1 v"
of vertical space.
.TPx
.REQ .sv "N"
Save the vertical distance
.I N
for later output with
.request .os
request (default scaling indicator\~\c
.scaleindicator v ).
.
.TPx
.REQ .sy "command-line"
Execute program
.IR command-line .
.
.TPx
.REQ .ta "T N"
Set tabs after every position that is a multiple of
.I N
(default scaling indicator\~\c
.scaleindicator m ).
.TPx
.REQ .ta "n1 n2 \fR\&.\|.\|.\&\fP n\fRn\fP \f[CB]T\f[] r1 r2 \
\fR\&.\|.\|.\&\fP r\fRn\fP"
Set tabs at positions
.IR n1 ,
.IR n2 ,
\&.\|.\|.\&,
.IR n n,
then set tabs at
.IR n n+ m \[tmu] r n+ r1
through
.IR n n+ m \[tmu] r n+ r n,
where
.I m
increments from 0, 1, 2, \&.\|.\|.\& to infinity.
.
.\".TPx
.\".REQ .tar
.\"Restore internally saved tab positions.
.\".
.\".TPx
.\".REQ .tas
.\"Save tab positions internally.
.
.
.TPx
.REQ .tc
Remove tab repetition glyph.
.
.
.TPx
.REQ .tc "c"
Set tab repetition glyph
.RI to\~ c
(default: none).
.
.
.TPx
.REQ .ti "\[+-]N"
Temporary indent next line (default scaling indicator\~\c
.scaleindicator m ).
.
.TPx
.REQ .tkf "font s1 n1 s2 n2"
Enable track kerning for
.IR font .
.
.TPx
.REQ .tl "\f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\
\f[CB]\[aq]\f[]"
Three-part title.
.
.TPx
.REQ .tm "anything"
Print
.I anything
on stderr.
.
.TPx
.REQ .tm1 "anything"
Print
.I anything
on stderr, allowing leading whitespace if
.I anything
starts with
\&\f[CB]\[dq]\f[]
(which is stripped off).
.
.TPx
.REQ .tmc "anything"
Similar to
.request .tm1
without emitting a final newline.
.
.TPx
.REQ .tr "abcd\fR\&.\|.\|.\&\fP"
Translate
.I a
to
.IR b ,
.I c
to
.IR d ,
etc.\& on output.
.
.TPx
.REQ .trf "filename"
Transparently output the contents of file
.IR filename .
.
.TPx
.REQ .trin "abcd\fR\&.\|.\|.\&\fP"
This is the same as the
.request .tr
request except that the
.B asciify
request uses the character code (if any) before the character
translation.
.
.TPx
.REQ .trnt "abcd\fR\&.\|.\|.\&\fP"
This is the same as the
.request .tr
request except that the translations do not apply to text that is
transparently throughput into a diversion with
.esc ! .
.
.TPx
.REQ .troff
Make the built-in conditions
.B t
true and
.B n
false.
.
.TPx
.REQ .uf "font"
Set underline font to
.I font
(to be switched to by
.request .ul ).
.
.TPx
.REQ .ul "N"
Underline (italicize in troff)
.I N
input lines.
.
.TPx
.REQ .unformat "diversion"
Unformat space characters and tabs in
.IR diversion ,
preserving font information.
.
.
.TPx
.REQ .vpt
Enable vertical position traps.
.
.
.TPx
.B .vpt 0
Disable vertical position traps.
.
.
.TPx
.REQ .vs
Change to previous vertical base line spacing.
.
.TPx
.REQ .vs "\[+-]N"
Set vertical base line spacing to
.I \[+-]N
(default scaling indicator\~\c
.scaleindicator p ).
.
.TPx
.REQ .warn
Enable all warnings.
.
.TPx
.REQ .warn "n"
Set warnings code to
.IR n .
.
.TPx
.REQ .warnscale "si"
Set scaling indicator used in warnings to
.IR si .
.
.
.TPx
.REQ .wh N
Remove active trap at vertical position
.IR N ;
a negative value is measured upward from page bottom.
.
.
.TPx
.REQ .wh "N name"
Plant trap,
calling macro
.I name
when page location
.I N
is reached or passed;
a negative value is measured upward from page bottom.
.
Any active trap already present at
.I N
is replaced.
.
.
.TPx
.REQ .while "cond anything"
While condition
.I cond
is true, accept
.I anything
as input.
.
.TPx
.REQ .write "stream anything"
Write
.I anything
to the stream named
.IR stream .
.
.TPx
.REQ .writec "stream anything"
Similar to
.request .write
without emitting a final newline.
.
.TPx
.REQ .writem "stream xx"
Write contents of macro or string
.I xx
to the stream named
.IR stream .
.
.PD
.
.
.P
Besides these standard groff requests, there might be further macro
calls.
They can originate from a macro package (see
.BR roff (@MAN7EXT@)
for an overview) or from a preprocessor.
.
.
.P
Preprocessor macros are easy to recognize.
.
They enclose their code between a pair of characteristic macros.
.
.
.P
.TS
box, center, tab (^);
c | c | c
CfCB | CfCB | CfCB.
preprocessor^start macro^ end macro
=
@g@chem^.cstart^.cend
@g@eqn^.EQ^.EN
grap^.G1^.G2
@g@grn^.GS^.GE
.\" Keep the .IF line below the @g@ideal line.
@g@ideal^.IS^.IE
^^.IF
@g@pic^.PS^.PE
@g@refer^.R1^.R2
@g@soelim^\f[I]none^\f[I]none
@g@tbl^.TS^.TE
_
glilypond^.lilypond start^.lilypond stop
gperl^.Perl start^.Perl stop
gpinyin^.pinyin start^.pinyin stop
.TE
.
.
.P
The \%\[oq]@g@ideal\[cq] preprocessor is not available in
.I groff
yet.
.
.
.\" ====================================================================
.SH "Escape sequences"
.\" ====================================================================
.
Whereas requests must occur on control lines,
escape sequences can occur intermixed with text and appear in arguments
to requests and macros
(and sometimes other escape sequences).
.
An escape sequence
(or simply \[lq]escape\[rq])
is introduced by the escape character,
a backslash
.RB \[lq] \[rs] \[rq]
(but see the
.B .ec
request).
.
The next character identifies the escape's function.
.
Escapes vary in length.
.
Some take an argument,
and of those,
some have different syntactical forms for a one-character,
two-character,
or arbitrary-length argument.
.
Others accept only an arbitrary-length argument.
.
In the former convention,
a one-character argument follows the function character immediately,
an opening parenthesis
.RB \[lq] ( \[rq]
introduces a two-character argument
(no closing parenthesis is used),
and an argument of arbitrary length is enclosed in brackets
.RB \[lq] [] \[rq].
.
In the latter convention,
the user selects a delimiter character;
the neutral apostrophe
.RB \[lq] \[aq] \[rq]
is a popular choice and shown in this document.
.
Some characters cannot be used as delimiters;
see section \[lq]Escapes\[rq] in the
.I groff
Texinfo manual for details.
.
A few escapes are idiosyncratic,
and support both of the foregoing conventions
.RB (\[lq] \[rs]s \[rq]),
designate their own terminating character
.RB (\[lq] \[rs]? \[rq]),
consume input until the next newline
.RB (\[lq] \[rs]! \[rq],
.RB \[lq] \[rs]" \[rq],
.RB \[lq] \[rs]# \[rq]),
or support an additional modifier character
.RB (\[lq] \[rs]s \[rq]
again).
.
.
.P
Escape sequences serve a variety of purposes.
.
Widespread uses include
commenting the source document;
changing the font style;
setting the point size;
interpolating special characters,
number registers,
and strings into the text;
and placing or suppressing break and hyphenation points.
.
As with requests,
use of escapes in source documents may interact poorly with a macro
package you use;
consult its documentation to learn of \[lq]safe\[rq] escapes or
alternative facilities it provides to achieve the desired result.
.
.
.\" ====================================================================
.SS "Escape short reference"
.\" ====================================================================
.
.PD 0
.
.\" ========= comments =========
.
.TP
.ESC \[dq]
Start of a comment.
.
Everything up to the end of the line is ignored.
.
.TP
.ESC #
Everything up to and including the next newline is ignored.
.
This is interpreted in copy mode.
.
This is like
.esc \[dq]
except that the terminating newline is ignored as well.
.
.\" ========= strings =========
.
.TP
.ESC * s
The string stored in the string variable with one-character name\~\c
.IR s .
.
.TP
.ESC *( st
The string stored in the string variable with two-character name
.IR st .
.
.TP
.ESC[] * string
The string stored in the string variable with name
.I string
(with arbitrary length).
.
.TP
.ESC[] * "stringvar arg1 arg2 \fR\&.\|.\|.\fP"
The string stored in the string variable with arbitrarily long name
.IR stringvar ,
taking
.IR arg1 ,
.IR arg2 ,
\&.\|.\|.\&
as arguments.
.
.\" ========= macro arguments =========
.
.TP
.ESC $0
The name by which the current macro was invoked.
.
The
.request .als
request can make a macro have more than one name.
.
.TP
.ESC $ x
Macro or string argument with one-digit number\~\c
.I x
in the range 1 to\~9.
.
.TP
.ESC $( xy
Macro or string argument with two-digit number
.I xy
(larger than zero).
.
.TP
.ESC[] $ nexp
Macro or string argument with number
.IR nexp ,
where
.I nexp
is a numerical expression evaluating to an integer \[>=]1.
.
.TP
.ESC $*
In a macro or string, the concatenation of all the arguments separated
by spaces.
.
.TP
.ESC $@
In a macro or string, the concatenation of all the arguments with each
surrounded by double quotes, and separated by spaces.
.
.TP
.ESC $\[ha]
In a macro, the representation of all parameters as if they were an
argument to the
.request .ds
request.
.
.\" ========= escaped characters =========
.
.TP
.ESC \e
reduces to a single backslash; useful to delay its interpretation as
escape character in copy mode.
.
For a printable backslash, use
.esc e ,
or even better
.esc [rs] ,
to be independent from the current escape character.
.
.TP
.ESC \[aq]
The acute accent \[aa]; same as
.esc (aa .
.
.TP
.ESC \[ga]
The grave accent \[ga]; same as
.esc (ga .
.
.TP
.ESC \-
The \- (minus) sign in the current font.
.
.TP
.ESC _
The same as
.esc (ul ,
the underline character.
.
.TP
.ESC .
The same as a dot (\[oq].\[cq]).
Necessary in nested macro definitions so that \[oq]\[rs]\[rs]..\[cq]\&
expands to \[oq]..\[cq].
.
.TP
.ESC %
Default hyphenation character.
.
.TP
.ESC !
Transparent line indicator.
.
.TP
.ESC? anything
In a diversion, this transparently embeds
.I anything
in the diversion.
.I anything
is read in copy mode.
.
See also the escape sequences
.esc !
and
.esc ? .
.
.
.\" ========= spacing [sic; \& and \) don't really space] =========
.
.TP
.ESC \& space
Unpaddable space size space glyph (no line break).
.
.TP
.ESC 0
Digit-width unbreakable space.
.
.TP
.ESC |
1/6\ em narrow unbreakable space glyph;
zero-width in
.IR nroff .
.
.TP
.ESC \[ha]
1/12\ em half-narrow unbreakable space glyph;
zero-width in
.IR nroff .
.
.TP
.ESC &
Non-printing input break.
.
.TP
.ESC )
Like
.esc &
except that it behaves like a glyph declared with the
.request .cflags
request to be transparent for the purposes of end-of-sentence
recognition.
.
.TP
.ESC /
Increases the width of the preceding glyph so that the spacing
between that glyph and the following glyph is correct if
the following glyph is a roman glyph.
.
.TP
.ESC ,
Modifies the spacing of the following glyph so that the spacing
between that glyph and the preceding glyph is correct if the
preceding glyph is a roman glyph.
.
.TP
.ESC \[ti]
Unbreakable space that stretches like a normal inter-word space when a
line is adjusted.
.
.TP
.ESC :
Insert a non-printing break point
(similar to
.esc %
but without a soft hyphen character).
.
.
.TP
.ESC "" newline
Ignored newline, for continuation lines.
.
.\" ========= structuring =========
.
.TP
.ESC {
Begin conditional input.
.
.TP
.ESC }
End conditional input.
.
.\" ========= longer escape names =========
.
.TP
.ESC ( sc
A glyph with two-character name
.IR sc ;
see section \[lq]Special Characters\[rq] below.
.
.TP
.ESC[] "" name
A glyph with name
.I name
(of arbitrary length).
.
.TP
.ESC[] "" "comp1 comp2 \fR\&.\|.\|.\&\fP"
A composite glyph with components
.IR comp1 ,
.IR comp2 ,
\&.\|.\|.
.
.\" ========= alphabetical escapes =========
.
.TP
.ESC a
Non-interpreted leader character.
.
.TP
.ESCq A anything
If
.I anything
is acceptable as a name of a string, macro, diversion, register,
environment or font it expands to\~1, and to\~0 otherwise.
.
.TP
.ESCq b abc\fR\&.\|.\|.\&\fP
Bracket building function.
.
.TP
.ESCq B anything
If
.I anything
is acceptable as a valid numeric expression it expands to\~1, and
to\~0 otherwise.
.
.TP
.ESC c
Continue output line at next input line.
Anything after this escape on the same line is ignored except
.ESC R
(which works as usual).
Anything before
.ESC c
on the same line is appended to the current partial output line.
The next non-command line after a line interrupted with
.ESC c
counts as a new input line.
.
.TP
.ESCq C glyph
The glyph called
.IR glyph ;
same as
.esc[] "" glyph ,
but compatible to other roff versions.
.
.TP
.ESC d
Forward (down) 1/2 em (1/2 line in nroff).
.
.TP
.ESCq D charseq
Draw a graphical element defined by the characters in
.IR charseq ;
see the
.I groff
Texinfo manual for details.
.
.TP
.ESC e
Printable version of the current escape character.
.
.TP
.ESC E
Equivalent to an escape character, but is not interpreted in copy mode.
.
.TP
.ESC f F
Change to font with one-character name or one-digit number\~\c
.IR F .
.
.TP
.ESC fP
Switch back to previous font.
.
.TP
.ESC f( fo
Change to font with two-character name or two-digit number
.IR fo .
.
.TP
.ESC[] f font
Change to font with arbitrarily long name or number expression
.IR font .
.
.TP
.ESC[] f ""
Switch back to previous font.
.
.TP
.ESC F f
Change to font family with one-character name\~\c
.IR f .
.
.TP
.ESC F( fm
Change to font family with two-character name
.IR fm .
.
.TP
.ESC[] F fam
Change to font family with arbitrarily long name
.IR fam .
.
.TP
.ESC[] F ""
Switch back to previous font family.
.
.TP
.ESC g r
Return format of register with one-character name\~\c
.I r
suitable for
.request .af
request.
.
.TP
.ESC g( rg
Return format of register with two-character name
.I rg
suitable for
.request .af
request.
.
.TP
.ESC[] g reg
Return format of register with arbitrarily long name
.I reg
suitable for
.request .af
request.
.
.TP
.ESCq h N
Local horizontal motion; move right
.I N
(left if negative).
.
.TP
.ESCq H N
Set height of current font to
.IR N .
.
.TP
.ESC k r
Mark horizontal position in one-character
.RI register\~ r .
.
.TP
.ESC k( rg
Mark horizontal position in two-character
.RI register\~ rg .
.
.TP
.ESC[] k reg
Mark horizontal position in register with arbitrarily long
.RI name\~ reg .
.
.TP
.ESCq l Nc
Horizontal line drawing function (optionally using character
.IR c ).
.
.TP
.ESCq L Nc
Vertical line drawing function (optionally using character
.IR c ).
.
.TP
.ESC m c
Change to color with one-character name\~\c
.IR c .
.
.TP
.ESC m( cl
Change to color with two-character name
.IR cl .
.
.TP
.ESC[] m color
Change to color with arbitrarily long name
.IR color .
.
.TP
.ESC[] m ""
Switch back to previous color.
.
.TP
.ESC M c
Change filling color for closed drawn objects to color with
one-character name\~\c
.IR c .
.
.TP
.ESC M( cl
Change filling color for closed drawn objects to color with
two-character name
.IR cl .
.
.TP
.ESC[] M color
Change filling color for closed drawn objects to color with
arbitrarily long name
.IR color .
.
.TP
.ESC[] M ""
Switch to previous fill color.
.
.TP
.ESC n r
The numerical value stored in the register variable with the
one-character name\~\c
.IR r .
.
.TP
.ESC n( re
The numerical value stored in the register variable with the
two-character name
.IR re .
.
.TP
.ESC[] n reg
The numerical value stored in the register variable with arbitrarily
long name
.IR reg .
.
.TP
.ESCq N n
Typeset the glyph with index\~\c
.I n
in the current font.
.
No special fonts are searched.
.
Useful for adding (named) entities to a document using the
.request .char
request and friends.
.
.TP
.ESCq o abc\fR\&.\|.\|.\&\fP
Overstrike glyphs
.IR a ,
.IR b ,
.IR c ,
etc.
.
.TP
.ESC O0
Disable glyph output.
.
Mainly for internal use.
.
.TP
.ESC O1
Enable glyph output.
.
Mainly for internal use.
.
.TP
.ESC p
Break output line at next word boundary; adjust if applicable.
.
.TP
.ESC r
Reverse 1\ em vertical motion (reverse line in nroff).
.
.TP
.ESCq R "name\~\[+-]n"
The same as
.request .nr
.I name
.IR \[+-]n .
.
.TP
.ESC s \[+-]N
Set/increase/decrease the point size to/by
.I N
scaled points.
.
.I N
must be a single digit;
0 restores the previous point size.
.
(In compatibility mode only,
a non-zero
.I N
must be in the range 4\[en]39.)
.
Otherwise,
same as
.request .ps
request.
.
.TP
.ESC s( \[+-]N
.TQ
.fam C
.BI \es \[+-] ( N
.fam
Set/increase/decrease the point size to/by
.I N
scaled points;
.I N
is a two-digit number \[>=]1.
.
Same as
.request .ps
request.
.
.TP
.ESC[] s \[+-]N
.TQ
.fam C
.BI \es \[+-] [ N ]
.fam
.TQ
.ESCq s \[+-]N
.TQ
.fam C
.BI \es \[+-] \[aq] N \[aq]
.fam
Set/increase/decrease the point size to/by
.I N
scaled points.
.
Same as
.request .ps
request.
.
.TP
.ESCq S N
Slant output by
.I N
degrees.
.
.TP
.ESC t
Non-interpreted horizontal tab.
.
.TP
.ESC u
Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
.
.TP
.ESCq v N
Local vertical motion; move down
.I N
(up if negative).
.
.TP
.ESC V e
The contents of the environment variable with one-character
name\~\c
.IR e .
.
.TP
.ESC V( ev
The contents of the environment variable with two-character name
.IR ev .
.
.TP
.ESC[] V env
The contents of the environment variable with arbitrarily long name
.IR env .
.
.TP
.ESCq w string
The width of the glyph sequence
.IR string .
.
.TP
.ESCq x N
Extra line-space function (negative before, positive after).
.
.TP
.ESCq X string
Output
.I string
as device control function.
.
.TP
.ESC Y n
Output string variable or macro with one-character name\~\c
.I n
uninterpreted as device control function.
.
.TP
.ESC Y( nm
Output string variable or macro with two-character name
.I nm
uninterpreted as device control function.
.
.TP
.ESC[] Y name
Output string variable or macro with arbitrarily long name
.I name
uninterpreted as device control function.
.
.TP
.ESC z c
Print
.I c
with zero width (without spacing).
.
.TP
.ESCq Z anything
Print
.I anything
and then restore the horizontal and vertical position;
.I anything
may not contain tabs or leaders.
.
.
.PD
.P
The escape sequences
.esc e ,
.esc . ,
.esc \[dq] ,
.esc $ ,
.esc * ,
.esc a ,
.esc n ,
.esc t ,
.esc g ,
and
.escarg \& newline
are interpreted in copy mode.
.
.
.P
Escape sequences starting with
.esc (
or
.esc [
do not represent single character escape sequences, but introduce escape
names with two or more characters.
.
.
.P
If a backslash is followed by a character that does not constitute a
defined escape sequence, the backslash is silently ignored and the
character maps to itself.
.
.
.\" ====================================================================
.SS Identifiers
.\" ====================================================================
.
An identifier is a label for an object of syntactical importance like
a register,
a name
(macro,
string,
diversion,
or box),
an environment,
a font,
a style,
or a glyph,
comprising a sequence of one or more characters with the following
exceptions.
.
.
.IP \[bu]
Spaces,
tabs,
or newlines.
.
.
.IP \[bu]
Invalid input characters;
these are certain control characters
(from the sets \[lq]C0 Controls\[rq] and \[lq]C1 Controls\[rq] as
Unicode describes them).
.
When
.I \%@g@troff
encounters one in an identifier,
it produces a warning diagnostic of type
.RB \[lq] input \[rq]
(see section \[lq]Warnings\[rq] in
.IR \%@g@troff (@MAN1EXT@)).
.
.
.IP
On a machine using the ISO 646,
8859,
or 10646 character encodings,
invalid input characters are
.BR 0x00 ,
.BR 0x08 ,
.BR 0x0B ,
.BR 0x0D \[en] 0x1F ,
and
.BR 0x80 \[en] 0x9F .
.
.
.IP
On an EBCDIC host,
they are
.BR 0x00 \[en] 0x01 ,
.BR 0x08 ,
.BR 0x09 ,
.BR 0x0B ,
.BR 0x0D \[en] 0x14 ,
.BR 0x17 \[en] 0x1F ,
and
.BR 0x30 \[en] 0x3F .
.
.
.IP
Some of these code points are used by
.I \%@g@troff
internally,
making it non-trivial to extend the program to cover Unicode or other
character encodings that use characters from these ranges.
.
(Consider what happens when a C1 control
.BR 0x80 \[en] 0x9F
is necessary as a continuation byte in a UTF-8 sequence.}
.
.
.IP
Invalid characters are removed during parsing;
an identifier
.RB \[lq] foo \[rq],
followed by an invalid character,
followed by
.RB \[lq] bar \[rq]
is treated as
.RB \[lq] foobar \[rq] .
.
.
.\" ====================================================================
.SS "Special characters"
.\" ====================================================================
.
[Note: \[oq]Special Characters\[cq] is a misnomer; those entities are
(output) glyphs, not (input) characters.]
.
.
.P
Common special characters are predefined by escape sequences of the
form
.BI \e( xy
with characters
.I x
and
.IR y .
.
In
.IR groff ,
it is also possible to use the form
.BI \e[ xy ]\c
\&.
.
.
.P
Some of these special characters exist in the usual font while most of
them are only available in the special font.
.
Below you can see a small selection of the most important glyphs; a
complete list can be found in
.BR groff_char (@MAN7EXT@).
.RS
.P
.PD 0
.
.TP
.ESC (Do
Dollar
.B \(Do
.
.TP
.ESC (Eu
Euro
.B \(Eu
.
.TP
.ESC (Po
British pound sterling
.B \(Po
.
.TP
.ESC (aq
Apostrophe quote
.B \(aq
.
.TP
.ESC (bu
Bullet sign
.B \(bu
.
.TP
.ESC (co
Copyright
.B \(co
.
.TP
.ESC (cq
Single closing quote (right)
.B \(cq
.
.TP
.ESC (ct
Cent
.B \(ct
.
.TP
.ESC (dd
Double dagger
.B  \(dd
.
.TP
.ESC (de
Degree sign
.B \(de
.
.TP
.ESC (dg
Dagger
.B \(dg
.
.TP
.ESC (dq
Double quote
.B \(dq
.
.TP
.ESC (em
Em-dash
.B \(em
.
.TP
.ESC (en
En-dash
.B \(en
.
.TP
.ESC (ha
Caret/spacing circumflex accent (\[lq]hat\[rq])
.B \(ha
.
.TP
.ESC (hy
Hyphen
.B \(hy
.
.TP
.ESC (lq
Double quote left
.B \(lq
.
.TP
.ESC (oq
Single opening quote (left)
.B \(oq
.
.TP
.ESC (rg
Registered sign
.B \(rg
.
.TP
.ESC (rq
Double quote right
.B \(rq
.
.TP
.ESC (rs
Reverse solidus/backslash
.B \(rs
.
.TP
.ESC (sc
Section sign
.B \(sc
.
.TP
.ESC (ti
Tilde (spacing)
.B \(ti
.
.TP
.ESC (tm
Trademark symbol
.B \(tm
.
.TP
.ESC (ul
Underline character
.B \(ul
.
.TP
.ESC (==
Identical
.B \(==
.
.TP
.ESC (>=
Larger or equal
.B \(>=
.
.TP
.ESC (<=
Less or equal
.B \(<=
.
.TP
.ESC (!=
Not equal
.B \(!=
.
.TP
.ESC (\->
Right arrow
.B \(->
.
.TP
.ESC (<\-
Left arrow
.B \(<-
.
.TP
.ESC (+\-
Plus-minus sign
.B \(+-
.
.PD
.RE
.
.
.\" ====================================================================
.SS "Unicode characters"
.\" ====================================================================
.
The extended escape
.B u
allows the inclusion of all available Unicode characters into a
.I roff
file.
.
.
.TP
.BI \e[u xxxx ]
.B u
is the escape name.
.
.I xxxx
is a hexadecimal number of four hex digits, such as
.B 0041
for the letter
.BR A ,
thus
.BR \e[u0041] .
.
.
.TP
.BI \e[u yyyyy ]
.B u
is the escape name.
.
.I yyyyy
is a hexadecimal number of five hex digits, such as
.B 2FA1A
for a Chinese-looking character from the Unicode block
.IR "CJK Compatibility Ideographs Supplement" ,
thus
.BR \e[u2FA1A] .
.
.
.P
The hexadecimal value indicates the corresponding Unicode code point for
a character.
.
.
.TP
.BI \e[u hex1 _ hex2 ]
.TQ
.BI \e[u hex1 _ hex2 _ hex3 ]
.IR hex1 ,
.IR hex2 ,
and
.I hex3
are all Unicode hexadecimal codes (4 or 5 hex digits) that are used
for overstriking, e.g.,
.B \e[u0041_0301]
is
.IR "A acute" ,
which can also be specified as
.BR \['A] ;
see
.BR groff_char (@MAN7EXT@).
.
.
.P
The availability of the Unicode characters depends on the font used.
.
For text mode, the device
.B \-Tutf8
is quite complete; for
.I troff
modes it might happen that some or many characters will not be
displayed.
.
Please check your fonts.
.
.
.\" ====================================================================
.SS Strings
.\" ====================================================================
.
.I groff
has string variables primarily for user convenience.
.
Only one string is predefined by the language.
.
.
.TPx
.STRING .T
Contains the name of the output driver
(for example,
.RB \[lq] utf8 \[rq]
or
.RB \[lq] pdf \[rq] ).
.
.
.P
The
.request .ds
request creates a string with a specified name and contents
and the
.esc *
escape dereferences its name,
retrieving the contents.
.
Dereferencing an undefined string name defines it as empty.
.
.
.P
The
.request .as
request is similar to
.request .ds
but appends to a string instead of redefining it.
.
If
.request .as
is called with only one argument,
no operation is performed
(beyond dereferencing it).
.
.
.P
The
.request .ds1
request defines a string such that compatibility mode is off when the
string is later interpolated.
.
To be more precise,
a
.I compatibility save
input token is inserted at the beginning of the string,
and a
.I compatibility restore
input token at the end.
.
Likewise,
the
.request .as1
request is similar to
.BR .as ,
but compatibility mode is switched off when the appended portion of the
string is later interpolated.
.
.
.P
.B Caution:
Unlike other requests,
the second argument to these requests consumes the remainder of the
input line,
including trailing spaces.
.
It is good style to end string definitions
(and appendments)
with a comment,
even an empty one,
to prevent unwanted space from creeping into them during source document
maintenance.
.
.
.P
To store leading space in a string,
start it with a double quote.
.
A double quote is special only in that position;
double quotes in any other location are included in the string
(the effects of escape sequences notwithstanding).
.
.
.P
Strings,
macros,
and diversions
(and boxes)
share the same name space.
.
Internally,
the same mechanism is used to store them.
.
.
.P
Several requests exist to perform rudimentary string operations.
.
Strings can be queried
(\c
.request .length )
and modified
(\c
.request .chop ,
.request .substring ,
.request .stringup ,
.request .stringdown ),
and their names can be manipulated through renaming,
removal,
and aliasing
(\c
.request .rn ,
.request .rm ,
.request .als).
.
.
.\" ====================================================================
.SH Registers
.\" ====================================================================
.
Registers are variables that store a value.
.
In groff,
most registers store numerical values
(see section \[lq]Numerical Expressions\[rq] above),
but some can also hold a string value.
.
.
.P
Each register is given a name.
Arbitrary registers can be defined and set with the
.request .nr
request.
.
.
.P
The value stored in a register can be retrieved by the escape sequences
introduced by
.esc n .
.
.
.P
Most useful are predefined registers.
.
In the following the notation
.I name
is used to refer to
.register name
to make clear that we speak about registers.
.
Please keep in mind that the
.esc[] n ""
decoration is not part of the register name.
.
.
.\" ====================================================================
.SS "Read-only registers"
.\" ====================================================================
.
The following registers have predefined values that should not be
modified by the user (usually, registers starting with a dot are
read-only).
.
Mostly, they provide information on the current settings or store
results from request calls.
.
.
.P
.PD 0
.
.TPx
.REG $$
The process ID of
.BR troff .
.
.TPx
.REG .$
Number of arguments in the current macro or string.
.
.TPx
.REG .a
Post-line extra line-space most recently utilized using
.esc x .
.
.TPx
.REG .A
Set to\~1 in
.B troff
if option
.option \-A
is used; always\~1 in
.BR nroff .
.
.TPx
.REG .b
The emboldening offset while
.request .bd
is active.
.
.TPx
.REG .br
Within a macro, set to\~1 if macro called with the \[oq]normal\[cq]
control character, and to\~0 otherwise.
.
.TPx
.REG .c
Current input line number.
.
.TPx
.REG .C
1\~if compatibility mode is in effect, 0\~otherwise.
.
Always\~0 in a
.request .do
request;
see
.register .cp
below.
.
.TPx
.REG .cdp
The depth of the last glyph added to the current environment.
.
It is positive if the glyph extends below the baseline.
.
.TPx
.REG .ce
The number of lines remaining to be centered, as set by the
.request .ce
request.
.
.TPx
.REG .cht
The height of the last glyph added to the current environment.
.
It is positive if the glyph extends above the baseline.
.
.TPx
.REG .color
1\~if colors are enabled, 0\~otherwise.
.
.TPx
.REG .cp
Within a
.request .do
request,
the saved value of compatibility mode (see
.register .C
above).
.
.TPx
.REG .csk
The skew of the last glyph added to the current environment.
.
The 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.
.
.TPx
.REG .d
Current vertical place in current diversion; equal to register
.BR nl .
.
.TPx
.REG .ev
The name or number of the current environment (string-valued).
.
.TPx
.REG .f
Current font number.
.
.TPx
.REG .F
The name of the current input file (string-valued).
.
.TPx
.REG .fam
The current font family (string-valued).
.
.TPx
.REG .fn
The current (internal) real font name (string-valued).
.
.TPx
.REG .fp
The number of the next free font position.
.
.TPx
.REG .g
Always 1 in GNU troff.
.
Macros should use it to test if running under groff.
.
.TPx
.REG .h
Text base-line high-water mark on current page or diversion.
.
.TPx
.REG .H
Number of basic units per horizontal unit of output device resolution.
.
.TPx
.REG .height
The current font height as set with
.esc H .
.
.TPx
.REG .hla
The hyphenation language in the current environment.
.
.TPx
.REG .hlc
The count of immediately preceding consecutive hyphenated lines in the
current environment.
.
.TPx
.REG .hlm
The maximum number of consecutive hyphenated lines allowed in the
current environment.
.
.TPx
.REG .hy
The automatic hyphenation mode in the current environment.
.
.TPx
.REG .hym
The hyphenation margin in the current environment.
.
.TPx
.REG .hys
The hyphenation space adjustment threshold in the current environment.
.
.TPx
.REG .i
Current indentation.
.
.TPx
.REG .in
The indentation that applies to the current output line.
.
.TPx
.REG .int
Positive if last output line contains
.esc c .
.
.
.TPx
.REG .j
Adjustment mode encoded as an integer.
.
Do not interpret or perform arithmetic on its value.
.
.
.TPx
.REG .k
The current horizontal output position (relative to the current
indentation).
.
.
.TPx
.REG .kern
1\~if pairwise kerning is enabled, 0\~otherwise.
.
.TPx
.REG .l
Current line length.
.
.TPx
.REG .L
The current line spacing setting as set by
.request .ls .
.
.TPx
.REG .lg
The current ligature mode (as set by the
.request .lg
request).
.
.TPx
.REG .linetabs
The current line-tabs mode (as set by the
.request .linetabs
request).
.
.TPx
.REG .ll
The line length that applies to the current output line.
.
.TPx
.REG .lt
The title length (as set by the
.request .lt
request).
.
.TPx
.REG .m
The current drawing color (string-valued).
.
.TPx
.REG .M
The current background color (string-valued).
.
.TPx
.REG .n
Length of text portion on previous output line.
.
.TPx
.REG .ne
The amount of space that was needed in the last
.request .ne
request that caused a trap to be sprung.
.
Useful in conjunction with register
.BR .trunc .
.
.
.TPx
.REG .nm
1\~if output line numbering is enabled
(even if temporarily suppressed),
0\~otherwise.
.
.
.TPx
.REG .ns
1\~if in no-space mode, 0\~otherwise.
.
.TPx
.REG .o
Current page offset.
.
.TPx
.REG .O
The suppression nesting level (see
.esc O ).
.
.TPx
.REG .p
Current page length.
.
.TPx
.REG .P
1\~if the current page is being printed, 0\~otherwise (as determined by
the
.option \-o
command-line option).
.
.TPx
.REG .pe
1\~during page ejection, 0\~otherwise.
.
.TPx
.REG .pn
The number of the next page: either the value set by a
.request .pn
request, or the number of the current page plus\ 1.
.
.TPx
.REG .ps
The current point size in scaled points.
.
.TPx
.REG .psr
The last-requested point size in scaled points.
.
.TPx
.REG .pvs
The current post-vertical line spacing.
.
.TPx
.REG .R
The number of unused number registers.
Always 10000 in GNU troff.
.
.TPx
.REG .rj
The number of lines to be right-justified as set by the
.request .rj
request.
.
.TPx
.REG .s
Current point size as a decimal fraction.
.
.TPx
.REG .slant
The slant of the current font as set with
.esc S .
.
.TPx
.REG .sr
The last requested point size in points as a decimal fraction
(string-valued).
.
.TPx
.REG .ss
Size of minimal inter-word spacing in twelfths of the space width of the
current font.
.
.TPx
.REG .sss
Size of additional inter-sentence spacing in twelfths of the space width
of the current font.
.
.TPx
.REG .sty
The current font style (string-valued).
.
.
.TPx
.REG .t
Distance to the next vertical position trap.
.
.
.TPx
.REG .T
Set to\~1
if option
.option \-T
is used.
.
.TPx
.REG .tabs
A string representation of the current tab settings suitable for use
as an argument to the
.request .ta
request.
.
.TPx
.REG .trunc
The amount of vertical space truncated by the most recently sprung
vertical position trap,
or,
if the trap was sprung by an
.request .ne
request,
minus the amount of vertical motion produced by
.request .ne .
.
Useful in conjunction with the
.register .ne .
.
.TPx
.REG .u
Equal to 1 in fill mode and 0 in no-fill mode.
.
.TPx
.REG .U
Equal to 1 in safer mode and 0 in unsafe mode.
.
.TPx
.REG .v
Current vertical line spacing.
.
.TPx
.REG .V
Number of basic units per vertical unit of output device resolution.
.
.
.TPx
.REG .vpt
1\~if vertical position traps are enabled, 0\~otherwise.
.
.
.TPx
.REG .w
Width of previous glyph.
.
.TPx
.REG .warn
The sum of the number codes of the currently enabled warnings.
.
.TPx
.REG .x
The major version number.
.
.TPx
.REG .y
The minor version number.
.
.TPx
.REG .Y
The revision number of groff.
.
.TPx
.REG .z
Name of current diversion.
.
.TPx
.REG .zoom
Zoom factor for current font (in multiples of 1/1000th; zero if no
magnification).
.PD
.
.
.\" ====================================================================
.SS "Writable registers"
.\" ====================================================================
.
The following registers can be read and written by the user.
They have predefined default values, but these can be modified for
customizing a document.
.
.
.P
.PD 0
.TPx
.REG %
Current page number.
.
.TPx
.REG c.
Current input line number.
.
.TPx
.REG ct
Character type (set by width function
.esc w ).
.
.TPx
.REG dl
Maximal width of last completed diversion.
.
.TPx
.REG dn
Height of last completed diversion.
.
.TPx
.REG dw
Current day of week (1\(en7).
.
.TPx
.REG dy
Current day of month (1\(en31).
.
.TPx
.REG hours
The number of hours past midnight.
.
Initialized at start-up.
.
.TPx
.REG hp
Current horizontal position at input line.
.
.TPx
.REG llx
Lower left x-coordinate (in PostScript units) of a given PostScript
image (set by
.request .psbb ).
.
.TPx
.REG lly
Lower left y-coordinate (in PostScript units) of a given PostScript
image (set by
.request .psbb ).
.
.TPx
.REG ln
Output line number.
.
.
.TPx
.REG lsn
The count of leading spaces on an input line.
.
.
.TPx
.REG lss
The amount of horizontal space corresponding to the leading spaces
on an input line.
.
.
.TPx
.REG minutes
The number of minutes after the hour.
.
Initialized at start-up.
.
.TPx
.REG mo
Current month (1\(en12).
.
.TPx
.REG nl
Vertical position of last printed text base-line.
.
.TPx
.REG opmaxx
.TPx
.REG opmaxy
.TPx
.REG opminx
.TPx
.REG opminy
These four registers mark the top left and bottom right hand corners of
a box which encompasses all written glyphs.
They are reset to \-1 by
.B \[rs]O0
or
.BR \[rs]O1 .
.
.TPx
.REG rsb
Like register
.BR sb ,
but takes account of the heights and depths of glyphs.
.
.TPx
.REG rst
Like register
.BR st ,
but takes account of the heights and depths of glyphs.
.
.TPx
.REG sb
Depth of string below base line (generated by width function
.esc w ).
.
.TPx
.REG seconds
The number of seconds after the minute.
.
Initialized at start-up.
.
.TPx
.REG skw
Right skip width from the center of the last glyph in the
.esc w
argument.
.
.TPx
.REG slimit
If greater than 0, the maximum number of objects on the input stack.
.
If \[<=]0 there is no limit, i.e., recursion can continue until virtual
memory is exhausted.
.
.TPx
.REG ssc
The amount of horizontal space (possibly negative) that should be
added to the last glyph before a subscript (generated by width
function
.esc w ).
.
.TPx
.REG st
Height of string above base line (generated by width function
.esc w ).
.
.TPx
.REG systat
The return value of the
.I system()
function executed by the last
.request .sy
request.
.
.TPx
.REG urx
Upper right x-coordinate (in PostScript units) of a given PostScript
image (set by
.request .psbb ).
.
.TPx
.REG ury
Upper right y-coordinate (in PostScript units) of a given PostScript
image (set by
.request .psbb ).
.
.TPx
.REG year
The current year.
.
.TPx
.REG yr
The current year minus 1900.
.
.PD
.
.
.\" ====================================================================
.SH Hyphenation
.\" ====================================================================
.
When filling,
.I groff
hyphenates words as needed at user-specified and automatically
determined hyphenation points.
.
Explicitly hyphenated words such as \[lq]mother-in-law\[rq] are eligible
for breaking after each of their hyphens.
.
The hyphenation
.RB character\~ \[rs]%
and non-printing break
.RB point\~ \[rs]:
escapes may be used to control the hyphenation and breaking of
individual words.
.
The
.B .hw
request sets user-defined hyphenation points for specified words at any
subsequent occurrence.
.
Otherwise,
.I groff
determines hyphenation points automatically by default.
.
.
.P
Several requests influence automatic hyphenation.
.
Because conventions vary,
a variety of hyphenation modes is available to the
.B .hy
request;
these determine whether hyphenation will apply to a word prior to
breaking a line at the end of a page
(more or less;
see below for details),
and at which positions within that word automatically determined
hyphenation points are permissible.
.
The default is
.RB \[lq] 1 \[rq]
for historical reasons,
but this is not an appropriate value for the English hyphenation
patterns used by
.IR groff ,
and macro packages often override it.
.
.
.TP
.B 0
disables hyphenation.
.
.
.TP
.B 1
enables hyphenation except after the first and before the last character
of a word.
.
.
.P
The remaining values \[lq]imply\[rq]
.BR 1 ;
that is,
they enable hyphenation under the same conditions as
.RB \[lq] ".hy 1" \[rq],
and then apply or lift restrictions relative to that basis.
.
.
.TP
.B 2
disables hyphenation of the last word on a page.
.
(Technically,
hyphenation is prevented if the next page position trap is closer than
the next line of text would be.
.
.I groff
automatically inserts an implicit page position trap at the end of each
page to cause a page transition.
.
Users or macro packages can set such traps explicitly to prevent
hyphenation of the last word in a column in multi-column page layouts or
before floating figures or tables.
.
See section \[lq]Traps\[rq] below.)
.
.
.TP
.B 4
disables hyphenation before the last two characters of a word.
.
.
.TP
.B 8
disables hyphenation after the first two characters of a word.
.
.
.TP
.B 16
enables hyphenation before the last character of a word.
.
.
.TP
.B 32
enables hyphenation after the first character of a word.
.
.
.P
Apart from value\~2,
restrictions imposed by the hyphenation mode are
.I not
respected for words whose hyphenations have been explicitly specified
with the hyphenation character
.RB (\[lq] \[rs]% \[rq]
by default)
or the
.B .hw
request.
.
.
.P
The nonzero values above are additive.
.
For example,
value\~12 causes
.I groff
to hyphenate neither the last two nor the first two characters of a
word.
.
Some values cannot be used together because they contradict;
for instance,
values 4 and\~16,
and values 8 and\~32.
.
As noted,
it is superfluous to add\~1 to any nonzero even mode.
.
.
.P
The places within a word that are eligible for hyphenation are
determined by language-specific data
.RB ( .hla ,
.BR .hpf ,
and
.BR .hpfa )
and lettercase relationships
.RB ( .hcode
and
.BR .hpfcode ).
.
Furthermore,
hyphenation of a word might be suppressed because too many previous
lines have been hyphenated
.RB ( .hlm ),
the line has not reached a certain minimum length
.RB ( .hym ),
or the line can instead be adjusted with up to a certain amount of
additional inter-word space
.RB ( .hys ).
.
See
.IR groff_diff (@MAN7EXT@)
or the
.I groff
Texinfo manual for further details.
.
.
.\" ====================================================================
.SH Traps
.\" ====================================================================
.
.I Traps
are locations in the output,
or conditions on the input that,
when reached or fulfilled,
cause a specified macro to be called.
.
These traps can occur at a given location on the page
.RB ( .wh ,\~ .ch );
at a given location in the current diversion
.RB ( .dt )\[em]together,
these are known as
vertical position traps,
which can be disabled and re-enabled
.RB ( .vpt );
at a blank line
.RB ( .blm );
at a line with leading space characters
.RB ( .lsm );
after a certain number of input lines
.RB ( .it ,\~ .itc );
or at the end of input
.RB ( .em ).
.
Macros called by traps have no arguments.
.
Setting a trap is also called
.IR planting .
.
It is also said that a trap is
.I sprung
if the associated macro is executed.
.
.
.P
Registers associated with trap management include
vertical position trap enablement status
.RB ( \[rs]n[.vpt] ),
distance to the next trap
.RB ( \[rs]n[.t] ),
amount of needed
.RB ( .ne -requested )
space that caused the most recent vertical position trap to be sprung
.RB ( \[rs]n[.ne] ),
amount of needed space truncated from the amount requested
.RB ( \[rs]n[.trunc] ),
page ejection status
.RB ( \[rs]n[.pe] ),
and
leading space count
.RB ( \[rs]n[.lsn] )
with its corresponding amount of motion
.RB ( \[rs]n[.lss] ).
.
.
.\" ====================================================================
.SH Underlining
.\" ====================================================================
.
In the
.I RUNOFF
language, the underlining was quite easy.
.
But in
.I roff
this is much more difficult.
.
.
.\" ====================================================================
.SS "Underlining with .ul"
.\" ====================================================================
.
There exists a
.I groff
request
.B .ul
(see above) that can underline the next or further source lines in
.BR nroff ,
but in
.B troff
it produces only a font change into
.IR italic .
.
So this request is not really useful.
.
.
.\" ====================================================================
.SS "Underlining with .UL from ms"
.\" ====================================================================
.
In the \[oq]ms\[cq] macro package in tmac/s.tmac
.BR groff_ms (@MAN7EXT@),
there is the macro
.BR .UL .
.
But this works only in
.BR troff ,
not in
.BR nroff .
.
.
.\" ====================================================================
.SS "Underlining macro definitions"
.\" ====================================================================
.
So one can use the
.I italic
.B nroff
idea from
.B .ul
and the
.B troff
definition
in
.I ms
for writing a useful new macro, something like
.
.RS
.EX
\&.de UNDERLINE
\&. ie n \[rs]\[rs]$1\[rs]f[I]\[rs]\[rs]$2\[rs]f[P]\[rs]\[rs]$3
\&. el \[rs]\[rs]$1\[rs]Z\[aq]\[rs]\[rs]$2\[aq]\[rs]v\[aq].25m\[aq]\
\[rs]D\[aq]l \[rs]w\[aq]\[rs]\[rs]$2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\
\[aq]\[rs]\[rs]$3
\&..
.EE
.RE
.
If
.BR doclifter (1)
makes trouble, change the macro name
.B UNDERLINE
into some 2-letter word, like
.BR Ul .
.
Moreover,
change the form of the font escape from
.B \[rs]f[P]
to
.BR \[rs]fP .
.
.
.\" ====================================================================
.SS "Underlining without macro definitions"
.\" ====================================================================
.
If one does not want to use macro definitions, e.g., when
.B doclifter
gets lost, use the following:
.
.RS
.EX
\&.ds u1 before
\&.ds u2 in
\&.ds u3 after
\&.ie n \[rs]*[u1]\[rs]f[I]\[rs]*[u2]\[rs]f[P]\[rs]*[u3]
\&.el \[rs]*[u1]\[rs]Z\[aq]\[rs]*[u2]\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\
\[aq]l \[rs]w\[aq]\[rs]*[u2]\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*\
[u3]
.EE
.RE
.
When using
.BR doclifter ,
it might be necessary to change syntax forms such as
.B \e[xy]
and
.B \e*[xy]
to those supported by AT&T
.IR troff :
.B \e*(xy
and
.BR \e(xy ,
and so on.
.
.
.P
Then these lines could look like
.RS
.EX
\&.ds u1 before
\&.ds u2 in
\&.ds u3 after
\&.ie n \[rs]*[u1]\[rs]fI\[rs]*(u2\[rs]fP\[rs]*(u3
\&.el \[rs]*(u1\[rs]Z\[aq]\[rs]*(u2\[aq]\[rs]v\[aq].25m\[aq]\[rs]D\
\[aq]l \[rs]w\[aq]\[rs]*(u2\[aq]u 0\[aq]\[rs]v\[aq]\-.25m\[aq]\[rs]*(u3
.EE
.RE
.
.
.P
The result looks like
.RS
.ft CR
before
\z\[ul]i\
\z\[ul]n
after
.ft R
.RE
.
.
.\" ====================================================================
.SS "Underlining with overstriking \ez and \e(ul"
.\" ====================================================================
.
There is another possibility for underlining by using overstriking
with
.BI \ez c
(print
.I c
with zero width without spacing) and
.B \e(ul
(underline character).
.
This produces the underlining of 1 character, both in
.B nroff
and in
.BR troff .
.
.
.P
For example the underlining of a character say
.B t
looks like
.B \ez\e[ul]t
or
.B \ez\e(ult
.
.
.P
Longer words look then a bit strange, but a useful mode is to write
each character into a whole own line.
.
To underlines the 3 character part "tar" of the word "start":
.
.RS
.EX
.br
before s\[rs]
\[rs]z\[rs][ul]t\[rs]
\[rs]z\[rs][ul]a\[rs]
\[rs]z\[rs][ul]r\[rs]
t after
.EE
.RE
.
or
.
.RS
.EX
.br
before s\[rs]
\[rs]z\[rs](ult\[rs]
\[rs]z\[rs](ula\[rs]
\[rs]z\[rs](ulr\[rs]
t after
.EE
.RE
.
.
.P
The result looks like
.RS
.ft CR
before s\
\z\[ul]t\
\z\[ul]a\
\z\[ul]r\
t after
.ft R
.RE
.
.
.\" ====================================================================
.SH Compatibility
.\" ====================================================================
.
The differences between the
.I roff
language recognized by GNU
.I troff \" GNU
and that of AT&T
.IR troff , \" AT&T
as well as the device,
font,
and device-independent intermediate output formats described by
CSTR\~#54 are documented in
.IR groff_diff (@MAN7EXT@).
.
.
.P
.I groff
provides an AT&T compatibility mode;
see
.IR groff (@MAN1EXT@).
.
.
.\" ====================================================================
.SH Debugging
.\" ====================================================================
.
.I groff
is not the easiest language to debug,
in part thanks to its design features of recursive interpolation and
multi-stage pipeline processing.
.
Nevertheless there exist several features useful for troubleshooting.
.
.
.P
Preprocessors use the
.B .lf
request to preserve the identity of the line numbers and names of input
files.
.
.I groff
emits a variety of error diagnostics and supports several categories of
warning;
the output of these can be selectively suppressed with
.B .warn
(and see the
.BR -E ,
.BR -w ,
and
.B -W
options of
.IR \%@g@troff (@MAN1EXT@)).
.
Backtraces can be automatically produced when errors or warnings occur
(the
.B \-b
option of
.IR \%@g@troff (@MAN1EXT@))
or generated on demand
.RB ( .backtrace ).
.
.BR .tm ,
.BR .tmc ,
and
.B .tm1
can be used to emit customized diagnostic messages or for
instrumentation while troubleshooting.
.
.B .ex
and
.B .ab
cause early termination with successful and error exit codes
respectively,
to halt further processing when continuing would be fruitless.
.
The state of the formatter can be examined with requests that write
lists of defined macros,
strings,
diversions,
and boxes
.RB ( .pm );
environments
.RB ( .pev ),
registers
.RB ( .pnr ),
and page location traps
.RB ( .ptr )
to the standard error stream.
.
.
.\" ====================================================================
.SH Authors
.\" ====================================================================
.
This document was written by
.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.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].
.
.
.P
\[lq]Troff User's Manual\[rq]
by Joseph F.\& Ossanna, 1976
(revised by Brian W.\& Kernighan, 1992),
AT&T Bell Laboratories Computing Science Techical Report No.\& 54,
widely called simply \[lq]CSTR\~#54\[rq],
documents the language,
device and font description file formats,
and device-independent output format
referred to collectively in
.I groff
documentation as
.RI \[lq]AT&T\~ troff \[rq].
.
.
.P
\[lq]A Typesetter-independent TROFF\[rq]
by Brian W.\& Kernighan, 1982,
AT&T Bell Laboratories Computing Science Techical Report No.\& 97
(CSTR\~#97),
provides additional insights into the
device and font description file formats
and device-independent output format.
.
.
.TP
.IR groff (@MAN1EXT@)
is the preferred interface to the
.I groff
system;
it manages the pipeline that carries a source document through
preprocessors,
the
.I \%@g@troff
formatter,
and an output driver to viewable or printable form.
.
It also exhaustively lists all of the man pages provided with the GNU
.I roff
system.
.
.
.TP
.IR groff_char (@MAN7EXT@)
discusses character encoding issues,
escape sequences that produce glyphs,
and enumerates
.IR groff 's
predefined special character escapes.
.
.
.TP
.IR groff_diff (@MAN7EXT@)
covers the differences between the
GNU
.I troff \" GNU
formatter,
its device and font description file format,
and its device-independent output format,
and those of AT&T
.IR troff ,\" AT&T
whose design it re-implements.
.
.
.TP
.IR groff_font (@MAN5EXT@)
describes the formats of the files that describe devices
.RI ( DESC )
and fonts.
.
.
.TP
.IR groff_tmac (@MAN5EXT@)
surveys macro packages provided with
.IR groff ,
describes how documents can take advantage of them,
offers guidance on writing macro packages and using diversions,
and includes historical information on macro package naming conventions.
.
.
.TP
.IR roff (@MAN7EXT@)
presents a detailed history of
.I roff
systems and summarizes concepts common to them.
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_7_man_C]
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72: