UNIX UNLEASHED PHẦN 5 pps

Part V — Text Formatting and Printing

Basic Formatting with troff / nroff

Formating with Macro Packages

Formatting Tables with tbl

Formatting Equations with eqn

Drawing Pictures with pic

Creating Graphs with grap

Writing Your Own Macros

Tools for Writers

Processing, Printing, and Troubleshooting Formatted Files

 21 — Basic Formatting with troff/nroff

 By James C. Armstrong

 Formatting with nroff/troff An Overview

 Printing nroff and troff Files

 Text Filling and Adjusting

 Vertical Spacing

 Line Controls

 Page Control

 Fonts and Style Controls

 In-Line Escape Sequences

 Special Characters

 Strings and Macros

 Number Registers

 Traps and Diversions

 Tabs, Character Conversions, and Controls

 Local Motions

 Overstrikes, Lines, and Arcs

 Conditional Text

 File Switching and Environments

 Flotsam and Jetsam

 Quick Reference of nroff/troff Requests

 Summary

21 — Basic Formatting with troff/nroff

By James C. Armstrong

One of the most common uses for any computer is text processing, and in this respect

machines running UNIX are no different than any others.

Many products exist for UNIX machines, including WordPerfect, Microsoft Word,

IslandWrite, and FrameMaker. Although very powerful, these text processors might not

be available on every machine. The best solution for almost every platform is the troff

text processor and its cousin, nroff. troff is short for "text run-off" and was originally

developed by Joseph Ossanna in the early 1970s, for use with the Graphics Systems CAT

typesetter. This was the typesetter in use at the Murray Hill Computer Center of Bell

Labs, where UNIX was first developed. In 1979, in response to the need to support more

typesetters, Brian Kernighan rewrote troff. Although alternatives were investigated,

UNIX had already invested a large amount of effort in troff, including macro packages

and preprocessors for the utility. You have already learned about manual pages, which

are written in troff using a specialized macro package.

Closely associated with troff is nroff. They both use the same set of commands to format

text, the biggest exception being that nroff does not support commands for changing

point sizes and supports only a limited number of character set changes. nroff also

provides ASCII output, so you can see the results of your nroff command on your screen.

Although third-party products can show the results of your troff command on screen if

they have graphics capabilities, on a standard UNIX system, the only way to see the troff

output is to send it to a printer.

Formatting with nroff/troff An Overview

Many word processors such as Microsoft Word and WordPerfect are WYSIWYG

processors (what you see is what you get). With those word processors, you choose menu

items or press key combinations that cause the formatting to occur right on the screen, but

the formatting codes do not appear in your document. Text processors like nroff and troff

are called descriptive markup languages, which means that you enter the formatting

codes into your document like any other text, and you don't see the effects of those

instructions until you print the file.

Several building blocks are available for formatting files using nroff and troff, including

the following:

Primitive requests The standard command in troff is called a primitive

request and has the form of a period followed by two lowercase letters.

The period must appear in the first column, and any text after the

request is an argument. Primitives are

used to do all kinds of formatting, such as indenting paragraphs,

adding space between paragraphs, changing fonts, and centering text.

This chapter provides examples of using the more common primitives and

a quick reference that briefly describes all

primitives. If you are new to nroff/troff, you might want to try using

a macro package before you dive into primitives.

Macros Most UNIX systems provide standard macro packages, which enable

you to format documents more easily than with primitives. Macros

perform operations more or less automatically, such as formatting

bulleted lists, headings, and indented paragraphs.

Four macro packages, mm, ms, me, and man are described in detail in

Chapter 22, "Formatting with Macro Packages." Chapter 27, "Writing Your

Own Macros," shows you the ins and outs of creating macros. You can

create a file using only

macro package commands, or you can mix macros and primitives in the

same file.

Preprocessors Most UNIX systems provide standard preprocessors. Each

preprocessor is a set of commands devoted to a special task. You can

format tables with the tbl preprocessor (Chapter 23), equations with

eqn (Chapter 24), line drawings with pic

(Chapter 25), and graphs with grap (Chapter 26). You can create a file

containing only preprocessor commands, and you can embed preprocessor

commands in regular documents formatted with primitives, a macro

package, or both.

Strings Strings can be defined, just as macros can. For example, if you

were writing about a new product whose name hadn't been decided yet,

you could define a string for the temporary name "Hot New Product."

When the name was finally chosen,

you wouldn't have to do a global search and replace for "Hot New

Product." You could just redefine the string to produce "XYZZY Thingo."

Specific instructions for defining strings are in the section titled

