UNIX UNLEASHED PHẦN 5 pps

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.. The default settings for n

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

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 (character or open-parenthesis-character-character) can be used to change fonts and point sizes and for many other tasks Some escape sequences enable you

backslash-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

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

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

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

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

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

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

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

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

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

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

Section 1 Legislative powers; in whom vested:

.sp

All legislative powers herein granted shall be vested in a

Congress of the United States, which shall consist of a Senate and a House of Representatives

.sp

Section 2 House of Representatives, how and by whom chosen, Qualifications of a Representative Representatives and direct taxes, how apportioned Enumeration Vacancies to be filled Power of choosing officers and of impeachment

.sp

1 The House of Representatives shall be composed of members chosen every second year by the people of the several states, and the electors in each State shall have the qualifications requisite for electors of the most numerous branch of the

State Legislature

.sp

2 No person shall be a Representative who shall not have

attained to the age of twenty-five years, and been seven years

a citizen of the United States, and who shall not, when elected,

be an inhabitant of that State in which he shall be chosen .sp

.rt

.po 4.5i

3 Representatives and direct taxes shall be apportioned among the several States which maybe included within this Union,

according to their respective numbers, which shall be determined

by adding to the whole number of free persons, including those bound for service for a term of years, and excluding Indians not

taxed, three-fifths of all other persons The actual enumeration

shall be made within three years after the first meeting of the

Congress of the United States, and within every subsequent term

of ten years, in such manner as they shall by law direct The

number of Representatives shall not exceed one for every thirty

thousand, but each State shall have at least one Representative;

and until such enumeration shall be made, the State of New

Hampshire shall be entitled to choose three, Massachusetts eight, Rhode Island and Providence Plantations one, Connecticut five,

New York six, New Jersey four, Pennsylvania eight, Delaware one,

Maryland six, Virginia ten, North Carolina five, South Carolina

five, and Georgia three

.sp

4 When vacancies happen in the representation from any State,

the Executive Authority thereof shall issue writs of election

to fill such vacancies

.sp

5 The House of Representatives shall choose their Speaker and

other officers; and shall have the sole power of impeachment

The last page control is ne This is used to indicate that a certain amount of space is needed before the end of a page Using this request, you can avoid starting paragraphs at the bottom of a page Normally, ne would be included in a macro If the space requested

is available, nothing happens If the space is not available, the end of page processing is triggered

Fonts and Style Controls

The previous sections have dealt with the positioning of text on the page and have ignored the actual modification of the text itself This section handles different fonts and point sizes

The standard font is a Times Roman font Italic, Bold, and Special fonts are also available

on all systems Some sites may also include Helvetica, Bold-Helvetica, Italic-Helvetica, and Constant-Width fonts Check your local system for which fonts are available

The request ft sets the appropriate font Mounting and unmounting fonts is performed automatically with this request The requested font must be specified in the argument; if

no argument is present, the previous font is restored The arguments are shown in Table 21.2

Table 21.2 Standard troff and nroff fonts

Fonts have limited meaning in nroff The font used is a constant-width font By

specifying bold, characters are overstruck in printing Italic is interpreted as an underline Other fonts have no meaning

By setting fonts, you can italicize the preamble to the Constitution and print each section header in bold The source is in Listing 21.9, and the output is in Figure 21.15

Figure 21.15 troff output using multiple fonts.

Listing 21.9 Font selection in troff

.ce

.ft B

Preamble

.sp

.ft I

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

All legislative powers herein granted shall be vested in a

Congress of the United States, which shall consist of a Senate

and a House of Representatives

The bd request sets an artificial bold capability by offsetting a second printing of the character by a number of points This can be used to make the italic font appear to be bold, with bd I 3 There is no effect in nroff

Different sizes of text can be created using the ps request You can specify either a relative change or an absolute point size Closely related is the ss request, which sets the width of the space character Similarly, when the point size is changed, the vertical spacing may also need to be changed, or parts of consecutive lines may overlap Using these requests, you can increase the size of the section headers in the Constitution and increase the size of the words "We the people." This is illustrated in Listing 21.10 and Figure 21.16

Figure 21.16 Multiple point sizes in troff output.

