Copyright (C) 2000-2012 |
Whole document tree THE LINUX MAN-PAGE-HOWTO Copyright 1995-2001 by Jens Schweikhardt, email: <howto at schweikhardt dot net> See further information on copying conditions below. $Id: man_page_howto.html,v 1.18 2001/08/09 18:22:33 schweikh Exp schweikh $ Click here to browse the author's latest version of this document. Corrections and suggestions welcome! 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 Table of contents
0) A few thoughts on documentation 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 1) How are man pages accessed? 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. Checking out the Linux Software Map (LSM) database on a program name is a place to start ensuring name uniqueness. 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 ` With the advent of the Linux File System Standard (FS-Stnd), things became more complicated. 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 I would not switch until all tools (like xman, tkman, info and many others that read man pages) can cope with the new structure. 2) How should a formatted man page look? 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). Please refer to the paragraph "What
are the font conventions?" for further explanations. Here comes
the man page for the (hypothetical) FOO(1) User Manuals FOO(1) NAME foo - frobnicate the bar library SYNOPSIS foo [-bar] [-c config-file ] file ... 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 .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 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 The BUGS section ...should ideally be non-existent. If you're brave, you can describe here limitations, known inconveniences, 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 ...is a list of related man pages in alphabetical order. Conventionally, it is the last section. You are free to invent other sections if they really don't fit in one of those described so far. So how exactly did you generate that man page? I expected that question, here's the source, Luke: .\" 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] [-c .I config-file .B ] .I file .B ... .SH DESCRIPTION .B 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 .BR 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. .SH OPTIONS .IP -b Do not write `busy' to stdout while processing. .IP "-c config-file" Use the alternate system wide .I config-file instead of .IR /etc/foo.conf . This overrides any .B FOOCONF environment variable. .IP -a In addition to the baz segments, also parse the blurfl headers. .IP -r Recursive mode. Operates as fast as lightning at the expense of a megabyte of virtual memory. .SH FILES .I /etc/foo.conf .RS The system wide configuration file. See .BR foo (5) for further details. .RE .I ~/.foorc .RS Per user configuration file. See .BR foo (5) for further details. .SH ENVIRONMENT .IP FOOCONF If non-null the full pathname for an alternate system wide .IR foo.conf . Overridden by the .B -c option. .SH DIAGNOSTICS The following diagnostics may be issued on stderr: Bad magic number. .RS The input file does not look like an archive file. .RE Old style baz segments. .RS .B foo can only handle new style baz segments. COBOL object libraries are not supported in this version. .SH BUGS The command name should have been chosen more carefully to reflect its purpose. .SH AUTHOR Jens Schweikhardt <howto at schweikhardt dot net> .SH "SEE ALSO" .BR bar (1), .BR foo (5), .BR xyzzy (1) 3) How do I document several programs/functions in a single man page? Many programs (
The first way is obviously a waste of disk space. The second is not
recommended because intelligent versions of the
It is important to specify the 4) Which macro package should I use? There are a number of macro packages especially designed for use in
writing man pages. Usually they are in the groff macro directory /usr/lib/groff/tmac.
The file names are troff , with all macros explained, is
the Troff User's Manual, available as
html,
PostScript (ps, 760K) or
Portable Document Format (pdf, 240K).
by Jospeh F. Ossanna and Brian W. Kernighan, revised November 1992.
AT&T Bell Labs have made it publicly available.
Don't forget to check out the late great
W. Richard Steven's
homepage (famous for Unix Network Programming as well as
the TCP/IP Illustrated trilogy),
who also has a list of
Troff Resources
including tbl , eqn , pic and other filters.
5) What preprocessors may I use? Groff comes with at least three preprocessors,
which screws up for sources using
I have yet to see a man page requiring 6) Should I distribute source and/or already formatted documentation? Let me give the pros (+) and cons (-) of a few selected possibilities:
IMHO it is best to distribute source only. The argument that it's
inaccessible on systems without 7) What are the font conventions? First of all: don't use direct font operators like .B Bold .BI Bold alternating with italics .BR Bold alternating with Roman .I Italics .IB Italics alternating with bold .IR Italics alternating with Roman .RB Roman alternating with bold .RI Roman alternating with italics .SM Small (scaled 9/10 of the regular size) .SB Small bold (not small alternating with bold) X alternating with Y means that the odd arguments are typeset in X while the even arguments are typeset in Y. For example .BI "Arg 1 is Bold, " "Arg 2 is Italics, " "and Bold, " "and Italics." The double quotes are needed to include white space into an argument; without them, no white space appears between the alternating typefaces. In fact, you'll only need the macros for alternating typefaces in cases where you want to avoid white space between typeface changes. So much for what's available. Here's how you should make use of the different typefaces: (portions shamelessly stolen from man(7)) Although there are many arbitrary conventions for man pages in the UNIX world, the existence of several hundred Linux-specific man pages defines our standards: For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold: .BI "myfunction(int " argc ", char **" argv ); Filenames are always in italics, except in the SYNOPSIS section, where included files are in bold. So you should use .I /usr/include/stdio.h and .B #include <stdio.h> Special macros, which are usually in upper case, are in bold: .B MAXINT When enumerating a list of error codes, the codes are in bold. This list usually uses the .TP (paragraph with hanging tag) macro as follows: .TP Any reference to another man page (or to the subject of the current man page) is in bold. If the manual section number is given, it is given in roman, without any spaces: .BR man (7) Acronyms look best when typeset in small type face. So I recommend .SM UNIX .SM ASCII .SM TAB .SM NFS .SM LALR(1) Following are some guidelines that increase reliability, readability and 'formatability' of your documentation.
9) How do I get a plain text man page without all that ^H^_ stuff? Have a look at
The
"Grog" stands for "GROff Guess", and it does what
it says--guess. If it were perfect we wouldn't need options any more.
I've seen it guess incorrectly on macro packages and on preprocessors.
Here is a little perl script I wrote that can delete the page headers
and footers, therefore saving you a few pages (and mother nature a tree)
when printing long and elaborate man pages. Save it in a file named
#!/usr/bin/perl -wn # make it slurp the whole file at once: undef $/; # delete first header: s/^\n*.*\n+//; # delete last footer: s/\n+.*\n+$/\n/g; # delete page breaks: s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g; # collapse two or more blank lines into a single one: s/\n{3,}/\n\n/g; # see what's left... print; You have to use it as the first filter after the
10) How do I get a high quality PostScript man page?
Print or view that using your favorite PostScript printer/viewer. See question 9) for an explanation of the options. 11) How do I get `apropos' and `whatis' to work? Suppose you wonder what compilers are installed on your system and how these can be invoked. To answer this (frequently asked) question you say
Corrections and suggestions welcome! Copyright 1995-2001 by Jens Schweikhardt. All rights reserved. "Two clause" BSD License: Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
If your name is missing here, drop me a note.
|