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 article 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:
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:
The new Man page can now be called from the command line just like any other Man page:
Conclusion
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.