Listing 21.10 troff source showing multiple point sizes

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

All legislative powers herein granted shall be vested in a

Congress of the United States, which shall consist of a Senate

and a House of Representatives

The last text request is cs, which sets a constant character width for a given font in troff This takes three arguments The first is a font, the second is the width of the space, and the last is the character point size If the third argument is absent, the default is the current character width If the second argument is also absent, that turns off the constant width

Listing 21.11 shows this for the default Times Roman font in the preamble, and turns it off for the remainder of the Constitution Figure 21.17 shows the output

Figure 21.17 troff output using cs.

Listing 21.11 troff source illustrating the cs request

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

Fonts can also be specified by position—font 1, font 2, font 3, and so on In the olden days of troff, before device-independent troff (ditroff), only four positions were available Quite naturally, 1 was the body type (Times Roman), 2 was the italic version of 1, and 3 was the bold version of 1 You got one elective—position 4—but it was almost always used for the Special font (the one with Greek letters and mathematical symbols) As a consequence, specifying fonts by position is not done frequently

The following examples all change the word "very" to italics (in nroff, the words are underlined):

This is \f2very\fP easy

You can count on finding your default body type in position 1, italics in 2, and bold in 3 Beyond that, you have no idea It depends on your system installation, and they're all different

TIP: Don't specify font changes by position for any position other than 1, 2, or

3 If someone at another branch of your company prints your file, you don't know what font 4 might be, and you can't control the results

What Does \f4 Look Like?

If you want to know what font is loaded in what position on your printers, create a test file that looks something like this:

When I ask for \ef4, I get \f4This Font\fP

When I ask for \ef5, I get \f5This Font\fP

When I ask for \ef6, I get \f6This Font\fP

Print the file, and you'll have a wall decoration that's attractive and useful

In-Line Escape Sequences

The basics of document building are now passed All the requests I have examined have been of the form xx and stand alone on each line Although any document can be

produced using these requests, an in-line request may be easier to use in many cases These can generate special characters, change fonts, change point sizes, and produce local motions

Escape sequences (backslash-character or

backslash-open-parenthesis-character-character) can be used to change fonts and point size and for many other tasks Table 21.3 lists troff escape sequences

Table 21.3 troff escape sequences

\ Prevents the next character from being processed by troff

\e Prints the escape character; default is the backslash (\)

\' Prints acute accent

\' Prints grave accent

\- Prints a minus sign in the current font

\[space] Creates an unpaddable 1-en space

\0 Prints a space the width of a digit

\| Prints a 1/6-em width space

\^ Prints a 1/12-em width space

\& Nonprinting zero-width character

\! Transparent line indicator

