• Choose a category
• All
• Classic-Fiction

groff also has the benefit of being much smaller than TEX; it requires fewer support files and executables than even a minimal TEX distribution.

One special application of groff is to format Unix manual pages. If you're a Unix programmer, you'll eventually need to write and produce manual pages of some kind. In this section, we introduce the use of groff through the writing of a short manual page.

As with TEX, groff uses a particular text-formatting language to describe how to process the text. This language is slightly more cryptic than TEX but is also less verbose. In addition, groff provides several macro packages that are used on top of the basic groff formatter; these macro packages are tailored to a particular type of document. For example, the mgs macros are an ideal choice for writing articles and papers, and the man macros are used for manual pages.

Writing a Manual Page

Writing manual pages with groff is actually quite simple. In order for your manual page to look like other manual pages, you need to follow several conventions in the source, which are presented in the following example. In this example, we write a manual page for a mythical command coffee, which controls your networked coffee machine in various ways.

Enter the following source with your text editor, and save the result as coffee.man:

1 .TH COFFEE 1 "23 March 94"

2 .SH NAME

3 coffee \- Control remote coffee machine

4 .SH SYNOPSIS

5 \fBcoffee\fP [ -h | -b ] [ -t \fItype\fP ] \fIamount\fP

6 .SH DESCRIPTION

7 \fIcoffee\fP queues a request to the remote coffee machine at the

8 device \fB/dev/cf0\fR. The required \fIamount\fP argument specifies

9 the number of cups, generally between 0 and 15 on ISO standard

10 coffee machines.

11 .SS Options

12 .TP

13 \fB-h\fP

14 Brew hot coffee. Cold is the default.

15 .TP

16 \fB-b\fP

17 Burn coffee. Especially useful when executing \fIcoffee\fP on behalf

18 of your boss.

19 .TP

20 \fB-t \fItype\fR

21 Specify the type of coffee to brew, where \fItype\fP is one of

22 \fBcolombian\fP, \fBregular\fP, or \fBdecaf\fP.

23 .SH FILES

24 .TP

25 \fI/dev/cf0\fR

26 The remote coffee machine device

27 .SH "SEE ALSO"

28 milk(5), sugar(5)

29 .SH BUGS

30 May require human intervention if coffee supply is exhausted.

Don't let the amount of obscurity in this source file frighten you. It helps to know that the character sequences \fB, \fI, and \fR are used to change the font to boldface, italics, and roman type, respectively. \fP resets the font to the one previously selected.

Other groff requests appear on lines beginning with a dot (.). On line 1, we see that the .TH request sets the title of the manual page to COFFEE and the manual section to 1. (Manual section 1 is used for user commands, section 2 for system calls, and so forth.) The .TH request also sets the date of the last manual page revision.

On line 2, the .SH request starts a section entitled NAME. Note that almost all Unix manual pages use the section progression NAME, SYNOPSIS, DESCRIPTION, FILES, SEE ALSO, NOTES, AUTHOR, and BUGS, with extra optional sections as needed. This is just a convention used when writing manual pages and isn't enforced by the software at all.

Line 3 gives the name of the command and a short description, after a dash (\-). You should use this format for the NAME section so that your manual page can be added to the whatis database used by the man -k and apropos commands.

On lines 4 to 5, we give the synopsis of the command syntax for coffee. Note that italic type (\fI...\fP) is used to denote parameters on the command line in the manual page, and that optional arguments are enclosed in square brackets.

Lines 6 to 10 give a brief description of the command. Italic type generally denotes commands, filenames, and user options. On line 11, a subsection named Options is started with the .SS request. Following this on lines 11 to 22 is a list of options, presented using a tagged list. Each item in the tagged list is marked with the