groff77 - Cheap VPS LLC

GROFF


Section: Environments, Tables, and Troff Macros (7)
Updated: 29 June 2002
Index
Return to Main Contents

 

NAME

groff – a short reference for the GNU roff language

 

DESCRIPTION

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

Text

"
"

or a single quote

Text

"
"

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 blanks 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 will be printed.
They can be modified by escape sequences, which are recognized by a
leading backslash

Text

"
"

These are in-line or even in-word formatting elements or functions.
Some of these take arguments separated by single quotes

Text

"
"

others are regulated by a length encoding introduced by an open
parenthesis

Text

"
"

or enclosed in brackets

Text

"
"

and

Text

"
"

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

e.

To be more precise,

e

represents the current escape character.
To get a backslash glyph, use

(rs

or

[rs].

2.

Double all backslashes.
3.

Begin all text lines with the special non-spacing character

&.


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.

 

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.

There are two kinds of roff commands, possibly with arguments.
Requests

are written on a line of their own starting with a dot

Text

"
"

or a

Text

"
"

whereas
Escape sequences

are in-line functions and in-word formatting elements starting with a
backslash

Text

"
"

The user can define her own formatting commands using the

de

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

ds

request and retrieved by the

*

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

nr

request and retrieved by the

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

ev

request.

Fonts

are identified either by a name or by an internal number.
The current font is chosen by the

ft

request or by the

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 characters have a constant width anyway.

Moreover, there are some advanced roff elements.
A
diversion

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

 

CONTROL CHARACTERS

There is a small set of characters that have a special controlling
task in certain conditions.


Text

"
"


A dot is only special at the beginning of a line or after the
condition in the requests

if ,

ie ,

el ,

and

while .

There it is the control character that introduces a request (or macro).
The special behavior can be delayed by using the

.

escape.
By using the

cc

request, the control character can be set to a different character,
making the dot

Text

"
"

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.

Text

"
"


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

c2

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 will work).
In all other positions, it denotes the single quote or apostrophe
character.
Groff provides a printable representation with the