"Strings and Macros"

later in this chapter, and in Chapter 26, "Writing Your Own Macros."

Number registers Number registers are used to keep track of values like

your current font and point size, your current indentation, and the

current list item. They are really nothing more than storage locations.

Some are read-only; others can be

manipulated. You can define your own number registers and use them in

macros. Specific examples are given in the section titled "Number

Registers" later in this chapter, and in Chapter 26, "Writing Your Own

Macros."

NOTE: troff insists on calling these registers "number registers," but in fact they

don't need to contain numbers; they can—and often do—contain alphabetic characters.

Escape sequences Escape sequences (backslash-character or backslash￾open-parenthesis-character-character) can be used to change fonts and

point sizes and for many other tasks. Some escape sequences enable you

to enter troff primitives in-line with the

text they affect rather than on lines by themselves. Specific examples

are given in the section titled "In-Line Escape Sequences" later in

this chapter and in other chapters where they apply.

Special characters Although these are system-dependent, there are a

number of special characters that are usually available on all systems,

such as a long dash, a degree symbol, and a copyright symbol. Specific

examples are given in the section titled

"Special Characters" later in this chapter and in other chapters where

they apply.

Processing troff and nroff files for printing is discussed in Chapter 29, "Processing,

Printing, and Troubleshooting Formatted Files."

Chapters 21 through 29 give you a good start on using the nroff/troff family of text

processing tools, but there is much more that you can do with them. For additional

information, you can consult the nroff and troff man pages online or your local bookstore

for books dedicated to this subject.

Printing nroff and troff Files

UNIX offers a selection of commands and utilities for printing. Printing nroff and troff

output files is covered in detail in Chapter 29. It describes the role of the preprocessors,

nroff and troff, the role of the postprocessors, and introduces you to PostScript. It also

reviews raw printing (just dumping the contents of your file with no formatting at all)

because sometimes you'll want to print a file without formatting it.

Text Filling and Adjusting

The cleanest look to any document is when the text looks symmetric, with one or two

smooth margins, and spread across the page—like this paragraph. The default settings for

nroff and troff are to "fill" each line with text, and to "adjust" the position of the text so

that all lines begin at the left margin, and the right margin is justified. In the simplest

case, the input file does not need any troff requests to format a basic document. Listing

21.1 illustrates a basic input file, and Figure 21.1 illustrates the output produced by nroff.

Figure 21.1. roff output with no requests.

Listing 21.1. Basic nroff/troff source with no requests.

We, the people of the United States, in order

to form a more perfect Union, establish justice, insure

domestic tranquility, provide for the common defense, promote

the general welfare,

and secure the blessing of liberty to ourselves and our posterity do

ordain and establish this Constitution for the United States of

America.

The raw text file has a ragged right margin, with some lines very short, and one line

longer than desired. By putting the text through nroff, the lines are set to an even length,

and the margins are smooth. Two words were broken across lines. If you look closely at

the output, you'll see that nroff justifies the right margin by inserting extra spaces

between words, at alternating ends of each line. The first line needed no extra spaces, but

to even the margin on the second line, an extra space was included between "perfect" and

"Union," and the third line needed four extra spaces.

troff output of the same text, shown in Figure 21.2, shows that the lines are expanded to

justify the margins by changing the spacing of letters across the entire line.

Figure 21.2. troff output of Figure 21.1.

The ability to fill the text can be set with two requests. The first, .fi, tells troff that you

want the text to be filled with input. This is the default setting. The request .nf tells troff

that you don't want text filled, that you want the right margin to be ragged. This is useful

for cases where a block of text is inappropriate, such as a return address or poetry. Listing

21.2 shows a sample input file for a letter, with no fill in places, and fill in places. Figure

21.3 shows the output.

Figure 21.3. troff output showing filled and nonfilled text.

Listing 21.2. troff source illustrating the fill requests.

.nf

101 Main Street

Morristown, NJ 07960

15 March, 1994

Dear Sir,

.fi

I just wanted to drop you a note to thank you for spending the

time to give me a tour of your facilities. I found the experience

both educational and enjoyable. I hope that we can work together

to produce a product we can sell.

Note that a blank line is used to separate blocks of text. On a longer document, these

blank lines can be used to separate paragraphs. Another way to separate blocks is to use

.br. This interrupts the filling of the current line and starts a new block of text. The same

can be done by starting a line of text with a space. Figure 21.4 shows the output of

Listing 21.1, but includes a break after "the general welfare."

Figure 21.4. troff output showing the effect of a break in midsentence.

