groff

by Jim Parker

IN THIS CHAPTER

• Embedding Commands

• Controlling Character Appearance

• Macros

• Using mm

This chapter looks at the groff text-formatting utility. Specifically, you will learn about the following topics:

• What groff is

• How to do basic text formatting

• How to create macros

• What the mm macro package is

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 on-screen.

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 primary 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.

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's run 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 might not have any idea what the output will look like until you see it!

A look at a groff source file shows that it is all ASCII characters that 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 are the commands on a single line, starting with a period.

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.

Character size and line spacing are not usually useful when displaying text on-screen, 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 14-point size.

.ps 20

This is a point size of 20.

.ps 6

And this is a really small point size of six.

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 20,\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 could 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 nine points).

Line spacing is the vertical spacing between lines. Vertical spacing is not tied to point size, so it should be adjusted manually. As a general rule, use a vertical spacing about 20 percent larger than the point size. The default vertical spacing is 11.

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, you can 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.

Changing fonts requires the command .ft (font type). In the early days of troff, only four fonts were supported: Roman, Roman bold, Roman italics, and a set of special characters. Other fonts had to be specially loaded in the phototypesetter. For this reason, groff defaults to Roman.

To switch to Roman bold, you use the command .ft B, while .ft I switches, not surprisingly, to Roman italics. To return to the normal Roman font, the command .ft R is used, although on most systems, .ft by itself will suffice:

This is in normal Roman font.

.ft B

This is bold.

.ft I

This is italics.

.ft

This is back to normal Roman font.

You can switch fonts with a line-embedded command, too, using \f followed by either I or B, switching back with R to the normal font:

This is normal, \fBbold\fR and \fIitalics\fR.

Because underline wasn't supported on most system printers, underlined text was converted to italics. The underline command .ux would italicize the next x lines of text.

Because we now have many thousands more fonts to work with than Roman, we must be able to change fonts within groff. The command to change fonts is .fp (font physically mounted), which also requires a number to indicate what position the font was mounted in the phototypesetter (old stuff, isn't it?). For example, if Helvetica were mounted in font position three and we referred to it by the font letter H, the command

.fp 3 H

would instruct the phototypesetter to switch to Helvetica in font position three. groff still retains these old-style commands.

The line length is set to default to 6.5 inches within groff. To override this value, the .ll (line length) command is used with an argument indicating the units. For example, the command

.ll 7i

switches groff to use a seven-inch line length. The maximum length accepted is usually about 7.5 inches, so to use paper wider than that you have to move the left margin over to compensate with the .po (page offset) command. The value .po 0 sets the left margin as far over as is possible.

To indent text, you use the .in (indent) command. It takes a number and an indicator of the units as arguments, as the following example shows:

This is normal stuff.

.in 0.75I

This is indented three-quarters of an inch.

To move the right margin to the left so that you can make a distinctive block of text within a normal chunk, you use the .ll (line length) command you saw earlier:

This is normal text, and goes on and on.

Even more text that continues the tradition.

.in 1i

.ll -1i

This is now indented one inch to the left, and the

right margin is indented one inch from the normal right

margin.  This makes the text stand out a little.

.in -1i

.ll +1i

And this is back to normal.  The block will stand out nicely

amongst all this normal text.

You will notice that we used relative movements of plus and minus a value in this example to make it easier. This way, we don't have to measure the page. You can revert to original values with the command .in and .ll with no arguments, as well.

An indent and line-length change is effective until the next command changes it. Sometimes you want to affect only a single line, though. If you want to indent only a single line, use the .ti (temporary indent) command:

This is really fine stuff.  You can tell, `cause I'm

still awake.

.ti 3i

This line is temporarily indented by three inches, but the

next line will be back to normal.

Tabs are used to set column output. Usually, tabs are used with groff only for unfilled text, which means material you would display in columns. Tab stops are set, by default, every half inch. To override these values, you use the .ta (tab) command. The command

.ta 1i 2i 3i 4i 5i 6i

sets the tabs at every inch instead. You can think of the setting of tabs within groff much as they are done on a typewriter, from left to right. Tabs are usually set for columns of numbers or tables, but the groff macro gtbl is much better at this. (You get a look at gtbl in the next chapter.)

The groff system has special instructions for controlling the size of individual letters, as well as formulas and special characters such as Greek letters. However, because groff is not needed for most purposes these days, we'll ignore the capabilities. If you want more information on how to provide these special features, check the groff man pages or consult a good troff book.

A macro is a shorthand notation for a set of commands or strings. Many commands used to write man pages are macros. To give a practical example of a groff macro, suppose we want every paragraph to start with a blank line and a temporary indent of half an inch. The groff commands to do this are

.sp

.ti +.5i

Instead of typing these two lines every paragraph, we can define a macro of one character (or more) that does it for us.

To define the macro, we use the .de (define) command followed by the name of the macro and the commands. It would look like this, placed somewhere at the top of the source code:

.de PP

.sp

.ti +.5I

..

The last line with two periods indicates the end of the definition. Now, whenever we use the command .PP it will be executed as the lines in the macro.

The mm (memorandum macros) package is not really part of nroff or troff, although both can use it. The mm program reads a source file much as groff does and translates it to output. Many of the mm macros are used for man pages. Indeed, many users find the nroff and troff commands too awkward or complicated, whereas mm is fully able to meet all their basic formatting needs.

To add mm commands, you use the period in the first column as with groff. The mm macros are usually quite simple, and easy to work with and use. We can look at the most important of them here.

Like groff, mm runs text together when reformatting, regardless of line breaks in the source file. To force a new paragraph, use the .P command. It forces a line break and adds a blank line to the output. Paragraphs are usually formatted so that they are flush left.

Headings are created with the .H command. For example, the command

.H This is a Heading

will create a break, output the heading text in bold, and leave a bit of a space between the heading and the text that follows it.

There can be seven levels of headings; 1 is the highest and 7 is the lowest. To specify the heading level, add the number as the first argument after the .H command:

.H 2 This is a level 2 heading

The mm heading macro will number the headings automatically, although you can suppress the numbering with the .HU (heading unnumbered) command. To reset the numbering (at a section break, for example), use the .nr (number register) command followed by the heading level and the number to use. For example, the command

.nr H2 1

will restart the numbering of second-level headings at 1.

Lists are easily created in mm with the .LI (list) command and the .LE (list end) command. This creates a bulleted list. For example, the command

.LI

thing 1

.LI

thing 2

.LE

thing 3

creates a bulleted list of the three bits of text. You can create a list with dashes instead of bullets using the .DL (dash list) command. The mark list command, .ML, creates a list with the character of your choice.

If you want a numbered list, use the .AL (automatic list) command. Lists with no arguments are created with Arabic numbers. To create an alphabetical list (A, B, C, and so on), use the macro command .AL A. Roman numerals (i, ii, iii, iv, v, and so on) can be used with the .AL I command.

You can nest list types as necessary. For example, the command

.AL I

.LI

groff

.AL

.LI

macros

.LI

mm

.LE

.LI

gtbl

.LI

geqn

.LE

will create output that looks like this:

I.  groff

      1. macros

      2. mm

II.   gtbl

III.  geqn

You have to be careful when terminating each list with an .LE command to ensure that you terminate the proper one. Experimentation and practice help you get the hang of this. You may have noticed that it takes a lot of commands to make a little list!