roff: some examples

To see the result of an example: show

See also the comments at top of the show script; for X, check the fonts in app-defaults/GXditview. These examples include comments (lines starting with .\") and newlines (.br); they all end with .pl 0 to suppress the blank rest of the last page, provided that no blank line follow it. The examples have been tested on groff, but most of them should work on other versions of roff.

Character formatting

Roff reads input lines, changing formatting when a line begins with .something or contains \something.
special characters, accents
change font face, size and interline

Blocks of text
ignore blocks of text
vertical movement, vertical position, no space on a return
page break, and how to avoid it after a line

Justification and indenting
text justified on the center, right, left or both sides
indent and temporary indent
no-fill mode, no-fill centering, no adjust mode
set tab stops, make tables; leaders; fields

Horizontal and vertical movements
mark a vertical position, return there later; high-water mark
horizontal movement, store horizontal position, string width
line numbering, temporarily suspend line numbering

Registers and control statements
numbers, registers
control statements: conditionals, cycles
string variables, substrings, string length

Registers contain only values, with no unit attached. Often, this value is in "u" units, while some requests have default unit "v" or "m". In such cases, specify the unit as in \n[register]u, \n[.h]u or \n[.p]u (, Also use "u" on multipliers or dividers, like in \n[.h]u/2u.

In some commands, + and - mean relative to the current value, while | mean an absolute value. For example: .sp (, .pl (

macros, macros with arguments, backslashes in macros, return
recursive macros

Escape sequences like \x are evaluated when the macro is defined. To evaluate them when it is called, use \\x. This is usually what intended.

Both macros and diversions (see below) can be started in a macro and terminated in another, where they can be used.

size and margins of page
header and footer

Partially filled line

The way output lines are created affects several commands; particularly important is the partially filled current line. Groff reads input words and collects them into the current output line. This current output line is said partially filled until it reaches the required length.

When this happens, the current output line is said filled. It is cut at the appropriate length, adjusted (aligned) and output (shipped out); what remains out from the cut makes the new (partially filled) current output line.

For example, with line length of 12 characters monospace:

inputcurrent linestateshipped outnew current line
abcd abcd partial
efgh abcd efgh partial
ijkl abcd efgh ijkl filled abcd efgh ijkl (partial)
mnop ijkl mnop partial

This is important because this mechanism is not transparent: a number of commands are affected by the current output line. In other words, the result they produce depends on what is in the current output line.

As an example, shows that a certain kind of vertical movement may also move some text that is before the command itself. This text is exactly the current output line when the command is encountered in the input text. Other things affected by the current output line:

Also related to filling are: .br and .brp; the difference between centering with .ce and .ad c (; .nf and .fi (no-fill mode=do not wait lines to be filled to output them).


Diversions store formatted text. This includes line formatting, which is undone unless the diversion is called when in no-fill mode (between .nf and .fi).

Only the lines that complete (become filled) between .di name and .di go in the diversion. This includes the partially filled line before .di name but not the partially filled line when .di is encountered:

Diversions can be used in the middle of a line, with \*[name]; the command .chop removes the terminating newline, which would show as a space; example:

A diversion may be started in a macro and ended in another, when its content is also used. This is shown in The same can be done for a macro instead of a diversion.


Several requests do not have an explicit termination, but only the number of lines to which they apply. For example, .ce 2 is a request to center the following two lines. Use .ce 1000 to begin and .ce 0 to terminate.
some graphics requests
include other files, end processing
write to a file (requires -U)
character translation, a macro called at the end of the document, a macro called at blank lines, write on stderr, margin character, brackets and tall lines, environments

For debugging, .tm, .ab .pm are useful, as well as the command line options -ww and -b.

Additional information