Writing man Pages Using groff
Two of the original text processing systems found on Unix systems are troff and nroff, developed at Bell Labs for the original implementation of Unix (in fact, the development of Unix itself was spurred, in part, to support such a text-processing system). The first version of this text processor was called roff (for “runoff”); later came troff, which generated output for a particular typesetter in use at the time. nroff was a later version that became the standard text processor on Unix systems everywhere. groff is GNU's implementation of nroff and troff that is used on Linux systems. It includes several extended features and drivers for a number of printing devices.
groff is capable of producing documents, articles, and books, much in the same vein as other text-formatting systems, such as TeX. However, groff (as well as the original nroff) has one intrinsic feature that is absent from TeX and variants: the ability to produce plain-ASCII output. While other systems are great for producing documents to be printed, groff is able to produce plain ASCII to be viewed online (or printed directly as plain text on even the simplest of printers). If you're going to be producing documentation to be viewed online, as well as in printed form, groff may be the way to go (although there are alternatives, such as Texinfo, Lametex, and other tools).
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 man pages. If you're a Unix programmer, you'll eventually need to write and produce man pages of some kind. In this article, we'll introduce the use of groff through the writing of a short man 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 systems such as TeX, but also less verbose. In addition, groff provides several macro packages that are used on top of the basic 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, while the man macros are used for man pages.
Writing man pages with groff is actually quite simple. For your man page to look like others, you need to follow several conventions in the source, which are presented below. In this example, we'll write a man page for a mythical command coffee that controls your networked coffee machine in various ways.
Using any text editor, enter the source from Listing 1 and save the result as coffee.man. Do not enter the line numbers at the beginning of each line; those are used only for reference later in the article.
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 ] 6: /fIamount/fP 7: .SH DESCRIPTION 8: /fBcoffee/fP queues a request to the remote 9: coffee machine at the device /fB/dev/cf0/fR. 10: The required /fIamount/fP argument specifies 11: the number of cups, generally between 0 and 12: 12 on ISO standard coffee machines. 13: .SS Options 14: .TP 15: /fB-h/fP 16: Brew hot coffee. Cold is the default. 17: .TP 18: /fB-b/fP 19: Burn coffee. Especially useful when executing 20: /fBcoffee/fP on behalf of your boss. 21: .TP 22: /fB-t /fItype/fR 23: Specify the type of coffee to brew, where 24: /fItype/fP is one of /fBcolumbian/fP, 25: /fBregular/fP, or /fBdecaf/fP. 26: .SH FILES 27: .TP 28: /fC/dev/cf0/fR 29: The remote coffee machine device 30: .SH "SEE ALSO" 31: milk(5), sugar(5) 32: .SH BUGS 33: May require human intervention if coffee 34: supply is exhausted.
Listing 1. Example man Page Source File
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 sets 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 is used to set the title of the man page to COFFEE, the man section to 1, and the date of the last man page revision. (Recall that man section 1 is used for user commands, section 2 is for system calls, and so forth. The man man command details each section number.) On line 2, the .SH request is used to start a section, entitled NAME. Note that almost all Unix man 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 man 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 ([mi]). You should use this format for the NAME section so that your man page can be added to the whatis database used by the man -k and apropos commands.
On lines 4—6 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, and that optional arguments are enclosed in square brackets.
Lines 7—12 give a brief description of the command. Boldface type is generally used to denote program and file names. On line 13, a subsection named Options is started with the .SS request. Following this on lines 14—25 is a list of options, presented using a tagged list. Each item in the tagged list is marked with the .TP request; the line after .TP is the tag, after which follows the item text itself. For example, the source on lines 14—16:
.TP \fB-h\P Brew hot coffee. Cold is the default.
will appear as the following in the output:
-h Brew hot coffee. Cold is the default.
You should document each command-line option for your program in this way.
Lines 26—29 make up the FILES section of the man page, which describes any files that the command might use to do its work. A tagged list using the .TP request is used for this as well.
On lines 30—31, the SEE ALSO section is given, which provides cross-references to other man pages of note. Notice that the string <\#34>SEE ALSO<\#34> following the .SH request on line 30 is in quotes; this is because .SH uses the first whitespace-delimited argument as the section title. Therefore any section titles that are more than one word need to be enclosed in quotes to make up a single argument. Finally, on lines 32—34, the BUGS section is presented.
|Dynamic DNS—an Object Lesson in Problem Solving||May 21, 2013|
|Using Salt Stack and Vagrant for Drupal Development||May 20, 2013|
|Making Linux and Android Get Along (It's Not as Hard as It Sounds)||May 16, 2013|
|Drupal Is a Framework: Why Everyone Needs to Understand This||May 15, 2013|
|Home, My Backup Data Center||May 13, 2013|
|Non-Linux FOSS: Seashore||May 10, 2013|
- RSS Feeds
- Making Linux and Android Get Along (It's Not as Hard as It Sounds)
- Using Salt Stack and Vagrant for Drupal Development
- Dynamic DNS—an Object Lesson in Problem Solving
- New Products
- Validate an E-Mail Address with PHP, the Right Way
- Drupal Is a Framework: Why Everyone Needs to Understand This
- A Topic for Discussion - Open Source Feature-Richness?
- Download the Free Red Hat White Paper "Using an Open Source Framework to Catch the Bad Guy"
- Tech Tip: Really Simple HTTP Server with Python
- Roll your own dynamic dns
4 hours 45 min ago
- Please correct the URL for Salt Stack's web site
7 hours 57 min ago
- Android is Linux -- why no better inter-operation
10 hours 12 min ago
- Connecting Android device to desktop Linux via USB
10 hours 41 min ago
- Find new cell phone and tablet pc
11 hours 39 min ago
13 hours 8 min ago
- Automatically updating Guest Additions
14 hours 16 min ago
- I like your topic on android
15 hours 3 min ago
- This is the easiest tutorial
21 hours 38 min ago
- Ahh, the Koolaid.
1 day 3 hours ago
Enter to Win an Adafruit Pi Cobbler Breakout Kit for Raspberry Pi
It's Raspberry Pi month at Linux Journal. Each week in May, Adafruit will be giving away a Pi-related prize to a lucky, randomly drawn LJ reader. Winners will be announced weekly.
Fill out the fields below to enter to win this week's prize-- a Pi Cobbler Breakout Kit for Raspberry Pi.
Congratulations to our winners so far:
- 5-8-13, Pi Starter Pack: Jack Davis
- 5-15-13, Pi Model B 512MB RAM: Patrick Dunn
- 5-21-13, Prototyping Pi Plate Kit: Philip Kirby
- Next winner announced on 5-27-13!
Free Webinar: Hadoop
How to Build an Optimal Hadoop Cluster to Store and Maintain Unlimited Amounts of Data Using Microservers
Realizing the promise of Apache® Hadoop® requires the effective deployment of compute, memory, storage and networking to achieve optimal results. With its flexibility and multitude of options, it is easy to over or under provision the server infrastructure, resulting in poor performance and high TCO. Join us for an in depth, technical discussion with industry experts from leading Hadoop and server companies who will provide insights into the key considerations for designing and deploying an optimal Hadoop cluster.
Some of key questions to be discussed are:
- What is the “typical” Hadoop cluster and what should be installed on the different machine types?
- Why should you consider the typical workload patterns when making your hardware decisions?
- Are all microservers created equal for Hadoop deployments?
- How do I plan for expansion if I require more compute, memory, storage or networking?