5
<TITLE>Red Hat Linux Unleashed rhl17.htm </TITLE>
7
<LINK REL="ToC" HREF="index.html">
9
<LINK REL="Index" HREF="htindex.html">
11
<LINK REL="Next" HREF="rhl18.htm">
13
<LINK REL="Previous" HREF="rhl16.htm"></HEAD>
15
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080">
19
<H2>Red Hat Linux Unleashed rhl17.htm</H2>
23
<A HREF="rhl16.htm" TARGET="_self"><IMG SRC="purprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
25
<A HREF="index.html" TARGET="_self"><IMG SRC="purtoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
27
<A HREF="rhl18.htm" TARGET="_self"><IMG SRC="purnext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
42
<A HREF="#E68E119" >Embedding Commands</A>
46
<A HREF="#E68E120" >Controlling Character Appearance</A>
52
<A HREF="#E69E235" >Sizes and Line Spacing</A>
56
<A HREF="#E69E236" >Fonts</A>
60
<A HREF="#E69E237" >Indenting and Line Length</A>
64
<A HREF="#E69E238" >Other Character Controls</A></UL>
68
<A HREF="#E68E121" >Macros</A>
72
<A HREF="#E68E122" >Using mm</A>
78
<A HREF="#E69E239" >Lists</A>
82
<A HREF="#E69E240" >Font Changes</A>
86
<A HREF="#E69E241" >Footnotes</A></UL>
90
<A HREF="#E68E123" >Summary</A></UL></UL></UL>
100
<FONT SIZE=6 COLOR="#FF0000"><B>17</B></FONT></CENTER></H1>
104
<A NAME="E67E17"></A>
110
<FONT SIZE=6 COLOR="#FF0000"><B>groff</B></FONT></CENTER></H2>
114
<P>This chapter looks at the groff text-formatting utility. Specifically, you will learn the following:
126
<LI>How to do basic text formatting
132
<LI>How to create macros
138
<LI>What the mm macro package is
146
<P>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
147
used primarily to compile man pages written and stored in groff/nroff format into a form that can be printed or displayed on-screen.
151
<P>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
152
by nroff. In most cases, you don't use nroff or troff directly, but use a macro package to access them.
156
<P>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.
160
<P>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
161
applications. If you really want to use groff for advanced text formatting, you should pick up a dedicated book on the subject.
167
<A NAME="E68E119"></A>
173
<FONT SIZE=5 COLOR="#FF0000"><B>Embedding Commands</B></FONT></CENTER></H3>
177
<P>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,
184
<FONT COLOR="#000080">This is fine stuff.
186
It is really interesting and
188
could keep me busy for hours.</FONT></PRE>
190
<P>covers three lines in the source, but when formatted, it's run together by groff to look like this:
198
<FONT COLOR="#000080">This is fine stuff. It is really interesting and could keep me busy for hours.</FONT></PRE>
200
<P>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
201
the output will look like until you see it!
205
<P>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:
211
<FONT COLOR="#000080">This is a bunch of text that will be displayed.
213
Here is even more text.
217
The line above is a groff command, identified by the
219
period in the first column of the line.</FONT></PRE>
221
<P>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
230
<FONT COLOR="#000080">This \fBline\fR has two embedded \fIgroff\fR commands.</FONT></PRE>
232
<P>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.
238
<A NAME="E68E120"></A>
244
<FONT SIZE=5 COLOR="#FF0000"><B>Controlling Character Appearance</B></FONT></CENTER></H3>
248
<P>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.
254
<A NAME="E69E235"></A>
260
<FONT SIZE=4 COLOR="#FF0000"><B>Sizes and Line Spacing</B></FONT></CENTER></H4>
264
<P>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:
270
<FONT COLOR="#000080">This is the default 10-point size.
274
This is now in 14-point size.
278
This is a point size of 20.
282
And this is a really small point size of six.</FONT></PRE>
292
<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,
293
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.</NOTE>
299
</BLOCKQUOTE></BLOCKQUOTE>
301
<P>Within a sentence, the point size can be changed with the line-embedded command \s followed by the point size. For example:
309
<FONT COLOR="#000080">This is in 10-point, while \s20this is in 20,\s10 and back to 10 again.</FONT></PRE>
311
<P>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
312
specified (so you can't change by more than nine points).
316
<P>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.
321
<P>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:
327
<FONT COLOR="#000080">This is in normal 10-point, 11 vertical space size.
333
This is in 12-point with 14 vertical spacing.</FONT></PRE>
335
<P>If you use the .vs command without a value, groff reverts to the previous value.
339
<P>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:
345
<FONT COLOR="#000080">This is default 10-point 11 vertical spaced text.
349
We have a blank line above this because of the command.
353
This is three and a half inches below the previous line.</FONT></PRE>
355
<P>You can use fractions in most groff commands, as this example shows.
361
<A NAME="E69E236"></A>
367
<FONT SIZE=4 COLOR="#FF0000"><B>Fonts</B></FONT></CENTER></H4>
371
<P>Changing fonts requires the command .ft (font type). In the early days of troff, only four fonts were supported: Roman, Roman bold, Roman italic, and a set of special characters. Other fonts had to be specially loaded in the phototypesetter. For this
372
reason, groff defaults to Roman.
376
<P>To switch to Roman bold, you use the command .ft B, while .ft I switches, not surprisingly, to Roman italic. To return to the normal Roman font, the command .ft R is used, although on most systems, .ft by itself will suffice:
382
<FONT COLOR="#000080">This is in normal Roman font.
394
This is back to normal Roman font.</FONT></PRE>
396
<P>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:
400
<P>This is normal, \fBbold\fR and \fIitalics\fR.
404
<P>Because underline wasn't supported on most system printers, underlined text was converted to italic. The underline command .ux would italicize the next x lines of text.
408
<P>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
409
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
417
<FONT COLOR="#000080">.fp 3 H</FONT></PRE>
419
<P>would instruct the phototypesetter to switch to Helvetica in font position three. groff still retains these old-style commands.
425
<A NAME="E69E237"></A>
431
<FONT SIZE=4 COLOR="#FF0000"><B>Indenting and Line Length</B></FONT></CENTER></H4>
435
<P>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
443
<FONT COLOR="#000080">.ll 7i</FONT></PRE>
445
<P>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
446
left margin as far over as is possible.
450
<P>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:
454
<P>This is normal stuff.
462
<FONT COLOR="#000080">.in 0.75I</FONT></PRE>
464
<P>This is indented three-quarters of an inch.
468
<P>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:
472
<P>This is normal text, and goes on and on.Even more text that continues the tradition.
478
<FONT COLOR="#000080">.in 1i
482
<P>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.
488
<FONT COLOR="#000080">.in -1i
492
<P>And this is back to normal. The block will stand out nicely amongst all this normal text.
496
<P>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.
500
<P>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:
504
<P>This is really fine stuff. You can tell, 'cause I'm still awake.
510
<FONT COLOR="#000080">.ti 3i</FONT></PRE>
512
<P>This line is temporarily indented by three inches, but the next line will be back to normal.
516
<P>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
525
<FONT COLOR="#000080">.ta 1i 2i 3i 4i 5i 6i</FONT></PRE>
527
<P>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.
528
(You get a look at gtbl in the next chapter.)
534
<A NAME="E69E238"></A>
540
<FONT SIZE=4 COLOR="#FF0000"><B>Other Character Controls</B></FONT></CENTER></H4>
544
<P>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 it is unlikely that groff is used for this type of output these days, we'll
545
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.
551
<A NAME="E68E121"></A>
557
<FONT SIZE=5 COLOR="#FF0000"><B>Macros</B></FONT></CENTER></H3>
561
<P>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
562
an inch. The groff commands to do this are
568
<FONT COLOR="#000080">.sp
570
.ti +.5i</FONT></PRE>
572
<P>Instead of typing these two lines every paragraph, we can define a macro of one character (or more) that does it for us.
576
<P>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:
582
<FONT COLOR="#000080">.de PP
590
<P>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.
602
<NOTE>Make sure that you don't define a macro with the name of a reserved groff command, or the macro will not be executed.</NOTE>
608
</BLOCKQUOTE></BLOCKQUOTE>
612
<A NAME="E68E122"></A>
618
<FONT SIZE=5 COLOR="#FF0000"><B>Using mm</B></FONT></CENTER></H3>
622
<P>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
623
the nroff and troff commands too awkward or complicated, whereas mm is fully able to meet all their basic formatting needs.
627
<P>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.
631
<P>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
636
<P>Headings are created with the .H command. For example, the command
640
<P>.H This is a Heading
644
<P>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.
648
<P>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:
652
<P>.H 2 This is a level 2 heading
656
<P>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
657
the heading level and the number to use. For example, the command
665
<FONT COLOR="#000080">.nr H2 1</FONT></PRE>
667
<P>will restart the numbering of second-level headings at 1.
673
<A NAME="E69E239"></A>
679
<FONT SIZE=4 COLOR="#FF0000"><B>Lists</B></FONT></CENTER></H4>
683
<P>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
689
<FONT COLOR="#000080">.LI
701
<P>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.
705
<P>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)
706
can be used with the .AL I command.
710
<P>You can nest list types as necessary. For example, the command
716
<FONT COLOR="#000080">.AL I
744
<P>will create output that looks like this:
750
<FONT COLOR="#000080">I. groff
758
III. geqn</FONT></PRE>
760
<P>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!
766
<A NAME="E69E240"></A>
772
<FONT SIZE=4 COLOR="#FF0000"><B>Font Changes</B></FONT></CENTER></H4>
776
<P>Changing fonts with mm is quite simple. When working from a period command, the command .B (bold) creates bold text until an .R (restore) command, while .I (italic) does the same until an .R command. If you want to bold or italicize only one word, you
777
can do it after the period command, as this example shows:
781
<P>This is normal text
789
<FONT COLOR="#000080">.B</FONT></PRE>
803
<FONT COLOR="#000080">.R</FONT></PRE>
815
<FONT COLOR="#000080">.Bbold</FONT></PRE>
821
<P>When you change only one word, you don't need a .R command.
825
<P>Changes can be performed within text in the same manner as with groff:
833
<FONT COLOR="#000080">This is an \fIitalics set of words\fR until here.</FONT></PRE>
837
<A NAME="E69E241"></A>
843
<FONT SIZE=4 COLOR="#FF0000"><B>Footnotes</B></FONT></CENTER></H4>
847
<P>To create a footnote, use the .FS (footnote start) and .FE (footnote end) commands. Every footnote on a single page will be collected and printed at the bottom. Footnotes are automatically numbered unless you specify another character:
853
<FONT COLOR="#000080">This is normal text.
857
<P>This is a footnote with its proper number in front of it.
863
<FONT COLOR="#000080">.FE
865
This is more normal text.
869
<P>But this is a footnote marked with an asterisk.
877
<FONT COLOR="#000080">.FE</FONT></PRE>
879
<P>This is even more normal text. At the bottom of the page
883
<P>will be a numbered footnote and an asterisked footnote.
887
<P>You can use any valid character for the optional footnote mark, including special characters supported by groff.
893
<A NAME="E68E123"></A>
899
<FONT SIZE=5 COLOR="#FF0000"><B>Summary</B></FONT></CENTER></H3>
903
<P>As you might expect, there is a lot to both groff and mm that we haven't looked at. Because groff is seldom used these days, we covered only the most important aspects. As I said earlier, if you want to learn more about groff or mm, find a good
904
reference book on the subject.
908
<A HREF="rhl16.htm" TARGET="_self"><IMG SRC="purprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
910
<A HREF="#I0" TARGET="_self"><IMG SRC="purtop.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Page Top"></A>
912
<A HREF="index.html" TARGET="_self"><IMG SRC="purtoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
914
<A HREF="rhl18.htm" TARGET="_self"><IMG SRC="purnext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
added
removed
Document/groff/rhl17.htm
