Chapter 17
groff

by Tim Parker

In This Chapter

•   Embedding Commands

•   Controlling Character Appearance

•   Macros

•   Using mm

The groff program is the GNU version of nroff and troff, text-formatting languages that have been used in UNIX for many years. The groff system includes versions of troff, nroff, eqn, tbl, and other UNIX text-formatting utilities. The groff language is used primarily to compile man pages written and stored in groff/nroff format into a form that can be printed or displayed onscreen.

The nroff language was designed to provide text formatting in lineprinters, whereas troff was developed for phototypesetters. The commands in the two languages are identical, although some commands that cannot be processed by a lineprinter are ignored by nroff. In most cases, you don’t use nroff or troff directly, but use a macro package to access them.

For the most part, nroff and troff have fallen into disuse with the development of powerful word processors and desktop publishing packages. Their sole remaining use is for formatting man pages, which continue to be used widely.

Both nroff and troff have many commands that you will never require. Therefore, in this chapter we will look at the basic command set necessary for you to use the groff version of the two languages, and how they can be used for man page-specific applications. If you really want to use groff for advanced text formatting, you should pick up a dedicated book on the subject.

Embedding Commands

One aspect of groff that may take a little getting used to is that the way you type lines in the file isn’t necessarily the way they will be displayed in the finished output. The groff system runs text lines together as much as possible. For example, the source file

This is fine stuff.

It is really interesting and

could keep me busy for hours.

covers three lines in the source, but when formatted, it runs together by groff to look like this:

This is fine stuff. It is really interesting and could keep me busy for

 hours.

with line breaks wherever necessary because of the page layout. This has an advantage in that you don’t have to worry about making everything look properly formatted within the source. However, the disadvantage is that you don’t have an accurate idea of what the output will look like until you see it.

A look at a groff source file shows that it is all ASCII characters which contain the usual text of the displayed output and a set of commands starting with a period, like this:

This is a bunch of text that will be displayed.

Here is even more text.

.ps 14

The line above is a groff command, identified by the

period in the first column of the line.

Most groff commands are on a line by themselves, although a few can be embedded anywhere on a line. These commands are usually prefaced by a backslash, much as the shell uses the backslash as an escape character. An example of a line with embedded commands is

This \fBline\fR has two embedded \fIgroff\fR commands.

Although there will be times when you want to use embedded commands, the majority of the commands used will be on a single line, starting with a period.

Controlling Character Appearance

The groff language has a few commands for controlling the way characters look when printed or displayed. These include changing the size and line spacing of characters, as well as controlling fonts.

Sizes and Line Spacing

Character size and line spacing are not usually useful when displaying text onscreen, unless you are using a bitmapped terminal. They are used for printed documents, though. You can change the size of text with the .ps (point size) command:

This is the default 10-point size.

.ps 14

This is now in fourteen-point size.

.ps 20

This is a point size of twenty.

.ps 6

And this is a really small point size of six.

---

Note:  
A point is 1/72 of an inch, so a 36-point character size is half an inch high. The 12-point size used most commonly is 1/6-inch high. Different versions of groff support different point sizes, but most versions support 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, and 36 points. If you set a value that is not supported, it is rounded up to the next highest value (to a maximum of 36). The default point size is 10. If you use the .ps command without a value, groff reverts to the previous value.

---

Within a sentence, the point size can be changed with the line-embedded command \s followed by the point size. For example:

This is in 10-point, while \s20this is in twenty,\s10 and back to 10

 again.

The \s command should be followed by a legal point size. The special command \s0 causes groff to revert to its previous value. Relative changes are also supported, so you can embed commands such as \s+2 and \s-2, although only a single digit can be specified (so you can’t change by more than 9 points).

Line spacing is controlled by the .vs (vertical space) command. In the next example, we change the point size and the vertical spacing to permit the characters to be printed clearly without overlap:

This is in normal 10-point, 11 vertical space size.

.ps 12

.vs 14

This is in 12-point with 14 vertical spacing.

If you use the .vs command without a value, groff reverts to the previous value.

If you want to force spacing for some reason, such as to separate sections of text, use the .sp (space) command. Used with no argument, .sp gives one blank line. It can also take arguments of i for inches and p for points:

This is default 10-point 11 vertical spaced text.

.sp

We have a blank line above this because of the command.

.sp 3.5i

This is three and a half inches below the previous line.

You can use fractions in most groff commands, as this example shows.