Writing man Pages Using groff

 in
groff is the GNU version of the popular nroff/troff text-formatting tools provided on most Unix systems. Its most common use is writing manual pages—online documentation for commands, programming interfaqces, and so forth. In this article, we show you the ropes of writing your own man pages with groff.
Formatting and Installing the man Page

In order to format this man page and view it on your screen, you can use the command:

$ groff -Tascii -man coffee.man | more

The -Tascii option tells groff to produce plain-ASCII output; -man tells groff to use the man page macro set. If all goes well, the man page should be displayed as shown in Figure 1.

COFFEE(1)                                               COFFEE(1)
NAME
       coffee - Control remote coffee machine
SYNOPSIS
       coffee [ -h | -b ] [ -t type ] amount
DESCRIPTION
       coffee  queues  a  request to the remote coffee machine at
       the device /dev/cf0. The required amount  argument  speci-
       fies the number of cups, generally between 0 and 12 on ISO
       standard coffee machines.
   Options
       -h     Brew hot coffee. Cold is the default.
       -b     Burn coffee. Especially useful when executing  cof-
              fee on behalf of your boss.
       -t type
              Specify  the  type of coffee to brew, where type is
              one of columbian, regular, or decaf.
FILES
       /dev/cf0
              The remote coffee machine device
SEE ALSO
       milk(5), sugar(5)
BUGS
       May  require  human  intervention  if  coffee  supply   is
       exhausted.

Figure 1. Formatted man Page

As mentioned before, groff is capable of producing other types of output. Using the -Tps option in place of -Tascii will produce PostScript output that you can save to a file, view with GhostView, or print on a PostScript printer. -Tdvi will produce device-independent .dvi output similar to that produced by TeX.

If you wish to make the man page available for others to view on your system, you need to install the groff source in a directory that is present in other users' MANPATH. The location for standard man pages is /usr/man. The source for section 1 man pages should therefore go in /usr/man/man1. Therefore, the command:

$ cp coffee.man /usr/man/man1/coffee.1

will install this man page in /usr/man for all to use (note the use of the .1 file name extension, instead of .man). When man coffee is subsequently invoked, the man page will be automatically reformatted, and the viewable text saved in /usr/man/cat1/coffee.1.Z.

If you can't copy man page sources directly to /usr/man (say, because you're not the system administrator), you can create your own man page directory tree and add it to your MANPATH. The MANPATH environment variable is of the same format as PATH; for example, to add the directory /home/mdw/man to MANPATH just use:

$ export MANPATH=/home/mdw/man:$MANPATH

There are many other options and formatting commands available for groff and the man page macros. The best way to find out about these is to look at the files in /usr/lib/groff; the tmac directory contains the macro files themselves, which often contain some documentation on the commands they provide. To use a particular macro set with groff, just use the -mmacro option. For example, to use the mgs macros, use:

groff -Tascii -mgs files...

The man pages for groff describe this option in more detail.

Unfortunately, the macro sets provided with groff are not well-documented. There are section 7 man pages for some of them; for example, man 7 groff_mm will tell you about the mm macro set. However, this documentation usually only covers the differences and new features in the groff implementation, which assumes you have access to the man pages for the original nroff/troff macro sets (known as DWB—the Documentor's Work Bench). The best source of information may be a book on using nroff/troff which covers these classic macro sets in detail. For more about writing man pages, you can always look at the man page sources (in /usr/man) and determine what they do by comparing the formatted output with the source.

This article is adapted from Running Linux, by Matt Welsh and Lar Kaufman, published by O'Reilly and Associates (ISBN 1-56592-100-3). Among other things, this book includes tutorials of various text-formatting systems used under Linux. Information in this issue of Linux Journal as well as Running Linux should provide a good head-start on using the many text tools available for the system.

Good luck, and happy documenting!

Matt Welsh (mdw@cs.cornell.edu) is a student and systems programmer at Cornell University, working with the Robotics and Vision Laboratory on projects dealing with real-time machine vision.

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Wonderful article

Anonymous's picture

Wonderful article

Thanks

Mike Strom 's picture

Thanks for a nice tutorial, just finished my first man page :)

Noticed that in the listing all backslashes (i.e. \fB) shows up like forward slashed (/fB). Maybe it's my browser?

Thanks,
Mike

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState