Jens Schweikhardt <howto@schweikhardt.net>
This HOWTO explains what you should bear in mind when you are going to write on-line documentation -- a so-called man page -- that you want to make accessible via the man(1) command. Throughout this HOWTO, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.
Why do we write documentation? Silly question. Because we want others to be able to use our program, library function or whatever we have written and made available. But writing documentation is not all there is to it:
The historical and well known way documentation is accessed on UNIX is via the man(1) command. This HOWTO describes what you have to do to write a man page that will be correctly processed by the documentation- related tools. The most important of these tools are man(1), xman(1x)?, apropos(1), makewhatis(8)? and catman(8). Reliability and accuracy of the information are, of course, up to you. But even in this respect you will find some ideas below that help you avoid some common glitches.
You need to know the precise mechanism for acccessing man pages in order to give your man page the right name and install it in the right place. Each man page should be categorized in a specific section, denoted by a single character. The most common sections under Linux, and their human readable names, are:
| Section | The human readable name | 1 | User commands that may be started by everyone. | 2 | System calls, that is, functions provided by the kernel. | 3 | Subroutines, that is, library functions. | 4 | Devices, that is, special files in the /dev directory. | 5 | File format descriptions, e.g. /etc/passwd. | 6 | Games, self-explanatory. | 7 | Miscellaneous, e.g. macro packages, conventions. | 8 | System administration tools that only root can execute. | 9 | Another (Linux specific) place for kernel routine documentation. | n | (Deprecated) New documentation, that may be moved to a more appropriate section. | o | (Deprecated) Old documentation, that may be kept for a grace period. | l | (Deprecated) Local documentation referring to this particular system.
The name of the man page's source file (the input to the formatting system) is the name of the command, function or file name, followed by a dot, followed by the section character. If you write the documentation on the format of the `passwd' file you have to name the source file `passwd.5'. Here we also have an example of a file name that is the same as a command name. There might be even a library subroutine named passwd. Sectioning is the usual way to resolve these ambiguities: The command description is found in the file `passwd.1' and the hypothetical library subroutine in `passwd.3'.
Sometimes additional characters are appended and the file name looks for example like `xterm.1x' or `wish.1tk'. The intent is to indicate that this is documentation for an X Window program or a Tk application, respectively. Some manual browsers can make use of this additional information. For example xman will use `xterm(x)' and `wish(tk)' in the list of available documentation.
Please don't use the n, o and l sections; according to the File System Standard these sections are deprecated. Stick to the numeric sections. Beware of name clashes with existing programs, functions or file names. It is certainly a bad idea to write yet another editor and call it ed, sed (for smart ed) or red (for Rocky's ed). By making sure your program's name is unique, you avoid having someone execute your program but read someone else's man page, or vice versa.
Now we know the name to give our file. The next decision is the directory in which it will finally be installed (say, when the user runs `make install' for your package.) On Linux, all man pages are below directories listed in the environment variable MANPATH. The doc-related tools use MANPATH in the same way the shell uses PATH to locate executables. In fact, MANPATH has the same format as PATH. Each contains a colon-separated list of directories (with the exception that MANPATH does not allow empty fields and relative pathnames -- it uses absolute names only.) If MANPATH is not set or not exported, a default will be used that contains at least the /usr/man directory. To speed up the search and to keep directories small, the directories specified by MANPATH (the so-called base directories) contain a bunch of subdirectories named `man<s>' where <s> stands for the one-character section designator introduced in the table above. Not all of the sections may be represented by a subdirectory because there simply is no reason to keep an empty `mano' subdirectory. However, there may be directories named `cat<s>', `dvi<s>' and `ps<s>' which hold documentation that is ready to display or print. More on this later. The only other file in any base directory should be a file named `whatis'. The purpose and creation of this file will also be described under paragraph 12). The safest way to have a man page for section <s> installed in the right place is to put it in the directory /usr/man/man<s>. A good Makefile, however, will allow the user to chose a base directory, by means of a make variable, MANDIR, say. Most of the GNU packages can be configured with the --prefix=/what/ever option. The manuals will then be installed under the base directory /what/ever/man. I suggest you also provide a way to do something similar.
With the advent of the Linux File System Standard (FS-Stnd), things became more complicated. the FS-Stnd appears to be replaced by the Filesystem Hierarchy Standard, FHS.? The FS-Stnd 1.2 states that
"Provisions must be made in the structure of /usr/man to support manual pages which are written in different (or multiple) languages."
This is achieved by introducing another directory level that distinguishes between different languages. Quoting again from FS-Stnd 1.2:
"This naming of language subdirectories of /usr/man is based on Appendix E of the POSIX 1003.1 standard which describes the locale identification string -- the most well accepted method to describe a cultural environment. The <locale> string is: <language>[_<territory>?[.<character-set>?[,<version>?"
(See the FS-Stnd for a few common <locale> strings.) According to these guidelines, we have our man pages in /usr/man/<locale>/man[1-9lno?. The formatted versions should then be in /usr/man/<locale>/cat[1-9lno? of course, otherwise we could only provide them for a single locale. HOWEVER, I can not recommend switching to that structure at this time. The FS-Stnd 1.2 also allows that
"Systems which use a unique language and code set for all manual pages may omit the <locale> substring and store all manual pages in <mandir>. For example, systems which only have English manual pages coded with ASCII, may store manual pages (the man[1-9? directories) directly in /usr/man. (That is the traditional circumstance and arrangement in fact.)"
I would not switch until all tools (like xman, tkman, info and many others that read man pages) can cope with the new structure.
Let me present you an example. Below I will explain it in detail. If you read this as plain text it won't show the different typefaces (bold and italics). the bold and italics has disappeared with the conversion to SGML/HTML; Bring it back.? Please refer to the paragraph "What are the font conventions?" for further explanations. Here comes the man page for the (hypothetical) foo program.
FOO(1) User Manuals FOO(1)
NAME
foo - frobnicate the bar library
SYNOPSIS
DESCRIPTION
foo frobnicates the bar library by tweaking internal symbol tables. By default it parses all baz segments and rearranges them in reverse order by time for the xyzzy(1) linker to find them. The symdef entry is then compressed using the WBG (Whiz-Bang-Gizmo) algorithm. All files are processed in the order specified.
OPTIONS
- b Do not write `busy' to stdout while processing.
c config-file
Use the alternate system wide config-file instead of /etc/foo.conf. This overrides any FOOCONF environment variable.
a In addition to the baz segments, also parse the blurfl
headers.
r Recursive mode. Operates as fast as lightning at the
expense of a megabyte of virtual memory.
FILES
/etc/foo.conf
The system wide configuration file. See foo(5) for fur- ther details.
/.foorc
Per user configuration file. See foo(5) for further details.
ENVIRONMENT
FOOCONF
If non-null the full pathname for an alternate system wide foo.conf. Overridden by the -c option.
DIAGNOSTICS
The following diagnostics may be issued on stderr:
Bad magic number.
The input file does not look like an archive file.
Old style baz segments.
foo can only handle new style baz segments. COBOL object libraries are not supported in this version.
BUGS
The command name should have been chosen more carefully to reflect its purpose.
AUTHOR
Jens Schweikhardt <howto at schweikhardt dot net>
SEE ALSO
bar(1), foo(5), xyzzy(1)
Linux Last change: MARCH 1995 2
Here's the explanation as I promised.
The NAME section
...is the only required section. Man pages without a name section are as useful as refrigerators at the north pole. This section also has a standardized format consisting of a comma-separated list of program or function names, followed by a dash, followed by a short (usually one line) description of the functionality the program (or function, or file) is supposed to provide. By means of makewhatis(8)?, the name sections make it into the whatis database files. Makewhatis is the reason the name section must exist, and why it must adhere to the format I described. In the groff source it must look like
.SH NAME foo \- frobnicate the bar library
The \- is of importance here. The backslash is needed to make the dash distinct from a hyphenation dash that may appear in either the command name or the one line description.
The SYNOPSIS section
...is intended to give a short overview on available program options. For functions this sections lists corresponding include files and the prototype so the programmer knows the type and number of arguments as well as the return type.
The DESCRIPTION section
...eloquently explains why your sequence of 0s and 1s is worth anything at all. Here's where you write down all your knowledge. This is the Hall Of Fame. Win other programmers' and users' admiration by making this section the source of reliable and detailed information. Explain what the arguments are for, the file format, what algorithms do the dirty jobs.
The OPTIONS section
...gives a description of how each option affects program behaviour. You knew that, didn't you?
The FILES section
...lists files the program or function uses. For example, it lists configuration files, startup files, and files the program directly operates on. It is a good idea to give the full pathname of these files and to make the install process modify the directory part to match user preferences: the groff manuals have a default prefix of /usr/local, so they reference /usr/local/lib/groff/* by default. However, if you install using 'make prefix=/opt/gnu' the references in the man page change to /opt/gnu/lib/groff/*
The ENVIRONMENT section
...lists all environment variables that affect your program or function and tells how, of course. Most commonly the variables will hold pathnames, filenames or default options.
The DIAGNOSTICS section
...should give an overview of the most common error messages from your program and how to cope with them. There's no need to explain system error error messages (from perror(3)) or fatal signals (from psignal(3)) as they can appear during execution of any program.
The BUGS section
...should ideally be non-existent. If you're brave, you can describe here the limitations, known inconveniences and features that others may regard as misfeatures. If you're not so brave, rename it the TO DO section ;-)
The AUTHOR section
...is nice to have in case there are gross errors in the documentation or program behaviour (Bzzt!) and you want to mail a bug report.
The SEE ALSO section
.\" Process this file with .\" groff -man -Tascii foo.1 .\" .TH FOO 1 "MARCH 1995" Linux "User Manuals" .SH NAME foo \- frobnicate the bar library .SH SYNOPSIS .B foo [-bar?
lib/CachedMarkup.php (In template 'browse' < 'body' < 'html'):257: Error: Pure virtual
lib/InlineParser.php:336: Warning: Invalid [] syntax ignored: [[-c
lib/CachedMarkup.php (In template 'browse' < 'body' < 'html'):257: Error: Pure virtual