Table of Contents
groff -
a short reference for the GNU roff language
The name groff
stands for GNU roff and is the free implementation of the roff type-setting
system. See roff(7)
for a survey and the background of the groff system.
This document gives only short descriptions of the predefined roff language
elements as used in groff. Both the classical features and the groff extensions
are provided.
Historically, the roff language was called troff. groff is
compatible with the classical system and provides proper extensions. So
in GNU, the terms roff, troff, and groff language could be used as synonyms.
However troff slightly tends to refer more to the classical aspects, whereas
groff emphasizes the GNU extensions, and roff is the general term for the
language.
This file is only a short version of the complete documentation
that is found in the groff info(1)
file, which contains more detailed,
actual, and concise information.
The general syntax for writing groff documents
is relatively easy, but writing extensions to the roff language can be
a bit harder.
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 or a single quote all other
lines are text lines.
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,
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.
Text
lines represent the parts that is printed. They can be modified by escape
sequences, which are recognized by a leading backslash These are in-line
or even in-word formatting elements or functions. Some of these take arguments
separated by single quotes others are regulated by a length encoding
introduced by an open parenthesis or enclosed in brackets and
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 copy mode.
The copy mode behavior
can be quite tricky, but there are some rules that ensure a safe usage.
- 1.
- Printable backslashes must be denoted as [rs]e. To be more precise, [rs]e
represents the current escape character. To get a backslash glyph, use
[rs](rs or [rs][rs].
- 2.
- Double all backslashes.
- 3.
- Begin all text lines with
the special non-spacing character [rs]&.
This does not produce the most
efficient code, but it should work as a first measure. For better strategies,
see the groff info file and groff_tmac(5)
.
Reading roff source files is
easier, just reduce all double backslashes to a single one in all macro
definitions.
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.
There are
two kinds of roff commands, possibly with arguments. Requests are written
on a line of their own starting with a dot or a whereas Escape sequences
are in-line functions and in-word formatting elements starting with a backslash
The user can define her own formatting commands using the $* request.
These commands are called 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.
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.
String variables store
character sequences. They are set with the $* request and retrieved by
the [rs]* escape sequences. Strings can have variables.
Register variables
can store numerical values, numbers with a scale unit, and occasionally
string-like objects. They are set with the $* request and retrieved by
the [rs]n escape sequences.
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.
Fonts are identified either
by a name or by an internal number. The current font is chosen by the $*
request or by the [rs]f escape sequences. Each device has special fonts,
but the following fonts are available for all devices. R is the standard
font Roman. B is its bold counterpart. The italic font is called 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, CR, CI, and CB. On text devices, all glyphs have
a constant width anyway.
Glyphs are visual representation forms of 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
‘glyph’ or ‘character’, whatever is more appropriate.
Moreover, there are some
advanced roff elements. A diversion stores (formatted) information into
a macro for later usage. A 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.
More
detailed information and examples can be found in the groff info file.
There is a small set of characters that have a special
controlling task in certain conditions.
- CB].]
- A dot is only special at the
beginning of a line or after the condition in the requests $* $* $*
and $* There it is the control character that introduces a request (or
macro). The special behavior can be delayed by using the [rs]. escape.
By using the $* request, the control character can be set to a different
character, making the dot a non-special character.
- 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.
- CB]’]
- The single quote 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, the non-break control
character can be set to a different character.
- 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 the single quote or apostrophe character. Groff provides
a printable representation with the [rs](cq escape sequence.
- CB][dq]]
- The double quote is used to enclose arguments in macros (but not in requests
and strings). In the $* and $* requests, a leading double quote in the
argument is stripped off, making everything else afterwards the string
to be defined (enabling leading whitespace). The escaped double quote [rs][dq]
introduces a comment. Otherwise, it is not special. Groff provides a printable
representation with the [rs](dq escape sequence.
- CB][rs]]
- The backslash
usually introduces an escape sequence (this can be changed with the $*
request). A printed version of the escape character is the [rs]e escape;
a backslash glyph can be obtained by [rs](rs.
- CB](]
- The open parenthesis
is only special in escape sequences when introducing an escape name or
argument consisting of exactly two characters. In groff, this behavior
can be replaced by the CB][]] construct.
- CB][]
- 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.
- CB]]]
- 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.
- CI]space]
- Space characters are only functional characters.
They separate the arguments in requests, macros, and strings, and the
words in text lines. They are subject to groff’s horizontal spacing calculations.
To get a defined space width, escape sequences like (this is the escape
character followed by a space), [rs]|, [rs]^, or [rs]h should be used.
- CI]newline]
- In text paragraphs, newlines mostly behave like space characters.
Continuation lines can be specified by an escaped newline, i.e., by specifying
a backslash as the last character of a line.
- CI]tab]
- 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.
A numerical value is a signed or
unsigned integer or float with or without an appended scaling indicator.
A 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.
The roff language defines the following scaling indicators.
- c
- Centimeter
- i
- Inch
- P
- Pica [eq] 1/6 inch
- p
- Point [eq] 1/72 inch
- m
- Em [eq] R]the font
size in points (approx. width of letter ‘CR]mR]’)
- M
- 100th R]of an CR]Em
- n
- En [eq] Em/2
- u
- Basic unit for actual output device
- v
- Vertical line
space in basic units scaled point [eq] 1/CI]sizescaleR] of a point (defined
in font I]DESC] file)
- f
- Scale by 65536.
Numerical expressions are combinations
of the numerical values defined above with the following arithmetical operators
already defined in classical troff.
- +
- Addition
- -
- Subtraction
- *
- Multiplication
- /
- Division
- %
- Modulo
- =
- Equals
- ==
- Equals
- <
- Less than
- >
- Greater
than
- <=
- Less or equal
- >=
- Greater or equal
- &
- Logical and
- :
- Logical
or
- !
- Logical not
- (
- Grouping of expressions
- )
- Close current grouping
Moreover, groff added the following operators for numerical expressions:
- I]e1CB]>?I]e2R]
- The maximum of e1 and e2.
- I]e1CB]<?I]e2R]
- The minimum
of e1 and e2.
- CB](I]cCB];I]eCB])R]
- Evaluate e using c as the default scaling
indicator.
For details see the groff info file.
Conditions
occur in tests raised by the $* $* and the $* requests. The following
table characterizes the different types of conditions.
- N
- A numerical
expression N yields true if its value is greater than~0.
- !N
- True if the
value of I is~0.
- ’s1’s2’
- True if string~s1 is identical to string~s2.
- !’s1’s2’
- True if string~s1 is not identical to string~s2.
- cch
- True if there is
a glyph~ch available.
- dname
- True if there is a string, macro, diversion,
or request called name.
- e
- Current page number is even.
- o
- Current page
number is odd.
- mname
- True if there is a color called name.
- n
- Formatter
is nroff.
- rreg
- True if there is a register named reg.
- t
- Formatter is
troff.
- Ffont
- True if there exists a font named font.
- Sstyle
- True if a
style named style has been registered.
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.
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.
Some requests have optional arguments with
a different behaviour. Not all of these details are outlined here. Refer
to the groff info file and groff_diff(7)
for all details.
In the following
request specifications, most argument names were chosen to be descriptive.
Only the following denotations need clarification.
- c
- denotes a single
character.
- font
- a font either specified as a font name or a font number.
- anything
- all characters up to the end of the line or within [rs]{ and
[rs]}.
- n
- is a numerical expression that evaluates to an integer value.
- N
- is an arbitrary numerical expression, signed or unsigned.
- [+-]N
- has
three meanings depending on its sign, described below.
If an expression
defined as [+-]N starts with a 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 the
value of the expression is subtracted from the request value.
Without a
sign, N replaces the existing value directly. To assign a negative number
either prepend~0 or enclose the negative number in parentheses.
- }
- Empty line, ignored. Useful for structuring
documents.
- }
- Complete line is a comment.
- }
- Print string on
standard error, exit program.
- }
- Begin line adjustment for output
lines in current adjust mode.
- }
- Start line adjustment in mode c (CI]c]CR][eq]l,r,b,n]).
- }
- Assign format c to register (CI]c]CR][eq]l,i,I,a,A]).
- }
-
Create alias name for register.
- }
- Create alias name for request,
string, macro, or diversion object.
- }
- Append to macro until .. is encountered.
- }
- Append to macro until .end is called.
- }
- Same as $* but with
compatibility mode switched off during macro expansion.
- }
- Same as
$* but with compatibility mode switched off during macro expansion.
-
}
- Append to a macro whose name is contained in the string register
macro until .. is encountered.
- }
- Append to a macro indirectly. macro
and end are string registers whose contents are interpolated for the macro
name and the end macro, respectively.
- }
- Same as $* but with compatibility
mode switched off during macro expansion.
- }
- Same as $* but with
compatibility mode switched off during macro expansion.
- }
- Append
anything to stringvar.
- }
- Same as $* but with compatibility mode
switched off during string expansion.
- }
- Unformat ASCII characters,
spaces, and some escape sequences in diversion.
- }
- Print a backtrace
of the input on stderr.
- }
- Embolden font by N-1 units.
- }
- Embolden
Special Font S when current font is font.
- }
- Unset the blank line
macro.
- }
- Set the blank line macro to macro.
- }
- End current diversion.
- }
- Divert to macro, omitting a partially filled line.
- }
- End
current diversion.
- }
- Divert and append to macro, omitting a partially
filled line.
- }
- Eject current page and begin new page.
- }
- Eject
current page; next page number [+-]N.
- }
- Line break.
- }
- Break
and spread output line. Same as [rs]p.
- }
- Break out of a while loop.
- }
- Reset no-break control character to
- }
- Set no-break control
character to c.
- }
- Reset control character to
- }
- Set control
character to c.
- }
- Center the next input line.
- }
- Center following
N input lines.
- }
- Copy contents of file filename unprocessed to stdout
or to the diversion.
- }
- Treat characters c1, c2, ... according to mode
number.
- }
- Change trap location to N.
- }
- Define entity c as string
anything.
- }
- Chop the last character off macro, string, or diversion
object.
- }
- Close the stream.
- }
- Enable colors.
- }
- If N is
zero disable colors, otherwise enable them.
- }
- Map glyph name from
to glyph name to while constructing a composite glyph name.
- }
- Finish
the current iteration of a while loop.
- }
- Enable compatibility mode.
- }
- If N is zero disable compatibility mode, otherwise enable it.
- }
- Set constant character width mode for font to N/36 ems with em
M.
- }
- Continuous underline in nroff, like $* in troff.
- }
- End
current diversion.
- }
- Divert and append to macro.
- }
- Define or
redefine macro until .. is encountered.
- }
- Define or redefine macro
until .end is called.
- }
- Same as $* but with compatibility mode switched
off during macro expansion.
- }
- Same as $* but with compatibility
mode switched off during macro expansion.
- }
- Define or redefine a
color with name color. scheme can be rgb, cym, cymk, gray, or grey. component
can be single components specified as fractions in the range 0 to 1 (default
scaling indicator~ as a string of two-digit hexadecimal color components
with a leading #, or as a string of four-digit hexadecimal components with
two leading #. The color default can’t be redefined.
- }
- Define or redefine
a macro whose name is contained in the string register macro until .. is
encountered.
- }
- Define or redefine a macro indirectly. macro and end
are string registers whose contents are interpolated for the macro name
and the end macro, respectively.
- }
- Same as $* but with compatibility
mode switched off during macro expansion.
- }
- Same as $* but with
compatibility mode switched off during macro expansion.
- }
- Write anything
to the intermediate output as a device control function.
- }
- Write
contents of macro or string name uninterpreted to the intermediate output
as a device control function.
- }
- End current diversion.
- }
- Divert
to macro.
- }
- Interpret .name with compatibility mode disabled.
-
}
- Set stringvar to anything.
- }
- Same as $* but with compatibility
mode switched off during string expansion.
- }
- Set diversion trap to
position N (default scaling indicator~
- }
- Reset escape character
to
- }
- Set escape character to c.
- }
- Restore escape character
saved with $*
- }
- Save current escape character.
- }
- Else part
for if-else ($* request.
- }
- The macro is run after the end of input.
- }
- Turn off escape character mechanism.
- }
- Switch to previous
environment and pop it off the stack.
- }
- Push down environment number
or name env to the stack and switch to it.
- }
- Copy the contents of
environment env to the current environment. No pushing or popping.
-
}
- Exit from roff processing.
- }
- Return to previous font family.
-
}
- Set the current font family to name.
- }
- Disable field mechanism.
- }
- Set field delimiter to~a and pad glyph to space.
- }
- Set field
delimiter to~a and pad glyph to~b.
- }
- Define fallback character (or
glyph) c as string anything.
- }
- Set fill color to previous fill color.
- }
- Set fill color to c.
- }
- Fill output lines.
- }
- Flush
output buffer.
- }
- Mount font on position n.
- }
- Mount font with
long external name to short internal name on position n.
- }
- Define
fallback character (or glyph) c for font f as string anything.
- }
-
Reset list of special fonts for font to be empty.
- }
- When the current
font is font, then the fonts s1, s2, ... are special.
- }
- Return to previous
font. Same as $* or $*
- }
- Change to font name or number font; same
as escape sequence.
- }
- Translate font1 to font2.
- }
- Don’t magnify
font.
- }
- Set zoom factor for font (in multiples of 1/1000th).
-
}
- Set glyph color to previous glyph color.
- }
- Set glyph color to
c.
- }
- Remove additional hyphenation indicator character.
- }
- Set
up additional hyphenation indicator character~c.
- }
- Set the hyphenation
code of character c1 to code1, that of c2 to code2, etc.
- }
- Set the
current hyphenation language to lang.
- }
- Set the maximum number of
consecutive hyphenated lines to n.
- }
- Read hyphenation patterns from
file.
- }
- Append hyphenation patterns from file.
- }
- Set input
mapping for $*
- }
- List of words with exceptional hyphenation.
-
}
- Switch to hyphenation mode N.
- }
- Set the hyphenation margin
to n (default scaling indicator~
- }
- Set the hyphenation space to
n.
- }
- If cond then anything else goto $*
- }
- If cond then anything;
otherwise do nothing.
- }
- Ignore text until .. is encountered.
- }
- Ignore text until .end is called.
- }
- Change to previous indentation
value.
- }
- Change indentation according to [+-]N (default scaling indicator~
- }
- Set an input-line count trap for the next N lines.
- }
- Same
as $* but count lines interrupted with [rs]c as one line.
- }
- Enable
pairwise kerning.
- }
- If n is zero, disable pairwise kerning, otherwise
enable it.
- }
- Remove leader repetition glyph.
- }
- Set leader repetition
glyph to~c.
- }
- Write the length of the string anything to register.
- }
- Enable line-tabs mode (i.e., calculate tab positions relative to
output line).
- }
- If n is zero, disable line-tabs mode, otherwise enable
it.
- }
- Set input line number to N.
- }
- Set input line number to
N and filename to file.
- }
- Ligature mode on if N>0.
- }
- Change
to previous line length.
- }
- Set line length according to [+-]N (default
length default scaling indicator~
- }
- Change to the previous
value of additional intra-line skip.
- }
- Set additional intra-line skip
value to N, i.e., N-1 blank lines are inserted after each text output line.
- }
- Length of title (default scaling indicator~
- }
- Margin
glyph off.
- }
- Print glyph~c after each text line at actual distance
from right margin.
- }
- Set margin glyph to~c and distance to~N from
right margin (default scaling indicator~
- }
- Mark current vertical
position in register.
- }
- The same as $* except that file is searched
in the tmac directories.
- }
- No output-line adjusting.
- }
- Need
a one-line vertical space.
- }
- Need N vertical space (default scaling
indicator~
- }
- No filling or adjusting of output-lines.
- }
- No
hyphenation.
- }
- Number mode off.
- }
- In line number mode, set
number, multiple, spacing, and indentation.
- }
- Do not number next
line.
- }
- Do not number next N lines.
- }
- Always process anything.
- }
- Define or modify register using [+-]N with auto-increment M.
-
}
- Make the built-in conditions n true and t false.
- }
- Turn on no-space
mode.
- }
- Immediately jump to end of current file.
- }
- Immediately
continue processing with file file.
- }
- Open filename for writing and
associate the stream named stream with it.
- }
- Like $* but append
to it.
- }
- Output vertical distance that was saved by the $* request.
- }
- Emit string directly to intermediate output, allowing leading
whitespace if string starts with CB][dq]] (which is stripped off).
-
}
- Reset page number character to~
- }
- Page number character.
-
}
- Print the current environment and each defined environment state
to stderr.
- }
- Pipe output to program (nroff only).
- }
- Set page
length to default The current page length is stored in $*
- }
- Change page length to [+-]N (default scaling indicator~
- }
- Print
macro names and sizes (number of blocks of 128 bytes).
- }
- Print only
total of sizes of macros (number of 128 bytes blocks).
- }
- Next page
number N.
- }
- Print the names and contents of all currently defined
number registers on stderr.
- }
- Change to previous page offset. The
current page offset is available in $*
- }
- Page offset N.
-
}
- Return to previous point size.
- }
- Point size; same as
- }
- Get the bounding box of a PostScript image filename.
- }
- This behaves
like the $* request except that input comes from the standard output of
command.
- }
- Print the names and positions of all traps (not including
input line traps and diversion traps) on stderr.
- }
- Change to previous
post-vertical line spacing.
- }
- Change post-vertical line spacing according
to [+-]N (default scaling indicator~
- }
- Remove the definitions of
entities c1, c2, ...
- }
- Read insertion.
- }
- Return from a macro.
- }
- Return twice, namely from the macro at the current level and from
the macro one level higher.
- }
- Remove the definitions of entities
c1, c2, ... for font f.
- }
- Right justify the next n input lines.
-
}
- Remove request, macro, or string name.
- }
- Rename request, macro,
or string old to new.
- }
- Rename register reg1 to reg2.
- }
- Remove
register.
- }
- Restore spacing; turn no-space mode off.
- }
- Return
(upward only) to marked vertical place (default scaling indicator~
-
}
- Define global fallback character (or glyph)~c as string anything.
- }
- Reset soft hyphen glyph to [rs](hy.
- }
- Set the soft hyphen
glyph to~c.
- }
- In a macro, shift the arguments by n~positions.
-
}
- Set available font sizes similar to the sizes command in a DESC file.
- }
- Include source file.
- }
- Skip one line vertically.
- }
- Space vertical distance N up or down according to sign of N (default scaling
indicator~
- }
- Reset global list of special fonts to be empty.
-
}
- Fonts s1, s2, etc. are special and are searched for glyphs not in
the current font.
- }
- Toggle the spread warning on and off without
changing its value.
- }
- Emit a warning if each space in an output line
is widened by limit or more (default scaling indicator~
- }
- Set
space glyph size to N/12 of the space width in the current font.
- }
- Set space glyph size to N/12 and sentence space size set to M/12 of the
space width in the current font.
- }
- Associate style with font position
n.
- }
- Replace the string named xx with the substring defined by the
indices n1 and n2.
- }
- Save of vertical space.
- }
- Save the vertical
distance N for later output with $* request (default scaling indicator~
- }
- Execute program command-line.
- }
- Set tabs after every position
that is a multiple of N (default scaling indicator~
- }
- Set tabs
at positions n1, n2, nn, then set tabs at nn+r1, nn+r2, nn+rn, then
at nn+rn+r1, nn+rn+r2, nn+rn+rn, and so on.
- }
- Remove tab
repetition glyph.
- }
- Set tab repetition glyph to~c.
- }
- Temporary
indent next line (default scaling indicator~
- }
- Enable track kerning
for font.
- }
- Three-part title.
- }
- Print anything on stdout.
-
}
- Print anything on stdout, allowing leading whitespace if anything
starts with CB][dq]] (which is stripped off).
- }
- Similar to $* without
emitting a final newline.
- }
- Translate a to b, c to d, etc. on output.
- }
- Transparently output the contents of file filename.
- }
- This
is the same as the $* request except that the asciify request uses the
character code (if any) before the character translation.
- }
- This
is the same as the $* request except that the translations do not apply
to text that is transparently throughput into a diversion with [rs]!.
- }
- Make the built-in conditions t true and n false.
- }
- Set underline
font to font (to be switched to by $*
- }
- Underline (italicize in
troff) N input lines.
- }
- Unformat space characters and tabs in diversion,
preserving font information.
- }
- Enable vertical position traps if n
is non-zero, disable them otherwise.
- }
- Change to previous vertical
base line spacing.
- }
- Set vertical base line spacing to [+-]N (default
scaling indicator~
- }
- Set warnings code to n.
- }
- Set scaling
indicator used in warnings to si.
- }
- Remove (first) trap at position
N.
- }
- Set location trap; negative means from page bottom.
- }
-
While condition cond is true, accept anything as input.
- }
- Write anything
to the stream named stream.
- }
- Similar to $* without emitting a final
newline.
- }
- Write contents of macro or string xx to the stream named
stream.
Besides these standard groff requests, there might be further
macro calls. They can originate from a macro package (see roff(7)
for an
overview) or from a preprocessor.
Preprocessor macros are easy to be recognized.
They enclose their code into a pair of characteristic macros.
preprocessor | start
macro | end macro |
eqn | .EQ | .EN |
grap | .G1 | .G2 |
grn | .GS | .GE |
pic | .PS | .PE |
refer | .R1 | .R2 |
soelim | I]none | I]none |
tbl | .TS | .TE |
Escape sequences are in-line language elements usually
introduced by a backslash and followed by an escape name and sometimes
by a required argument. Input processing is continued directly after the
escaped character or the argument (without an intervening separation character).
So there must be a way to determine the end of the escape name and the
end of the argument.
This is done by enclosing names (escape name and arguments
consisting of a variable name) by a pair of brackets [lB]name[rB] and constant
arguments (number expressions and characters) by apostrophes (ASCII 0x27)
like [cq]constant[cq]R].
There are abbreviations for short names. Two-character
escape names can be specified by an opening parenthesis like [rs](xy or
[rs]*(xy without a closing counterpart. And all one-character names different
from the special characters and can even be specified without a marker,
for example [rs]nc or [rs]$c.
Constant arguments of length~1 can omit
the marker apostrophes, too, but there is no two-character analogue.
While
one-character escape sequences are mainly used for in-line functions and
system related tasks, the two-letter names following the [rs]( construct
are glyphs predefined by the roff system; these are called ‘Special Characters’
in the classical documentation. Escapes sequences of the form denote
glyphs too.
- Start of a comment.
- Everything
up to the end of the line is ignored.
- Everything up to and including
the next newline is ignored.
- This is interpreted in copy mode. This is
like [rs][dq] except that the terminating newline is ignored as well.
- The string stored in the string variable with one-character name~s.
-
- The string stored in the string variable with two-character name
- st.
- The string stored in the string variable with name
- string (with arbitrary
length).
- The string stored in the string variable with arbitrarily long
name
- stringvar, taking arg1, arg2, ... as arguments.
- The name by which
the current macro was invoked.
- The $* request can make a macro have more
than one name.
- Macro or string argument with one-digit number~x
- in the
range 1 to~9.
- Macro or string argument with two-digit number
- xy (larger
than zero).
- Macro or string argument with number
- nexp, where nexp is
a numerical expression evaluating to an integer [>=]1.
- In a macro or
string, the concatenation of all the arguments separated
- by spaces.
-
In a macro or string, the concatenation of all the arguments with each
- surrounded by double quotes, and separated by spaces.
- In a macro, the
representation of all parameters as if they were an
- argument to the $*
request.
- reduces to a single backslash; useful to delay its interpretation
as
- escape character in copy mode. For a printable backslash, use [rs]e,
or even better [rs][rs], to be independent from the current escape character.
- The acute accent [aa]; same as
- [rs](aa. Unescaped: apostrophe, right
quotation mark, single quote (ASCII 0x27).
- The grave accent [ga]; same
as
- [rs](ga. Unescaped: left quote, backquote (ASCII 0x60).
- The - (minus)
sign in the current font.
-
- The same as
- [rs](ul, the underline character.
- An uninterpreted dot (period), even at start of line.
-
- Default optional
hyphenation character.
-
- Transparent line indicator.
-
- In a diversion,
this transparently embeds
- anything in the diversion. anything is read in
copy mode. See also the escape sequences [rs]! and [rs]?.
- Unpaddable
space size space glyph (no line break).
-
- Digit-width space.
-
- 1/6 em narrow
space glyph; zero width in nroff.
-
- 1/12 em half-narrow space glyph; zero
width in nroff.
-
- Non-printable, zero-width glyph.
-
- Like
- [rs]& except
that it behaves like a glyph declared with the $* request to be transparent
for the purposes of end-of-sentence recognition.
- 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.
- 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.
- Unbreakable space that stretches like a normal inter-word space when
a
- line is adjusted.
- Inserts a zero-width break point (similar to
- [rs]%
but without a soft hyphen character).
- Ignored newline, for continuation
lines.
-
- Begin conditional input.
-
- End conditional input.
-
- A glyph
with two-character name
- sc; see section Special Characters.
- A glyph with
name
- name (of arbitrary length).
- A composite glyph with components
- comp1,
comp2, ...
- Non-interpreted leader character.
-
- If
- anything is acceptable
as a name of a string, macro, diversion, register, environment or font
it expands to~1, and to~0 otherwise.
- Bracket building function.
-
- If
- anything is acceptable as a valid numeric expression it expands to~1, and
to~0 otherwise.
- Interrupt text processing.
-
- The glyph called
- glyph;
same as but compatible to other roff versions.
- Forward (down) 1/2
em (1/2 line in nroff).
-
- Draw a graphical element defined by the characters
in
- charseq; see the groff info file for details.
- Printable version of
the current escape character.
-
- Equivalent to an escape character, but
is not interpreted in copy mode.
-
- Change to font with one-character name
or one-digit number~F.
-
- Switch back to previous font.
-
- Change to font
with two-character name or two-digit number
- fo.
- Change to font with arbitrarily
long name or number expression
- font.
- Switch back to previous font.
-
-
Change to font family with one-character name~f.
-
- Change to font family
with two-character name
- fm.
- Change to font family with arbitrarily long
name
- fam.
- Switch back to previous font family.
-
- Return format of register
with one-character name~r
- suitable for $* request.
- Return format of
register with two-character name
- rg suitable for $* request.
- Return
format of register with arbitrarily long name
- reg suitable for $* request.
- Local horizontal motion; move right
- N (left if negative).
- Set height
of current font to
- N.
- Mark horizontal input place in one-character register~r.
-
- Mark horizontal input place in two-character register
- rg.
- Mark horizontal
input place in register with arbitrarily long name
- reg.
- Horizontal line
drawing function (optionally using character
- c).
- Vertical line drawing
function (optionally using character
- c).
- Change to color with one-character
name~c.
-
- Change to color with two-character name
- cl.
- Change to color
with arbitrarily long name
- color.
- Switch back to previous color.
-
-
Change filling color for closed drawn objects to color with
- one-character
name~c.
- Change filling color for closed drawn objects to color with
- two-character name cl.
- Change filling color for closed drawn objects
to color with
- arbitrarily long name color.
- Switch to previous fill color.
-
- The numerical value stored in the register variable with the
- one-character
name~r.
- The numerical value stored in the register variable with the
- two-character name re.
- The numerical value stored in the register variable
with arbitrarily
- long name reg.
- Typeset the glyph with index~n
- in the
current font. No special fonts are searched. Useful for adding (named)
entities to a document using the $* request and friends.
- Overstrike
glyphs
- a, b, c, etc.
- Disable glyph output.
- Mainly for internal use.
- Enable glyph output.
- Mainly for internal use.
- Break and spread output
line.
-
- Reverse 1 em vertical motion (reverse line in nroff).
-
- The same
as
- $* name [+-]n.
- Set/increase/decrease the point size to/by
- N scaled
points; N is a one-digit number in the range 1 to~9. Same as $* request.
- Set/increase/decrease the point size to/by
- N scaled points; N is
a two-digit number [>=]1. Same as $* request.
- Set/increase/decrease
the point size to/by
- N scaled points. Same as $* request.
- Slant output
by
- N degrees.
- Non-interpreted horizontal tab.
-
- Reverse (up) 1/2 em
vertical motion (1/2 line in nroff).
-
- Local vertical motion; move down
- N (up if negative).
- The contents of the environment variable with one-character
- name~e.
- The contents of the environment variable with two-character name
- ev.
- The contents of the environment variable with arbitrarily long name
- env.
- The width of the glyph sequence
- string.
- Extra line-space function
(negative before, positive after).
-
- Output
- string as device control function.
- Output string variable or macro with one-character name~n
- uninterpreted
as device control function.
- Output string variable or macro with two-character
name
- nm uninterpreted as device control function.
- Output string variable
or macro with arbitrarily long name
- name uninterpreted as device control
function.
- Print
- c with zero width (without spacing).
- Print
- anything
and then restore the horizontal and vertical position; anything may not
contain tabs or leaders.
The escape sequences [rs]e, [rs]., [rs][dq],
[rs]$, [rs]*, [rs]a, [rs]n, [rs]t, [rs]g, and are interpreted
in copy mode.
Escape sequences starting with [rs]( or [rs][ do not represent
single character escape sequences, but introduce escape names with two
or more characters.
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.
[Note: ‘Special
Characters’ is a misnomer; those entities are (output) glyphs, not (input)
characters.]
Common special characters are predefined by escape sequences
of the form [rs](xy with characters x and y. Some of these exist in the
usual font while most of them are only available in the special font. Below
you can find a selection of the most important glyphs; a complete list
can be found in groff_char(7)
.
- Bullet sign
- Copyright
- Cent
-
Double dagger
- Degree
- Dagger
- Printable double quote
- Em-dash
-
Hyphen
- Registered sign
- Printable backslash character
- Section
sign
- Underline character
- Identical
- Larger or equal
- Less or
equal
- Not equal
- Right arrow
- Left arrow
- Plus-minus sign
-
Strings are defined by the $* request and can be retrieved by the [rs]*
escape sequence.
Strings share their name space with macros. So strings
and macros without arguments are roughly equivalent; it is possible to
call a string like a macro and vice-versa, but this often leads to unpredictable
results. The following string is the only one predefined in groff.
-
The name of the current output device as specified by the
- command line
option.
Registers are variables that store a value. In groff,
most registers store numerical values (see section NUMERICAL EXPRESSIONS
above), but some can also hold a string value.
Each register is given a
name. Arbitrary registers can be defined and set with the $* request.
The
value stored in a register can be retrieved by the escape sequences introduced
by [rs]n.
Most useful are predefined registers. In the following the notation
name is used to refer to $* to make clear that we speak about registers.
Please keep in mind that the decoration is not part of the register
name.
The following registers have predefined values
that should not be modified by the user (usually, registers starting with
a dot a read-only). Mostly, they provide information on the current settings
or store results from request calls.
- Number of arguments in the current
macro or string.
-
- Post-line extra line-space most recently utilized using
- [rs]x.
- Set to~1 in
- troff if option is used; always~1 in nroff.
- Within a macro, set to~1 if macro called with the ‘normal’ control
- character,
and to~0 otherwise.
- Current input line number.
-
- 1~if compatibility
mode is in effect, 0~otherwise.
-
- The depth of the last glyph added to
the current environment.
- It is positive if the glyph extends below the
baseline.
- The number of lines remaining to be centered, as set by the
- $* request.
- The height of the last glyph added to the current environment.
- It is positive if the glyph extends above the baseline.
- 1~if colors
are enabled, 0~otherwise.
-
- 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.
-
Current vertical place in current diversion; equal to
- $*
- The
name or number of the current environment (string-valued).
-
- Current font
number.
-
- The current font family (string-valued).
-
- The current (internal)
real font name (string-valued).
-
- The number of the next free font position.
-
- Always 1 in GNU troff.
- Macros should use it to test if running under
groff.
- Text base-line high-water mark on current page or diversion.
-
-
Available horizontal resolution in basic units.
-
- The current font
height as set with
- $*
- The current hyphenation language as set by
the
- $* request.
- The number of immediately preceding consecutive hyphenated
lines.
-
- The maximum allowed number of consecutive hyphenated lines,
as set by
- the $* request.
- The current hyphenation flags (as set by
the
- $* request).
- The current hyphenation margin (as set by the
- $*
request).
- The current hyphenation space (as set by the
- $* request).
- Current indentation.
-
- The indentation that applies to the current
output line.
-
- Positive if last output line contains
- [rs]c.
- 1~if
pairwise kerning is enabled, 0~otherwise.
-
- Current line length.
-
-
The current ligature mode (as set by the
- $* request).
- The current
line-tabs mode (as set by the
- $* request).
- The line length that applies
to the current output line.
-
- The title length (as set by the
- $* request).
- The current drawing color (string-valued).
-
- The current background
color (string-valued).
-
- Length of text portion on previous output line.
-
- The amount of space that was needed in the last
- $* request that caused
a trap to be sprung. Useful in conjunction with $*
- 1~if in no-space
mode, 0~otherwise.
-
- Current page offset.
-
- Current page length.
-
-
1~during page ejection, 0~otherwise.
-
- The number of the next page:
either the value set by a
- $* request, or the number of the current page
plus 1.
- The current point size in scaled points.
-
- The last-requested
point size in scaled points.
-
- The current post-vertical line spacing.
-
- The number of lines to be right-justified as set by the
- $* request.
- Current point size as a decimal fraction.
-
- The slant of the current
font as set with
- $*
- The last requested point size in points as a
decimal fraction
- (string-valued).
- The value of the parameters set by
the first argument of the
- $* request.
- The value of the parameters
set by the second argument of the
- $* request.
- The current font style
(string-valued).
-
- Vertical distance to the next trap.
-
- Set to~1
- if
option is used.
- A string representation of the current tab settings
suitable for use
- as an argument to the $* request.
- The amount of vertical
space truncated by the most recently sprung
- vertical position trap, or,
if the trap was sprung by a $* request, minus the amount of vertical motion
produced by $* Useful in conjunction with the $*
- Equal to 1 in
fill mode and 0 in no-fill mode.
-
- Equal to 1 in safer mode and 0 in unsafe
mode.
-
- Current vertical line spacing.
-
- Available vertical resolution
in basic units.
-
- 1~if vertical position traps are enabled, 0~otherwise.
-
- Width of previous glyph.
-
- The sum of the number codes of the currently
enabled warnings.
-
- The major version number.
-
- The minor version number.
-
- The revision number of groff.
-
- Name of current diversion.
-
- Zoom
factor for current font (in multiples of 1/1000th; zero if no
- magnification).
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.
- Current page number.
-
- Current input
line number.
-
- Character type (set by width function
- [rs]w).
- Maximal
width of last completed diversion.
-
- Height of last completed diversion.
-
- Current day of week (1-7).
-
- Current day of month (1-31).
-
- The
number of hours past midnight.
- Initialized at start-up.
- Current horizontal
position at input line.
-
- Lower left x-coordinate (in PostScript units)
of a given PostScript
- image (set by $*
- Lower left y-coordinate (in
PostScript units) of a given PostScript
- image (set by $*
- Output line
number.
-
- The number of minutes after the hour.
- Initialized at start-up.
- Current month (1-12).
-
- Vertical position of last printed text base-line.
-
- Like
- $* but takes account of the heights and depths of glyphs.
- Like
- $* but takes account of the heights and depths of glyphs.
-
Depth of string below base line (generated by width function
- [rs]w).
- The number of seconds after the minute.
- Initialized at start-up.
-
Right skip width from the center of the last glyph in the
- [rs]w argument.
- 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.
- The amount of horizontal space (possibly negative) that
should be
- added to the last glyph before a subscript (generated by width
function [rs]w).
- Height of string above base line (generated by width
function
- [rs]w).
- The return value of the
- system() function executed
by the last $* request.
- Upper right x-coordinate (in PostScript units)
of a given PostScript
- image (set by $*
- Upper right y-coordinate (in
PostScript units) of a given PostScript
- image (set by $*
- The current
year (year 2000 compliant).
-
- Current year minus 1900.
- For Y2K compliance
use $* instead.
The differences of the groff language
in comparison to classical troff as defined by [CSTR~#54] are documented
in groff_diff(7)
.
The groff system provides a compatibility mode, see groff(1)
on how to invoke this.
Report bugs to the groff bug mailing list
Include a complete, self-contained example that will allow the bug to be
reproduced, and say which version of groff you are using.
Copyright
(C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
Foundation, Inc.
This document is distributed under the terms of the FDL
(GNU Free Documentation License) version 1.3 or later. You should have received
a copy of the FDL on your system, it is also available on-line at the GNU
copyleft site
This document is part of groff, the GNU roff distribution.
It was written by Bernd Warken it is maintained by Werner Lemberg
The main source of information for the groff language is the
groff info(1)
file. Besides the gory details, it contains many examples.
- groff(1)
- the usage of the groff program and pointers to the documentation
and availability of the groff system.
- groff_diff(7)
- the differences of
the groff language as compared to classical roff. This is the authoritative
document for the predefined language elements that are specific to groff.
- groff_char(7)
- the predefined groff special characters (glyphs).
- groff_font(5)
- the specification of fonts and the DESC file.
- roff(7)
- the history of roff,
the common parts shared by all roff systems, and pointers to further documentation.
- [CSTR~#54]
- Nroff/:Troff User’s Manual by Ossanna & Kernighan [em] the
bible for classical troff.
Table of Contents