Let us first survey some basic concepts necessary to use a macro package fruitfully.11 References are made throughout to more detailed information.
GNU troff
reads input prepared by the user and outputs a
formatted document suitable for publication or framing. The input
consists of text, or words to be printed, and embedded commands
(requests and escape sequences), which tell GNU
troff
how to format the output. See Formatter Instructions.
The primary function of GNU troff
is to collect words from
its input, fill output lines with those words, break
the line at the right-hand margin (possibly by hyphenating a word),
adjust the line to reach that margin (if necessary) by
widening spaces between words, and output the result.
In fact, we know full well today that it is futile to speak of liberty as long as economic slavery exists. (Kropotkin) ⇒ In fact, we know full well today that it ⇒ is futile to speak of liberty as long as ⇒ economic slavery exists. (Kropotkin)
Sometimes a new output line should start even though the current line is
not yet full—for example, at the end of a paragraph. GNU
troff
will do this for us automatically at the end of input,
but we often want a break sooner, and more frequently. We wish to
instruct the formatter.
To that end, not all input lines are text lines containing
words to be formatted. Control lines start with a dot
(‘.’) or an apostrophe (‘'’) as the first character, and are
followed by a request or macro name that tells a macro package (or GNU
troff
directly) how to format the text.
We can command a break with the br
request. Some requests cause
a break automatically, as do (normally) blank input lines and input
lines beginning with a space or tab.
A macro bundles text and/or control lines into a named collection that can be called like a request. A macro can also be called by a trap that is set to “go off” automatically at certain places on the page. Thus, while requests perform primitive operations, macros handle complex ones, like arranging the output into columns, collecting and writing out footnotes, or managing page headers and footers.
Many requests and macros accept arguments that influence their
behavior. A “plain” sp
request breaks and puts a blank line on
the output. But
.sp 4
spaces four lines instead. Spaces (but not tabs) separate arguments from the request or macro name and from each other.
Here are a few hints for preparing text for input to GNU
troff
.
troff
packs words onto longer
lines anyhow.
troff
then recognizes punctuation
that ends a sentence, and inserts inter-sentence space accordingly.
We offer further advice in Input Conventions.
Vertical spacing is the distance between lines of text; it is expressed in the same units as the type size—the point. The default is 10-point type on 12-point spacing. To get double-spaced text you would set the vertical spacing to 24 points. Some, but not all, macro packages expose a macro or register to configure the vertical spacing.
A number of requests allow you to change the way the output is arranged on the page, sometimes called its layout. Most macro packages don’t supply macros for performing these (at least not without performing other actions besides), as they are such basic operations. The macro packages for writing man pages, man and mdoc, discourage explicit use of these requests altogether.
Arguments to requests and macro calls can often be measurements rather than simple integers. For instance,
.sp 1.5i My thoughts on the subject .sp
outputs one and a half inches of vertical space, followed by the line “My thoughts on the subject”, followed by a single blank line (more measurement units are available; see Measurements). Excess vertical space is normally discarded at page or column breaks. If the above example appears one inch from the bottom of the page, the half inch of space “left over” does not appear at the top of the next.
If you desire precise spacing control when using a macro package, be
advised that it might not honor sp
requests as you expect; it can
use a formatter feature called no-space mode to prevent excess
space from accumulating. See Manipulating Spacing. Use the
facilities the package offers to control spacing between paragraphs,
before section headings, and around displays (discussed below).
Text lines can be centered by using the ce
request. The line
after ce
is centered (horizontally) on the page. To center more
than one line, use ‘.ce N’ (where N is the number
of lines to center), followed by the N lines. To center many
lines without counting them, try the following technique.
.ce 1000 many lines of input .ce 0
The ‘.ce 0’ request tells GNU troff
to center zero
more text lines—in other words, to stop centering.
GNU troff
also offers the rj
request for right-aligning
text. It works analogously to ce
and is convenient for setting
epigraphs.
The bp
request starts a new page.
All of these requests cause a break, starting a new line. If you invoke them with the apostrophe ‘'’, the no-break control character, the (initial) break they normally perform is suppressed. ‘'br’ does nothing.