WRITING MAN PAGES
 
 
This is a preliminary draft. Changes will occour till it's final release. At least, it's not finished yet.
 
Every programmer in the X world some time arrives at this crossroad: creating a man page for his just-finished utility/widget/killer application, so users can get up-to-date information online. But many programmers try to avoid this nasty procedure. Or to cite W. Shakesbeare (this is not a beer brewer, but rather an english playwrighter): To write, or not to write

To help you somewhat in this daunting task, I've created this "instructions guide". It describes the necessary steps to roll your own man pages with ease. In addition it shows some nice macros to make life more easy. 
 
OVERVIEW
 

 
STEP 1: What Do I Need?

You need the nroff/troff formatting package either from your hardware's vendor or from the GNU foundation. GNU's troff variant is called gtroff and comes together with a front-end to gtroff and other preprocessors like gtbl (for setting tables). In the following I'll refer to groff only but using nroff or troff instead should be straightforward. 

The man command often uses preformatted man pages as created by troff/groff. Depending on your platform's configuration man can also display unformatted (raw) man pages by processing them first with troff/groff. 

The raw man page is simply a plain ASCII file with interspearsed commands for the formatting package. Thus you can use whatever editor you want to create the source file from which groff creates the man page - even vi (although emacs is even more cryptic). With groff, to ease writing you can define new macros. In fact, the whole process relies heavily on macro packages which already come with troff/groff. You can specify the necessary macro package(s) when invoking groff. Such packages are then read in by troff before processing of your man page file begins. 

Running groff is a simple task: 

 $ groff -t -man -Tascii MyFile > MyManPage
MyFile is the name of the file containing the raw man page. 

MyManPage is a name suitable to be used with man on your platform. On some platforms you have to run pack or gzip on the resulting man page file. With some systems you have to add the section number to MyManPage

The option -t first runs gtbl, a preprocessor for setting tables. With man pages, you will often need to do this. The next option -man load the appropiate macro package for authoring man pages. And finaly -Tascii prepares output for use with man

But now some examples to clearify this. In every case I assume that you have your own private man page directories. If not, you can easily create them. The following shell commands (assuming the bourne shell) will do the job (for preformatted man pages): 

 $ cd
 $ mkdir man
 $ mkdir man/cat3
 $ MANPATH=`pwd`/man:$MANPATH
 $ export MANPATH
But now the examples: 
  • IRIX 4.0.x or 5.2.x (Silicon Graphics):
  •  $ groff -t -man -Tascii XmComboBox.groff > XmComboBox
     $ pack -f XmComboBox
     $ cp XmComboBox.z ~/man/cat3/XmComboBox.z
  • LINUX:
  •  $ groff -t -man -Tascii XmComboBox.groff > XmComboBox.3X
     $ gzip -f XmComboBox.3X
     $ cp XmComboBox.3X.gz ~/man/cat3/XmComboBox.3X.gz
 
STEP 2: The Title: Identifying the Page

The first macro command I'll introduce is called .TH. With groff documents a macro's name must always be given on the first column of a line. If you put by error a space in the first column, groff will not notice the command and put the command's name verbatim into the resulting man page. 

The .TH macro expects up to five parameters: 

.TH name chapter comment left center 

name is a string to be displayed in the header of every page. It is printed to the left side as well as on the right side of the header. If name contains more than one word, you must enclose them in quotation mark.
chapter is the chapter's name: examples may be "3X" for Xlib or Xt functions, "3Xm" for Motif functions.
comment appears in the center of the footer together with the page number. Normally this contains the man page's creation date (or the release date).
left is printed on the left portion of the page footer. This argument should specify a software package's version number.
center appears in the center portion of the page header.
An example (on one line without the backslash): 
 .TH XmComboBox 3Xm "19 October 1994" "Version 1.30" \
    "Harry's Motif Tools"
STEP 3: Sections, Sections, Sections, ...

When browsing through the man pages you may have already noticed different section names like SYNOPSIS, DESCRIPTION, and SEE ALSO. The section names are printed to the left of the page whereas the text following the section's title is indented to the right. To create a section title, use the .SH macro. The text following .SH on the same line will be printed in another type face (often bold on ttys). Other text from the next line on gets indented to the right and is typed with a Roman font. 

