Next: , Previous: , Up: Tutorial for Macro Package Users   [Contents][Index]


3.1 Basics

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.

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 the layout of the page. 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 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.


Next: , Previous: , Up: Tutorial for Macro Package Users   [Contents][Index]