roff: some examples

To see the result of an example: show file.tr

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.

characters.tr
special characters, accents
font.tr
change font face, size and interline

Blocks of text

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

Justification and indenting

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

Horizontal and vertical movements

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

Registers and control statements

register.tr
numbers, registers
control.tr
control statements: conditionals, cycles
string.tr
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 (page.tr, mark.tr). 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 (vertical.tr), .pl (page.tr).

Macros

macro.tr
macros, macros with arguments, backslashes in macros, return
recursive.tr
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.

Pages

page.tr
size and margins of page
header.tr
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, fill.tr 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 (nofill.tr); .nf and .fi (no-fill mode=do not wait lines to be filled to output them).

Diversions

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: string.tr.

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

Other

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.

graphics.tr
some graphics requests
include.tr
include other files, end processing
write.tr
write to a file (requires -U)
misc.br
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