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). [TODO: 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
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 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
...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) |