\\*x , \*(xx Specifies string named x or xx

\a Specifies leader character used in macros

\b'abc ' Bracket-building function

\c Interrupts text processing

\d Moves down half a line space

\D Draws line, circle, ellipse, arc, or spline

\fx, \f(xx,

\fn

Requests a font change; font with 1-character name is specified as \fH; font with 2-character name is specified as \f(HB

\h'n' Moves horizontally to the right; to move left, specify negative number

\H'n' Sets character height to n points

\jx Marks horizontal place on output line in register x

\kx Marks horizontal place on input line in register x

\l Draws horizontal line

\L Draws vertical line

\nx, \n(xx Interpolates number register x or xx

\o Overstrikes specified characters

\p Breaks output line

\r Reverse 1-em vertical motion

\s Requests a change in point size; can be specified as an absolute value or with

±

\S'n' Slants output n degrees to the right

\t Horizontal tab

\u Moves up half a line space

\v'n' Moves vertically down; to move up the page, specify negative number

\w Interpolates width of specified string

\x Extra line-space function

\zc Prints c with zero width (without spacing)

\{ Begins conditional input

\} Ends conditional input

\[newline] Concealed (ignored) newline

\X X, any character not listed above

Listing 21.12 shows troff input with in-line font and size changes, and Figure 21.18 shows the output

Figure 21.18 troff output with in-line font changes.

Listing 21.12 troff source with in-line font changes

\fB\s+4We, the people\s-4\fP 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

Two other in-line escapes are \& and \p The \& escape is a zero-length control character and can be used to enable the printing of a control character (.) at the start of a line The

\p escape generates a break, but also requests that the line be spread to the current input line length

Similarly, if a word requires extra vertical space, the in-line escape \x is used to request the additional vertical space The amount of space needed must be enclosed in single quotes

The next in-line escape deals with unfilled text only If a line of unfilled text is

terminated with a \c, the next text present will be treated as a continuation of that line This allows the document writer to include a sequence of requests in the middle of a line, even if those requests do not have associated in-line escapes The cs request is an

example of a case where \c may be used

Fonts may be changed in-line by using the \f escape Single character font identifiers can

be designated with \fB, but two-character identifiers need a ( to group the letters An example would be \f(HI for a change to Helvetica-Italic Point sizes can similarly be changed with \s Here, two-digit fonts are acceptable Relative changes can be made, too Figure 21.18 shows a case where the words "We the people" are bold and four points larger than surrounding text

Special Characters

Although special characters are system-dependent, there are several special characters that you can expect to have in your system Table 21.4 lists these

ASCII is limited to a small number of printable characters; fortunately, troff provides access to many more characters and symbols needed for mathematics and other

applications A few are escape sequences, but most are two-character escapes Several two-character printing symbols are available, some on the default font, and some on a special font These include Greek characters, mathematical characters, and editing symbols An example of this is the mathematical expressions in Listing 21.13 and Figure 21.19

Figure 21.19 troff output of special characters.

Listing 21.13 In-line character requests for troff

Table 21.4 list the special characters typically available for the standard fonts

Table 21.4 Special characters

Strings and Macros

troff and nroff provide the ability to specify strings that can be used repeatedly The strings can be given one- or two-character identifiers, and those identifiers can be

referenced later Strings can be defined with the ds request The next argument must be the identifier, and the string that follows is assigned to the identifier The as request appends additional text to the string Accessing the string is accomplished with the in-line escape \* Our Constitution provides an example in Listing 21.14 and Figure 21.20

Figure 21.20 troff output with a defined string.

Listing 21.14 troff source defining a string

.ce

.ds us United States

Preamble

.sp

We, the people

of the \*(us, 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

All legislative powers herein granted shall be vested in a

Congress of the \*(us, which shall consist of a Senate and a

Macros are defined with the de request A one- or two-character label should follow the request By convention, macro names are often uppercase, although this is not a

requirement The troff requests then follow the de until the request is present These requests are then executed whenever the macro is called You call the macro by starting the line with a followed by the macro name, without a space

Macros can be designed to take arguments Up to nine arguments can be passed to a macro and are accessed as \$N, where N is the argument position from 1 to 9 These can

be treated as ordinary variables and can be used anywhere in the macro When a macro is

defined, the contents of the commands are interpreted This means that the presence of strings, variables, and comments are translated when the macro is read To insure that the argument is not interpreted until the macro is used, the argument should be listed in the definition as \\$N The \\ will be interpreted as \ This \\ can be used whenever the writer wants the escape to be interpreted when the macro is invoked

Two examples are illustrated in Listing 21.15 and Figure 21.21 The first macro defined,

PP, is used to signal a new paragraph You first request a space, then you temporarily indent the first line by a quarter-inch You also insure that the font is Times Roman The second macro defined is for a header, HD Give it two arguments: the first is the point size desired for the header and the second is the text of the header First request a space, then change the point size to the requested size Next, request that the text be centered and made bold Then issue the text, reset the point size and font, and request an additional space

Figure 21.21 troff output with a defined macro.

Listing 21.15 troff source defining macros

.HD 14 "A sample header"

.PP

We begin the text of the first paragraph here This is indented

and formatted We continue with the text of the first paragraph

until we want the second paragraph

.PP

We re-issue the macro, and get the space and indent

Macros can be changed after creation using the am request This appends troff requests

to the already existing macro, given in the first argument In the preceding example, assume you wanted the second and subsequent paragraphs to have a point size of ten for the text You could do this by including the following commands after the first call to PP: .am PP

.ss 10

You could have redefined the macro with de, but the am request is quicker You can also rename macros with rn This can be used even with standard troff requests and strings The original name is the first argument, and the new name is the second

argument The old name is not retained

Lastly, macros, strings, and other requests can be removed with rm Any subsequent commands to the macro will be ignored

Number Registers

troff provides number registers for the tracking of parameters for troff These can be accessed with the escape sequence \n For single character names, like x, use \nx For multiple character names, like xx, use \n(xx Number registers are used for items such as page numbers and line length The predefined registers include % for page number, dw for the day of the week, dy for the day, mo for the month, and yr for the year nl also shows the position of the last printed line Listing 21.16 shows how some of these

registers can be used Figure 21.22 is the output

Figure 21.22 troff number registers in output.

Listing 21.16 Using number registers

.$ Number of arguments to a macro

.A Set to 1 if -a is used on troff command line; always 1 for nroff

.T Set to 1 if -T is used on nroff command line; always 1 for troff

.a Value of extra space most recently used

.c Number of lines read from current input file

.f Current font

.h Text high water mark for current page

.i Current indent

.l Current line length

.n Length of text on previous output line

.o Current page offset

.p Current page length

.s Current point size

.u Fill more flag (1 for on, 0 for off)

.v Current vertical line spacing

A short script to list default values is shown in Listing 21.17, with Figure 21.23 showing the output

Figure 21.23 troff output with register values.

Listing 21.17 troff source to identify register values

.nf

The current font is \n(.f

The current point size is \n(.s

The line length is \n(.l

The page length is \n(.p

The page offset is \n(.o

Of course, these registers are useful; however, the real benefit of registers comes from the user's ability to define their own registers These can be used to track headers, paragraph numbers, and section numbers The nr request initializes and modifies user-specified registers It takes two or three arguments: the first is the register name, and the second is the register modification When first created, a register is assigned the value of zero A positive number is added to the value; a negative number is subtracted An optional third argument sets a default increment and decrement value The automatic increment can be used in escape sequences: \n+(xx adds the increment to register xx, and \n-(xx subtracts the decrement

The appearance of the number is set with the af request The first argument is the

register, the second is one of six formats 1 is for an Arabic number sequence, 001 is for a zero-filled Arabic number sequence i and I are for Times Roman numbers, upper- and lowercase, and a and A are for alphabetic sequences

Lastly, the rr request removes a number register There are a limited number of registers available, identified by the read-only register R The document writer may need to remove registers if space becomes a problem

Listing 21.18 illustrates the source of a macro that numbers sections of the Constitution The output is in Figure 21.24 The section header macros are for Articles, sections, and paragraphs of the constitution First define the aR number register to count the articles, and set its display format to Times Roman numerals You first define the AR macro It centers a 16-point bold text, with the word "Article" and the number register Note that you increment the number register every time you print the value You also set the sE number register to zero, as an Arabic number You then reset the point size and font The

SE macro is similar, printing the section and number, and setting pP to zero The PP macro increments pP

Figure 21.24 troff output with number registers.

Listing 21.18 troff source using number registers

.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

All legislative powers herein granted shall be vested in a

Congress of the United States, which shall consist of a Senate and a House of Representatives

.SE

House of Representatives, how and by whom chosen, Qualifications

of a Representative Representatives and direct taxes, how

apportioned Enumeration Vacancies to be filled Power of

choosing officers and of impeachment

.PP

The House of Representatives shall be composed of members chosen every second year by the people of the several states, and the electors in each State shall have the qualifications requisite for electors of the most numerous branch of the State Legislature .PP

No person shall be a Representative who shall not have attained

to the age of twenty-five years, and been seven years a citizen

of the United States, and who shall not, when elected, be an

inhabitant of that State in which he shall be chosen

to the whole number of free persons, including those bound for

service for a term of years, and excluding Indians not taxed,

three-fifths of all other persons The actual enumeration shall

be made within three years after the first meeting of the

Congress of the United States, and within every subsequent term

of ten years, in such manner as they shall by law direct The

number of Representatives shall not exceed one for every thirty

thousand, but each State shall have at least one Representative;

and until such enumeration shall be made, the State of New

Hampshire shall be entitled to choose three, Massachusetts eight, Rhode Island and Providence Plantations one, Connecticut

five, New York six, New Jersey four, Pennsylvania eight,

Delaware one, Maryland six, Virginia ten, North Carolina five,

South Carolina five, and Georgia three

.PP

When vacancies happen in the representation from any State, the

Executive Authority thereof shall issue writs of election to fill such vacancies

.PP

The House of Representatives shall choose their Speaker and other officers; and shall have the sole power of impeachment

Traps and Diversions

So far, I have examined the results of invoking troff requests where you place them in your document These are not the only examples of executing troff requests You can specify macros to be executed at any given physical position on a document These are called traps, and they can be triggered by page position, diversions, and input line count

A common use for page traps is to place headers or footers on pages Diversion traps can

be used to create footnotes in text, or to create a reference list for the end of a chapter Input line traps count the number of lines since the request These are useful for when macros are meant to be a single line

Diversions are used to direct output to a macro, instead of to the page The diversion requests are usually in macros, and traps must be set to produce the diversion output Diversions are created with the di request, the call followed by the name of the diversion macro If no argument is present, the diversion ends, and output resumes on the page Text can be added to the diversion with the da request Diversions can also be requested

by page position with dt, followed by the position and diversion macro name

Traps are set with the wh request This is followed by a position and a macro name If a macro had previously been set at that position, then that trap is removed If no macro is passed as an argument, then any traps at that position are removed The position of a macro trap can be changed with the ch request, followed by the macro name and

position If a position is missing, the macro is removed Input traps are set with the it request, followed by a text position and macro name Finally, a trailing macro can be set with em This sets a macro to be run at the end of input

The use of diversions and traps is illustrated in Chapter 26, "Writing Your Own Macros."

Tabs, Character Conversions, and Controls

Tabs and tab spacing can be set by the document writer in troff This gives the writer the ability to create simple tables by lining up columns and using tabs The ta request sets the tab stops, and if a stop value is preceded by a +, then the stop is relative to the

previous tab stop The tab repetition character (the character that fills the space between text and tab stops) can be specified with the tc request The nature of the tab stop can also be specified right after the tab stop distance The text left-adjusts within the tab space

by default To center the text, use a C after the distance (no space), and use an R to adjust

right-A simple table is illustrated in Listing 21.19, with the output in Figure 21.25

Figure 21.25 A formatted table with tabs.

Listing 21.19 Formatting a table using tabs

.tc -

Bob Williams 3/3/56 (999) 555-2222

Some characters are considered control characters These are the used to signal a troff request, \ to indicate an in-line escape, and ' to indicate a breakless command The escape character can be reset with the ec request and can be turned off with the eo request .ec takes an argument, which is the new escape character If no argument is present, it returns

to the default The cc request changes the basic control character, , to whatever is

specified This is particularly useful if a writer wishes to show a sample of troff input in a document, as shown in Listing 21.20 and Figure 21.26 Finally, c2 changes the no-break control character from ' to the specified argument

Figure 21.26 troff output with character translations.

Underlining in nroff and italics in troff can also be invoked with the ul and cu requests This turns on underline mode In troff, the two requests have an identical effect; in nroff, cu is for continuous underlining, and ul underlines characters The underlining font can

be changed with the uf request

Character translations are also possible with troff The tr request is analogous to the tr UNIX command Instead of two groups of characters, though, the from-to pairs of

characters are side by side in a single character string argument This is also illustrated in Listing 21.20 and Figure 21.26

Listing 21.20 troff source illustrating character translations

.nf

A sample of troff input:

.sp

.cc ,

Local Motions

Besides the sp and related requests, there are in-line techniques to move the current output location in troff These are called local motions and can be vertical or horizontal There are four types of vertical motions All are in-line escapes The first, \r, moves up single line \d is used to move down half a line, for subscripts, and \u is used to move up half a line, for superscripts Finally, \v'N' is used to make a local motion of vertical distance N A negative number moves up the page, and a positive number moves down the page You cannot leave the page with a local motion An example is in Listing 21.21, with output in Figure 21.27

Figure 21.27 troff output with local motions.