(cq

escape sequence.

Text

"
"


The double quote is used to enclose arguments in requests, macros, and
strings.
In the

ds

and

as

requests, a leading double quote in the argument will be stripped off,
making everything else afterwards the string to be defined (enabling
leading whitespace).
The escaped double quote

"

introduces a comment.
Otherwise, it is not special.
Groff provides a printable representation with the

(dq

escape sequence.

Text

"
"


The backslash usually introduces an escape sequence (this can be
changed with the

ec

request).
A printed version of the escape character is the

e

escape; a backslash glyph can be obtained by

(rs.

Text

"
"


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 [] construct.

Text

"
"


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.

Text

"
"


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

Text

"
"

(this is the escape character followed by a space),

|,

^,

or

h

should be used.

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

Text

"
"

as the last character of a line.

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.


 

NUMERICAL EXPRESSIONS

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 = 1/6 inch

p

Point = 1/72 inch

m

Em = the font size in points (width of letter `m’)

M

100th of an Em

n

En = Em/2

u

Basic unit for actual output device

v

Vertical line space in basic units
scaled point = 1/sizescale of a point (defined in
font 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:


Text

"
"

The maximum of
e1

and
e2.

Text

"
"

The minimum of
e1

and
e2.

Text

"
"

Evaluate
e

using
c

as the default scaling indicator.


For details see the groff info file.

 

CONDITIONS

Conditions

occur in tests raised by the

if ,

ie ,

and the

while

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.

s1s2

True if string~s1

is identical to string~s2.

!’s1s2

True if string~s1

is not identical to string~s2.

cch

True if there is a character~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.


 

REQUESTS

This section provides a short reference for the predefined requests.
In groff, request and macro 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.
An argument can be enclosed by a pair of double quotes.
This is very handy if an argument contains space characters, e.g.,
"arg with space"

denotes a single argument.

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

{

and

}.

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

Text

"
"

sign the resulting value of the expression will be added to an already
existing value inherent to the related request, e.g. adding to a number
register.
If the expression starts with a

Text

"
"

the value of the expression will be 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.

 

Request Short Reference


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

(c=l,r,b,n).

Assign format
c

to
register

(c=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.

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

.am

but with compatibility mode switched off during macro expansion.

Same as

.am

but with compatibility mode switched off during macro expansion.

Append
anything

to
stringvar.

Unformat ASCII characters, spaces, and some escape sequences in
diversion.

Same as

.as

but with compatibility mode switched off during string expansion.

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

p.

Break out of a while loop.

Reset no-break control character to

Text

"
"

Set no-break control character to
c.

Reset control character to

Text

"
"

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

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

.ul

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

.de

but with compatibility mode switched off during macro expansion.

Same as

.de

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.

End current diversion.

Divert to
macro .

Interpret

.name

with compatibility mode disabled.

Set
stringvar

to
anything.

Same as

.ds

but with compatibility mode switched off during string expansion.

Set diversion trap to position
N

(default scaling indicator~

Reset escape character to

Text

"
"

Set escape character to
c.

Restore escape character saved with

.ecs .

Save current escape character.

Else part for if-else (
ie )

request.

The
macro

will be run after the end of input.

Turn off escape character mechanism.

Switch to previous environment.

Push down environment number or name
env

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 character to space.

Set field delimiter to
a

and pad character to
b.

Define fallback character
c

as string
anything.

Fill output lines.

Flush output buffer.

Mount
font

on position
n.

Mount font with long
external

name to short
internal

name on position
n.

When the current font is
font,

then the fonts
s1,

s2,

will be special.

Return to previous font.
Same as

f[]

or

fP .

Change to font name or number
font;

same as

escape sequence.

Translate
font1

to
font2.

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

.hpf .

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

.el .

If
cond

then
anything;

otherwise do nothing.

Ignore text until
..

is encountered.

Ignore text until

.end .

Change to previous indent value.

Change indent according to
±N

(default scaling indicator~

Set an input-line count trap for the next
N

lines.

Same as

.it

but count lines interrupted with

c

as one line.

Enable pairwise kerning.

If
n

is zero, disable pairwise kerning, otherwise enable it.

Remove leader repetition character.

Set leader repetition character to~c.

Write the length of the string
anything

in
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

and filename to
file.

Ligature mode on if
N>0.

Change to previous line length.

Set line length according to
±N

(default size

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 character off.

Print character
c

after each text line at actual distance from right margin.

Set margin character to
c

and distance to
N

from right margin (default scaling indicator~

Mark current vertical position in
register.

The same as the .so request 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 indent.

Do not number next line.

Do not number next
N

lines.

Always execute
anything.

Define or modify
register

using
±N

with auto-increment
M.

Make the built-in condition
n

true and
t

false.

Turn no-space mode on.

Immediately jump to end of current file.

Next file.

Open

filename

for writing and associate the stream named

stream

with it.

Like

.open

but append to it.

Output vertical distance that was saved by the

sv

request.

Emit
string

directly to intermediate output, allowing leading whitespace if
string

starts with

Text

"
"

(which will be stripped off).

Reset page number character to~

Text

"
"

Page number character.

Pipe output to
program

(nroff only).

Set page length to default

The current page length is stored in

.p .

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

.o .

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

so

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 characters
c1,

c2,

Read insertion.

Return from a macro.

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~

Reset soft hyphen character to

(hy.

Set the soft hyphen character 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~

Fonts
s1,

s2,

etc. are special and will be searched for characters 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~

Space-character size set to
N/12

of the spacewidth in the current font.

Space-character size set to
N/12

and sentence space size set to
M/12

of the spacewidth in the current font (=1/3 em).

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

os

request.

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 repition character.

Set tab repetition character to~c.

Temporary indent next line (default scaling indicator~

Enable track kerning for
font.

Three-part title.

Print
anything

on terminal (UNIX standard message output).

Print
anything

on terminal (UNIX standard message output), allowing leading
whitespace if
anything

starts with

Text

"
"

(which will be stripped off).

Similar to

.tm1

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

tr

request except that the
asciify

request will use the character code (if any) before the character
translation.

This is the same as the

tr

request except that the translations do not apply to text that is
transparently throughput into a diversion with

!.

Make the built-in condition
t

true and
n

false.

Underline font set to
font

(to be switched to by

.ul ).

Underline (italicize in troff)
N

input lines.

Unformat space characters and tabs, preserving font information in
diversion.

Enable vertical position traps if
n

is non-zero, disable them otherwise.

Change to previous vertical base line spacing.

Set vertical base line spacing according to
±N

(default scaling indicator~

Default value is

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

.write

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.











preprocessorstart macro end macro


eqn.PS.PE
grap.G1.G2
grn.GS.GE
pic.PS.PE
refer.R1.R2
soelimnonenone
tbl.TS.TE

 

ESCAPE SEQUENCES

Escape sequences are in-line language elements usually introduced by a
backslash

Text

"
"

and followed by an escape name and sometimes by a required argument.
Input processing is continued directly after the escaped character or
the argument resp. 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
[name]

and constant arguments (number expressions and characters) by
apostrophes (ASCII 0x27) like
constant.

There are abbreviations for short names.
Two character escape names can be specified by an opening parenthesis
like

(xy

without a closing counterpart.
And all one-character names different from the special characters

Text

"
"

and

Text

"
"

can even be specified without a marker in the form

c.

Constant arguments of length~1 can omit the marker apostrophes, too,
but there is no two-character analogue.

While 1-character escape sequences are mainly used for in-line
functions and system related tasks, the 2-letter names following the

(

construct are used for special characters predefined by the roff system.
Escapes sequences with names of more than two characters

denote user defined named characters (see the

char

request).

 

Single Character Escapes

Back to Top

PayPal Logo┬ęCheap VPS LLC - Leader of affordable VPS Hosting Services