The first section has always to be entitled NAME. The text following in this section should only span across a single line and contain no text manipulation like changing the font. This is for the permuted index generator (for use with apropos) who gets confused if there is anything in the line other than plain text. 

 .SH NAME
 bogous \- a special compiler for use with bogous source files
Note the "\-" in this example. groff regards a simple "-" as a hyphen. But we actually want an en-dash here, that's why you have to use "\-" instead of "-". 

It's completely up to you how to name the remaining sections. If you need more examples, I advise you to look at all the man pages comming with your U**X operating system. 

The sceletton of a man page would look like this: 

 .\" This is a comment line.
 .TH Bogous 42X "1 Apr 2001" "V0.99zeta" "Bogous Software Group"
 .SH NAME
 bogous \- a special compiler for use with bogous source files
 .SH SYNOPSIS
 Some text...
 .SH DESCRIPTION
 At least a rough description...
 .SH BUGS
 To numerous to count...
STEP 4: Paragraphs

There are several predefined ways to lay out text in paragraphs. Most common you'll use either the .LP or .PP command. These commands simply achive the same result: they begin a fresh paragraph and indent it 0.5 inch to the right (measured relative to the page's left border). The same indent is set automatically by the .SH command for the first paragraph following a section. Neither .LP nor .PP takes any parameter, thus you have to type the text of the following paragraph starting with a fresh line. 

 .SH DESCRIPTION
 This is the first paragraph of the description. It
 spans over several lines and just takes up space. It simply
 makes no sense.
 .LP
 This is the second paragraph.
results in: 
DESCRIPTION
This is the first paragraph of the description. It spans over several lines and just takes up space. It simply makes no sense.

This is the second paragraph.

From time to time you need to indent paragraphs further. This can be done using .RS (start of relative indent) and .RE (end of relative indent). If you don't specify an argument to .RS all following paragraphs are indented .5 inch relative to the current paragraph's left indent. 
 .SH DESCRIPTION
 My first paragraph (indent = 0.5 inch).
 .RS
 This is the second paragraph (indented 1 inch to the right).
 .RE
 Third paragraph.
DESCRIPTION
My first paragraph (indent = 0.5 inch).
This is the second paragraph (indented 1 inch to the right).
Third paragraph.
 
STEP 5: Fonts, Fonts, Fonts, ...

Using plain ASCII isn't always just enough. In your man page you surely need to emphasize some words or sentences. The man page macro package provides for this: 

.B
Prints all the text on the same line as the .B command in bold face. Text on the next line appears using the default (Roman) font.

.I 
Prints the remaining text on the same line using an italic font.
.U
Underlines the following text.
 This text is printed with a
 .B bold font
 . Now this is printed using a normal font.
produces: 
This text is printed with a bold font . Now this is printed using a normal font.
If you look close enough at the result, you'll notice the space between the word "font" and the following punctuation mark. With the .B command groff always assumes a word boundary at the end of the text which is to be printed bold. In this case groff's assumption is wrong. We don't want this space between "font" and the point. Thus you have to use another macro instead: 
 This text is printed with a
 .BR "bold font" .
 Now this is printed using a normal font.
.BR means: "first print bold text, then switch back to the roman font." This macro accepts up to six arguments, printing the first one with a bold font, the second one using a roman font, then printing bold text again, and so on. Remember to enclose text in quotation marks if it contains spaces. Notice the point beeing the second argument to .BR, thus seperated by an space from the text "bold font". 

Other combinations are also possible: 

.IR
first italic, then back to roman.
.UR
first underlined, then back to roman.
.BI
first bold, then back to italic.
 
STEP 6: Macros to Make Life Easier

Thanks to this "turbo introduction" to groff, you should now be able to write your own man pages ;-). 

But life can be so much easier using macros for the every day's work. In addition, macros help to keep a certain style throughout your document or a set of documents. 


Back to the Tips page 

Contents: Harald Albrecht (albrecht@igpm.rwth-aachen.de) 
Layout: Harald Albrecht 
Last Change: 97/08/10 (ab)