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.
Roff reads input lines, changing formatting when a line begins with .something or contains \something.
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).
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.
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:
input | current line | state | shipped out | new 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 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.
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.
For debugging, .tm, .ab .pm are useful, as well as the command line options -ww and -b.