Although smooth margins are the default, this is also something under the control of the

writer. The .ad command controls adjustment. It can take the following as arguments: l

means to adjust the left margin only; r is to adjust the right margin only; c is to center

each line; and b or n means to adjust both margins. Figure 21.5 shows the effects of .ad l,

.ad r, and .ad c on the first text sample. .ad b is the default starting value and is effectively

demonstrated in the first example.

Figure 21.5. troff output showing the effects of different line adjustments.

Obviously, adjustment makes no sense if the text is not filled. Right margin adjustment

can also be turned off with .na. The adjustment mode is not changed.

The last type of text adjustment is centering. This is a bit different than .ad c, which

continues to fill lines before centering the text, but only if .fi is specified. The centering

request is .ce and can be followed by a number. This centers the next line or lines,

without filling text. If the text is being filled, each input line is treated as if it is followed

by a break. Non-filled lines would be treated the same as .ce. Chapter titles are an

example of text centering. Listing 21.3 is the source for a centering command, and the

output is illustrated in Figure 21.6.

Figure 21.6. The effects of the centering request.

Listing 21.3. troff source for the centering command.

.ce 3

Scientific Methods of Computing

A Simulation

by John Smith

Vertical Spacing

There are three types of vertical space controls in troff. Baseline spacing controls the

basic spacing between consecutive lines of text. The next type is extra line spacing; this is

the ability to double-space text, or more, both on a regular basis, and on a per case basis.

The last is a block of vertical space.

Space measurements have different scales. When a request needs a distance, you can use

the default type or modify the number with an indicator. The measurement types are

inches, centimeters, Picas, Ems, Ens, points, units, and vertical line spaces. A Pica is 1/6

of an inch. An em is the width of the letter m and is dependent on the font used in troff.

An en is half an em. The modifiers are listed in Table 21.1.

Table 21.1. troff space measurement modifiers.

Measurement Option Description

i inch

c centimeter

p Pica

m Em

n En

p point

u unit

v vertical space

The default vertical spacing between lines of text is dependent on the text processor used.

For nroff, it is 1/6 of an inch. For troff, it is 12 points. This can be changed with .vs. For

nroff, the command argument is rounded to Picas, so if extra space is needed

regularly, .ls is clearer. With troff, the default space measurement is points, although any

measurement type can be used. An example of different spacings is given in Figure 21.7,

using the initial text sample.

Figure 21.7. Different vertical spacing using troff.

The .ls request, mentioned previously, is used to indicate the number of blank lines

between each line of text. The default value is 1, for single spacing. Double-spacing text

is accomplished with .ls 2. Figure 21.8 shows the first text sample, but with .ls 2.

Figure 21.8. Different line spacing using troff.

Block spacing can be achieved with the .sp request. With no arguments, this gives a

single blank line. It can take arguments of any size, with the default unit being the

vertical spacing. Negative numbers space back up the page; positive numbers head down

the page. Spacing changes requested here will not leave the page—if the requested space

is beyond the bottom of the page, the text will start at the top of the next page. Using the

sample letter, you can leave an inch of space between the date and the salutation. The

source is changed in Listing 21.4, with the output in Figure 21.9.

Figure 21.9. troff output with a block of space.

Listing 21.4. troff source for block spacing.

.nf

101 Main Street

Morristown, NJ 07960

15 March, 1994

.sp 1i

Dear Sir,

.fi

I just wanted to drop you a note to thank you for spending the

time to give me a tour of your facilities. I found the experience

both educational and enjoyable. I hope that we can work together

to produce a product we can sell.

Another method to grab a block of vertical space is the .sv request. It takes the same

arguments as .sp but has some different behaviors. You cannot request space at the top of

a page with .sp, for example. Also, if a space request exceeds the size of the page, it is

truncated at the bottom of the page with .sp. With .sv, the space is not generated unless

there is room on the page for the space. In this case, the space requested is remembered

and can be released on a new page with .os. Normally, .os appears only in complicated

macro definitions, which are discussed later.

For the sample letter, save a half inch of space at the top of the page. The source is

Listing 21.5, and the output is Figure 21.10.

Figure 21.10. troff output with requested space using .sv.

Listing 21.5. troff source using .sv.

.sv 0.5i

.nf

101 Main Street

Morristown, NJ 07960

15 March, 1994

.sp 1i

Dear Sir,

.fi

I just wanted to drop you a note to thank you for spending the

time to give me a tour of your facilities. I found the experience

both educational and enjoyable. I hope that we can work together

to produce a product we can sell.

