Creating Linux Man Pages: How to Create On-Line Documentation for Linux

Man pages provide an excellent on-line resource for every Linux user, and this tutorial shows how to built a Man page from scratch.

Forty years ago the first port of call for any Unix user having problems with a program was the Man command, and today the first port of call for any Linux user having problems with a program is still the man command; and that's no wonder - it enables a vast amount of information to be available for both program developers and program users.

On top of which, it's very easy for developers to add their own documentation - as this tutorial will show.

The Linux Man Page Convention

Man pages generally follow the same convention:

• Name
• Synopsis
• Configuration
• Description
• Options
• Exit Status
• Return Value
• Errors
• Environment
• Files
• Versions
• Conforming to
• Notes
• Bugs
• Example
• See also

Although Man pages should follow the convention not all of the sections are mandatory, for example:

• the configuration section is usually only used when documenting devices
• options and the exit status are only needed when discussing commands (both for ordinary and root users)
• return values, errors and versions would only be expected for system calls and library functions (in C programs, for instance)

Creating a Man Page

A developer does not need any special software to create a Man page - just a simple text editor and some formatting tags:

• .TH - the man page title
• .SH - section headers
• .SS - sub-section headers
• .PP - new paragraph
• .B - bold text
• .I - text in italics

With these basic tags a Man page can be written quite quickly:
." Set the title
.TH Yahoo Finance
." Add a header for the name section
.SH NAME
Yahoo Finance Stock Quotes
.SH SYNOPSIS
wget -O [
." put the key words into italics
.I output file
] [
.I url
] [
.I company symbols
] [
.I fields
]
.SH DESCRIPTION
Download Yahoo Finance stock quotes directly into a CSV file.
.SH OPTIONS
." Add a sub-section
.SS FIELDS
." use bold for the field values
.B s
the company symbol
.PP
.B l1
latest stock quote
.PP
.B c1
change in stock value
.PP
.B d1
date of the stock quote
.SH FILES
http://download.finance.yahoo.com/d/quotes.csv
.SH EXAMPLE
."Add some formatted text
.nf
wget -O shares.csv \
http://download.finance.yahoo.com/d/quotes.csv?s=RHT,MSFT,NOVL\
&f=sl1c1d1&e=.csv
." End the formatted text
.fi

Testing a Man Page

There are two, very simple, ways to test this new man page:

• use the nroff command to view the formatted output, for example: nroff -man yahoo_finance.txt
• copy the text document to the correct area in the system and use the man command to view the result

Linux Man Page Locations

The directories for storing the man pages will be found in one of two areas:

/usr/share/man
/usr/local/man

In the two directories there will be one or more sub-directories, each one named man with a number or a letter for a suffix (for example man1); each of these sub-directories is for a particular type of man page, which may vary from system to system, but typically they are:

0 - header files
1 - standard commands
2 - Linux kernel system calls
3 - standard c library functions
4 - special devices
5 - file formats and conventions
6 - games and toys
7 - miscellaneous , for example standards (for example SQL and ISO)
8 - root commands
9 - kernel details
n - Tcl/Tk functionality

Sometimes a letter p may be used as an additional prefix (for example man3p) in which case the sub-directory will contain POSIX versions of the man pages.

Not only must the file be placed in the correct directory but it must also be given the correct suffix, for example all files placed in the man1 directory must have a suffix of 1:
sudo cp yahoo.txt /usr/local/man/man1/yahoo.1

The new Man page can now be called from the command line just like any other Man page:
man yahoo

Man pages are very easy to create and to maintain, and by using this simple system program developers will always be able to keep their users completely up to date.

---

Posted on Utopian.io - Rewarding Open Source Contributors

---