Two other spacing controls are also available. The request .ns turns off spacing mode,

effectively disabling the .sp command. To restore spacing, .rs is used. These commands

are more likely to be found in macros.

Line Controls

So far, I have examined troff requests to fill and adjust lines of text and to move your

location on a page. I will now examine how to alter the line itself.

By default, the length of a line of text is 6.5 inches in nroff, and 7.54 inches in troff. This

can be changed with the .ll request. The default space measurement is in ems, but I find

using inches a bit easier. Listing 21.6 shows the source, changing the line length to 4

inches; its effect on the output is shown in Figure 21.11.

Figure 21.11. troff output with line indents and lengths.

Lines of text can also be indented, both for a single line and for all text. The .in request

indents all lines of text a common distance. This is illustrated by indenting the return

address in Listing 21.6. A temporary indent can be requested with .ti, such as might lead

a paragraph. This is also illustrated in Listing 21.6 and Figure 21.11.

Listing 21.6. troff source illustrating line indents and lengths.

.nf

.ll 4.0i

.in 2.0i

101 Main Street

Morristown, NJ 07960

15 March, 1994

.sp 1i

.in 0

Dear Sir,

.fi

.ti 0.25i

I just wanted to drop you a note to thank you for spending the

time to give me a tour of your facilities. I found the experience

both educational and enjoyable. I hope that we can work together

to produce a product we can sell.

Using text indents can help organize a document.

Page Control

So far, this chapter has examined how to format text independent of the page, but for

most documents, page controls are necessary. Both nroff and troff default to an 11-inch

page. troff has a one-inch left margin, and nroff has no left margin. Pages start at page

one and are sequentially numbered. Each of these details can be changed by the

document writer.

The .pl request sets the length of a page; the default space measurement is in vertical

spaces. Again, inches can be better used here. For the sample letter, assume a page length

of 8 inches. (Some other normal page lengths are 12 inches for A4 paper and 14 inches

for legal-sized paper. troff can support pages up to 75 inches in length, and nroff up to

136 inches.)

You can force new pages with the .bp request. An argument can affect the number of

pages output. The .ns request, mentioned earlier, disables the .bp request, unless a

specific number of pages is requested.

The .pn request assigns a page number to the next page printed. This does not affect the

present page, only subsequent pages. These three requests are illustrated in Listing 21.7

and Figure 21.12, an extended form of the letter.

Figure 21.12. troff output with page controls.

Listing 21.7. troff source illustrating page controls.

.nf

.ll 5.0i

.pl 8.0i

.in 2.5i

101 Main Street

Morristown, NJ 07960

15 March, 1994

.in 0

.sp 1i

Dear Sir,

.fi

.ti 0.5i

I just wanted to drop you a note to thank you for spending the

time to give me a tour of your facilities. I found the experience

both educational and enjoyable. I hope that we can work together

to produce a product we can sell.

.pn 4

I am sending a copy of our proposal on the next page. I look forward

to hearing from you.

.sp 2

.in 2.5i

Yours,

.sp 0.5i

Joe Smith, President Any Corp.

.bp

.in 0

We propose to build our widget tools with your widget makers.

Note that the page number is not printed. Page numbers are printed only if explicitly

requested by the programmer. These techniques are discussed later in this chapter in

Section 21.19 "Flotsam and Jetsam," where I discuss page titling.

The text can be offset on the page using the .po request. This is different from the .in

request. .po sets the 0 value for indents and temporary indents. This is illustrated in

Figure 21.13, which has a page offset of two inches to the preamble of the Constitution.

Figure 21.13. troff output with a two-inch page offset.

Two very powerful page controls are the .mk and the .rt requests. The .mk request saves

the current vertical location in an internal register (which can be specified in the

argument). This sets a flag at the current location. The .rt request returns to that previous

location. One good use for these requests is to establish multiple column output. The

programmer can set the mark at the top of the page, and at the bottom of the page return

to the mark. This is illustrated in Listing 21.8 and Figure 21.14. Note that the simple

multiple column approach also requires the use of the .ll and .po requests.

Figure 21.14. troff output showing the work of .mk and .rt.

Listing 21.8. troff source using .mk and .rt requests.

.ll 3i

.mk a

.ce

Preamble

.sp

We, the people of the United States, in order

to form a more perfect Union, establish justice, insure

domestic tranquility, provide for the common defense, promote

the general welfare,

and secure the blessing of liberty to ourselves and our posterity do

ordain and establish this Constitution for the United States of

America.

.sp

.ce

Article I

.sp