mirror of https://github.com/tLDP/LDP
1084 lines
41 KiB
Plaintext
1084 lines
41 KiB
Plaintext
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
|
<article>
|
|
<articleinfo>
|
|
<title>Linux Man Page Howto</title>
|
|
<author>
|
|
<firstname> Jens </firstname>
|
|
<surname> Schweikhardt</surname>
|
|
<affiliation>
|
|
<address><email>howto@schweikhardt.net</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<othercredit role='converter'>
|
|
<firstname>Pradeep</firstname>
|
|
<surname>Padala</surname>
|
|
<contrib>Conversion from HTML to DocBook v4.1.</contrib>
|
|
</othercredit>
|
|
<revhistory>
|
|
|
|
<revision>
|
|
<revnumber>0.1</revnumber>
|
|
<date>2002-09-07</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Conversion from HTML to Docbook v4.1
|
|
</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
|
|
<pubdate>v0.1, 2002-09-07</pubdate>
|
|
<abstract>
|
|
<para>$Id$</para>
|
|
<para>
|
|
<emphasis>
|
|
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 <literal>man</literal>(1)
|
|
command. Throughout this HOWTO, a manual entry is simply referred
|
|
to as a man page, regardless of actual length and without sexist
|
|
intention.
|
|
</emphasis>
|
|
</para>
|
|
</abstract>
|
|
</articleinfo>
|
|
|
|
<sect1 id="q1"><title>A few thoughts on documentation</title>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Documentation must be accessible. If it's hidden in some
|
|
non-standard place where the documentation-related tools won't
|
|
find it -- how can it serve its purpose?</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Documentation must be reliable and accurate. There's
|
|
nothing more annoying than having program behaviour and
|
|
documentation disagree. Users will curse you, send you hate mail
|
|
and throw your work into the bit bucket, with the firm intent to
|
|
never install anything written by that jerk again.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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 <literal>man</literal>(1), <literal>xman</literal>(1x),
|
|
<literal>apropos</literal>(1), <literal>makewhatis</literal>(8) and
|
|
<literal>catman</literal>(8). Reliability and accuracy of the
|
|
information are, of course, up to you. But even in this respect you
|
|
will find <link linkend="q9">some ideas below</link> that help you
|
|
avoid some common glitches.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q2"><title>How are man pages accessed?</title>
|
|
|
|
<para>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:</para>
|
|
|
|
<programlisting>
|
|
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.
|
|
</programlisting>
|
|
|
|
<para>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'.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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 `<literal>make install</literal>' 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 <link linkend="q2">table above</link>. 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 <link linkend="q12">paragraph 12)</link>. 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 <literal>Makefile</literal>, however,
|
|
will allow the user to chose a base directory, by means of a
|
|
<literal>make</literal> variable, MANDIR, say. Most of the GNU
|
|
packages can be configured with the
|
|
<literal>--prefix=/what/ever</literal> 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.</para>
|
|
|
|
<para>With the advent of the Linux
|
|
File System Standard (FS-Stnd), things became more
|
|
complicated. [Note: the FS-Stnd appears to be replaced
|
|
by the <ulink url="http://www.pathname.com/fhs/">Filesystem Hierarchy
|
|
Standard</ulink>, FHS.] The FS-Stnd 1.2 states that</para>
|
|
|
|
<para>"Provisions must be made in the structure of /usr/man to
|
|
support manual pages which are written in different (or multiple)
|
|
languages."</para>
|
|
|
|
|
|
<para>This is achieved by introducing another directory level that
|
|
distinguishes between different languages. Quoting again from
|
|
FS-Stnd 1.2:</para>
|
|
|
|
<para>"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>]"</para>
|
|
|
|
|
|
<para>(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</para>
|
|
|
|
<para>"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 <literal>man[1-9]</literal> directories) directly in /usr/man.
|
|
(That is the traditional circumstance and arrangement in
|
|
fact.)"</para>
|
|
|
|
|
|
<para>I would not switch until all tools (like xman, tkman, info
|
|
and many others that read man pages) can cope with the new
|
|
structure.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q3"><title>How should a formatted man page look?</title>
|
|
|
|
<para>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 (<emphasis>bold</emphasis> and
|
|
<emphasis>italics</emphasis>). [TODO: the bold and italics has
|
|
disappeared with the conversion to SGML/HTML; Bring it back.]
|
|
Please refer to the paragraph
|
|
"<link linkend="q8">What are the font
|
|
conventions?</link>" for further explanations. Here comes the
|
|
man page for the (hypothetical) <literal>foo</literal>
|
|
program.</para>
|
|
|
|
<programlisting>
|
|
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 <ulink url="mailto:howto@schweikhardt.net"><howto at schweikhardt dot net></ulink>
|
|
|
|
SEE ALSO
|
|
bar(1), foo(5), xyzzy(1)
|
|
|
|
Linux Last change: MARCH 1995 2
|
|
|
|
</programlisting>
|
|
|
|
<para>Here's the explanation as I promised.</para>
|
|
|
|
<para><emphasis>The NAME section</emphasis></para>
|
|
|
|
<para>...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 <literal>makewhatis</literal>(8), the name
|
|
sections make it into the <literal>whatis</literal> database files.
|
|
<literal>Makewhatis</literal> is the reason the name section must
|
|
exist, and why it must adhere to the format I described. In the
|
|
<literal>groff</literal> source it must look like</para>
|
|
|
|
<para><emphasis>.SH NAME foo \- frobnicate the bar library</emphasis></para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para><emphasis>The SYNOPSIS section</emphasis></para>
|
|
|
|
<para>...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.</para>
|
|
|
|
<para><emphasis>The DESCRIPTION section</emphasis></para>
|
|
|
|
<para>...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.</para>
|
|
|
|
<para><emphasis>The OPTIONS section</emphasis></para>
|
|
|
|
<para>...gives a description of how each option affects program
|
|
behaviour. You knew that, didn't you?</para>
|
|
|
|
<para><emphasis>The FILES section</emphasis></para>
|
|
|
|
<para>...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 <literal>groff</literal>
|
|
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/*</para>
|
|
|
|
<para><emphasis>The ENVIRONMENT section</emphasis></para>
|
|
|
|
<para>...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.</para>
|
|
|
|
<para><emphasis>The DIAGNOSTICS section</emphasis></para>
|
|
|
|
<para>...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 messages (from
|
|
<literal>perror</literal>(3)) or fatal signals (from
|
|
<literal>psignal</literal>(3)) as they can appear during execution
|
|
of any program.</para>
|
|
|
|
<para><emphasis>The BUGS section</emphasis></para>
|
|
|
|
<para>...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 ;-)</para>
|
|
|
|
<para><emphasis>The AUTHOR section</emphasis></para>
|
|
|
|
<para>...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.</para>
|
|
|
|
<para><emphasis>The SEE ALSO section</emphasis></para>
|
|
|
|
<para>...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:</para>
|
|
|
|
<programlisting>
|
|
.\" 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)
|
|
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="q4"><title>How do I document several programs/functions in a
|
|
single man page?</title>
|
|
|
|
<para>Many programs (<literal>grep</literal>,
|
|
<literal>egrep</literal>) and functions (<literal>printf</literal>,
|
|
<literal>fprintf</literal>, ...) are documented in a single man
|
|
page. However, these man pages would be quite useless if they were
|
|
only accessible under one name. We cannot expect a user to remember
|
|
that the <literal>egrep</literal> man page is actually the
|
|
<literal>grep</literal> man page. It is therefore necessary to have
|
|
the man page available under different names. You have several
|
|
possibilities to achieve this:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>have identical copies for each name.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>connect all man pages using hard links.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>symbolic links pointing to the actual man page.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>use <literal>groff</literal>'s `source' mechanism
|
|
provided by the <literal>.so</literal> macro.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The first way is obviously a waste of disk space. The second
|
|
is not recommended because intelligent versions of the
|
|
<literal>catman</literal> program can save a lot of work by looking
|
|
at the file type or contents. Hard links will prevent
|
|
<literal>catman</literal> from being clever. (Note that
|
|
<literal>catman</literal>'s purpose is to format all man pages
|
|
so they can be displayed quickly.) The third alternative has a
|
|
slight drawback: if flexibility is a concern, you have to be aware
|
|
that there are file systems that do not support symbolic links. The
|
|
upshot of this is that the Best Thing (TM) is using
|
|
<literal>groff</literal>'s source mechanism. Here's how to
|
|
do it: If you want to have your man page available under the names
|
|
`foo' and `bar' in section 1, then put the man page in
|
|
foo.1 and have bar.1 look like this:</para>
|
|
|
|
<para><literal>.so man1/foo.1</literal></para>
|
|
|
|
<para>It is important to specify the <literal>man1/</literal>
|
|
directory part as well as the file name `foo.1' because when
|
|
<literal>groff</literal> is run by the browser it will have the
|
|
manual base directory as its current working directory (cwd) and
|
|
<literal>groff</literal> interprets <literal>.so</literal>
|
|
arguments relative to the cwd.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q5"><title>Which macro package should I
|
|
use?</title>
|
|
|
|
<para>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
|
|
<literal>tmac.</literal><something>, where <something>
|
|
is the argument to groff's -m option. Groff will use
|
|
<literal>tmac.</literal><something> when it is given the
|
|
`<literal>-m</literal> <something>' option. Often the
|
|
blank between `<literal>-m</literal>' and
|
|
`<something>' is omitted so we may say `<literal>groff
|
|
-man</literal>' when we are formatting man pages using the
|
|
<literal>tmac.an</literal> macro package. That's the reason for
|
|
the strange name `tmac.an'. Besides tmac.an there is another
|
|
popular macro package, <literal>tmac.doc</literal>, which
|
|
originated at the University of California at Berkeley. Many BSD
|
|
man pages use it and it seems that UCB has made it its standard for
|
|
documentation. The <literal>tmac.doc</literal> macros are much more
|
|
flexible but alas, there are manual browsers that will not use them
|
|
but always call <literal>groff -man</literal>. For example, all
|
|
<literal>xman</literal> programs I have seen will screw up on man
|
|
pages requiring <literal>tmac.doc</literal>. So do yourself a
|
|
favor: use <literal>tmac.an</literal> -- use of any other macro
|
|
package is considered harmful. <literal>tmac.andoc</literal> is a
|
|
pseudo macro package that takes a look at the source and then loads
|
|
either <literal>tmac.an</literal> or <literal>tmac.doc</literal>.
|
|
Actually, any man page browser should use it but to this point, not
|
|
all of them do, so it is best we cling to ye olde
|
|
<literal>tmac.an</literal>. Anything I tell you from now on and
|
|
concerning macros only holds true for <literal>tmac.an</literal>.
|
|
If you want to use the <literal>tmac.doc</literal> macros anyway,
|
|
have a look at the tutorial sampler, <ulink
|
|
url="http://www.freebsd.org/cgi/man.cgi?query=mdoc.samples"><literal>mdoc.samples</literal></ulink>.
|
|
Some distros (I'm told) also come with mdoc(7), mdoc.samples(7) and
|
|
groff_man(7).</para>
|
|
|
|
<para>The definitive dope for <literal>troff</literal>, with all
|
|
macros explained, is the <emphasis>Troff User's
|
|
Manual</emphasis>, available as
|
|
<ulink url="http://cm.bell-labs.com/sys/doc/troff.html">html</ulink>,
|
|
<ulink url="http://cm.bell-labs.com/sys/doc/troff.ps">PostScript
|
|
(ps, 760K)</ulink> or
|
|
<ulink url="http://cm.bell-labs.com/sys/doc/troff.pdf">Portable
|
|
Document Format (pdf, 240K)</ulink>. 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
|
|
<ulink url="http://www.kohala.com/start/">W. Richard Steven's
|
|
homepage</ulink> (famous for <emphasis>Unix Network
|
|
Programming</emphasis> as well as the <emphasis>TCP/IP
|
|
Illustrated</emphasis> trilogy), who also has a list of
|
|
<ulink url="http://www.kohala.com/start/troff/troff.html">Troff
|
|
Resources</ulink> including <literal>tbl</literal>,
|
|
<literal>eqn</literal>, <literal>pic</literal> and other
|
|
filters.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q6"><title>What preprocessors may I
|
|
use?</title>
|
|
|
|
<para>Groff comes with at least three preprocessors,
|
|
<literal>tbl</literal>, <literal>eqn</literal>, and
|
|
<literal>pic</literal> (on some systems they are named
|
|
<literal>gtbl</literal>, <literal>geqn</literal> and
|
|
<literal>gpic</literal>.) Their purpose is to translate
|
|
preprocessor macros and their data to regular troff input.
|
|
<literal>Tbl</literal> is a table preprocessor,
|
|
<literal>eqn</literal> is an equations/maths preprocessor and
|
|
<literal>pic</literal> is a picture preprocessor. Please refer to
|
|
the man pages for more information on what functionality they
|
|
provide. To put it in a nutshell: don't write man pages
|
|
requiring <emphasis>any</emphasis> preprocessor. Eqn will generally
|
|
produce terrible output for typewriter-like devices, unfortunately
|
|
the type of device 99% of all man pages are viewed on (well, at
|
|
least I do). For example, XAllocColor.3x uses a few formulas with
|
|
exponentiation. Due to the nature of typewriter-like devices, the
|
|
exponent will be on the same line as the base. N to the power of
|
|
two appears as `N2'. <literal>Tbl</literal> should be avoided
|
|
because all xman programs I have seen fail on them. Xman 3.1.6 uses
|
|
the following command to format man pages, e.g. signal(7):</para>
|
|
|
|
<para><literal>gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff
|
|
-Tascii -man /tmp/xmana01760 2> /dev/null</literal></para>
|
|
|
|
<para>which screws up for sources using <literal>gtbl</literal>,
|
|
because <literal>gtbl</literal> output is fed again into
|
|
<literal>gtbl</literal>. The effect is a man page without your
|
|
table. I don't know if it's a bug or a feature that
|
|
<literal>gtbl</literal> chokes on its own output or if xman could
|
|
be a little smarter and not use <literal>gtbl</literal> twice.
|
|
Furthermore, some systems use <literal>grog</literal> to determine
|
|
what options to pass to groff. Unfortunately grog sometimes guesses
|
|
wrong and recommends <literal>groff -t</literal> when in fact
|
|
<literal>tbl</literal> must not be used. We are basically left with
|
|
two workarounds for tables:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Format the table yourself manually and put it between .nf and
|
|
.fi lines so that it will be left unformatted. You won't have
|
|
bold and italics this way but this beats having your table
|
|
swallowed any day.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use any <literal>tbl</literal> macros you like but distribute
|
|
the <literal>tbl</literal> output instead of the input. There is
|
|
however this quirk with <literal>grog</literal> who thinks that any
|
|
file containing a line starting with <literal>.TS</literal>
|
|
requires <literal>tbl</literal>. <literal>Tbl</literal> output for
|
|
some reason unbeknownst to me still contains <literal>.TS</literal>
|
|
and <literal>.TE</literal>. It seems you can simply remove them and
|
|
have the result still look okay. YMMV, so please test this with
|
|
your particular man page.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>I have yet to see a man page requiring <literal>pic</literal>
|
|
preprocessing. But I would not like it. As you can see above,
|
|
<literal>xman</literal> will not use it and
|
|
<literal>groff</literal> will certainly do the funky wadakiki on
|
|
the input.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q7"><title>Should I distribute source
|
|
and/or already formatted documentation?</title>
|
|
|
|
<para>Let me give the pros (+) and cons (-) of a few selected
|
|
possibilities:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Source only:+ smaller distribution package.- inaccessible on
|
|
systems without <literal>groff</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Uncompressed formatted only:+ accessible even on systems
|
|
without <literal>groff</literal>.- the user can't generate a
|
|
dvi or postscript file.- waste of disk space on systems that also
|
|
handle compressed pages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Compressed formatted only:+ accessible even on systems
|
|
without <literal>groff</literal>.- the user can't generate a
|
|
dvi or postscript file.- which compression format would you use?
|
|
.Z? .z? .gz? All of them?</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Source and uncompressed formatted:+ accessible even on
|
|
systems without <literal>groff</literal>.- larger distribution
|
|
package- some systems may expect compressed formatted man pages.-
|
|
redundant information on systems equipped with
|
|
<literal>groff</literal>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>IMHO it is best to distribute source only. The argument that
|
|
it's inaccessible on systems without <literal>groff</literal>
|
|
does not matter. The 500+ man pages of the Linux Documentation
|
|
Project are source only. The man pages of XFree86 are source only.
|
|
The man pages from the FSF are source only. In fact, I have rarely
|
|
seen software distributed with formatted man pages. If any sysadmin
|
|
is really concerned about having man pages accessible then he also
|
|
has <literal>groff</literal> installed.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q8"><title>What are the font
|
|
conventions?</title>
|
|
|
|
<para>First of all: don't use direct font operators like
|
|
<literal>\fB</literal>, <literal>\fP</literal> etc. Use macros
|
|
which take arguments. This way you avoid a common glitch:
|
|
forgetting the font change at the end of the word and having the
|
|
bold or italic extend up to the next font change. Believe me, it
|
|
happens more often than you think. The <literal>tmac.an</literal>
|
|
macros provide the following type faces:</para>
|
|
|
|
<para>.B Bold</para>
|
|
|
|
<para>.BI Bold alternating with italics</para>
|
|
|
|
<para>.BR Bold alternating with Roman</para>
|
|
|
|
<para>.I Italics</para>
|
|
|
|
<para>.IB Italics alternating with bold</para>
|
|
|
|
<para>.IR Italics alternating with Roman</para>
|
|
|
|
<para>.RB Roman alternating with bold</para>
|
|
|
|
<para>.RI Roman alternating with italics</para>
|
|
|
|
<para>.SM Small (scaled 9/10 of the regular size)</para>
|
|
|
|
<para>.SB Small bold (<emphasis>not</emphasis> small alternating
|
|
with bold)</para>
|
|
|
|
|
|
<para>X alternating with Y means that the odd arguments are typeset
|
|
in X while the even arguments are typeset in Y. For example</para>
|
|
|
|
<para>.BI "Arg 1 is Bold, " "Arg 2 is Italics,
|
|
" "and Bold, " "and Italics."</para>
|
|
|
|
|
|
<para>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 <emphasis>want</emphasis>
|
|
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))</para>
|
|
|
|
<para>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:</para>
|
|
|
|
<para>.BI "myfunction(int " argc ", char **"
|
|
argv );</para>
|
|
|
|
|
|
<para>Filenames are always in italics, except in the SYNOPSIS
|
|
section, where included files are in bold. So you should use</para>
|
|
|
|
<para>.I /usr/include/stdio.h</para>
|
|
|
|
|
|
<para>and</para>
|
|
|
|
<para>.B #include <stdio.h></para>
|
|
|
|
|
|
<para>Special macros, which are usually in upper case, are in
|
|
bold:</para>
|
|
|
|
<para>.B MAXINT</para>
|
|
|
|
|
|
<para>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:</para>
|
|
|
|
<para>.TP.B EBADF.I fd is not a valid file descriptor..TP.B
|
|
EINVAL.I fd is unsuitable for reading</para>
|
|
|
|
|
|
<para>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:</para>
|
|
|
|
<para>.BR man (7)</para>
|
|
|
|
|
|
<para>Acronyms look best when typeset in small type face. So I
|
|
recommend</para>
|
|
|
|
<para>.SM UNIX</para>
|
|
|
|
<para>.SM ASCII</para>
|
|
|
|
<para>.SM TAB</para>
|
|
|
|
<para>.SM NFS</para>
|
|
|
|
<para>.SM LALR(1)</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q9"><title>Polishing your man
|
|
page</title>
|
|
|
|
<para>Following are some guidelines that increase reliability,
|
|
readability and 'formatability' of your
|
|
documentation.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Test examples to make sure they work (use cut and paste to
|
|
give your shell the exact wording from the man page). Copy the
|
|
output of your command into your man page, don't just type what
|
|
you <emphasis>think</emphasis> your program will print.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Proof read, ispell, and have someone else read it, especially
|
|
if you are not a native English speaker. The HOWTO you are reading
|
|
has passed the latter test (special thanks to Michael Miller for a
|
|
particular heroic contribution! All the remaining rough edges are
|
|
entirely my fault). Additional volunteers are always
|
|
welcome.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your man page: Does <literal>groff</literal> complain
|
|
when you format your man page? It's nice to have the
|
|
<literal>groff</literal> command line in a comment. Does the
|
|
<literal>man</literal>(1) command complain when you call
|
|
<literal>man yourprog</literal>? Does it produce the expected
|
|
result? Will <literal>xman</literal>(1x) and
|
|
<literal>tkman</literal>(1tk) cope with your manual? XFree86 3.1
|
|
has xman 3.1.6 - X11R6, it will try to uncompress
|
|
using<literal>gzip -c -d < %s > %s zcat < %s >
|
|
%s</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Will <literal>makewhatis</literal>(8) be able to extract the
|
|
one-line description from the NAME section?</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Translate your man page to HTML format using
|
|
<literal>rman</literal> from <ulink
|
|
url="http://polyglotman.sourceforge.net/">
|
|
http://polyglotman.sourceforge.net/</ulink>, and view the result with a
|
|
a set of web browsers (netscape, mozilla, opera, lynx, ...) Check that
|
|
the cross-references among your man pages work as hyperlinks in the
|
|
generated HTML. If your software package has a web site, post its man
|
|
pages there, and keep them up-to-date.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <literal>rman</literal> utility can also translate man pages
|
|
into LaTeX, RTF, SGML, and other formats; check these out if you want
|
|
to incorporate your man pages in a book or other larger document.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Try translating your man page to HTML using
|
|
<literal>man2html</literal>, which has been part of the Linux man
|
|
package since man-1.4. The <literal>man2html</literal> utility is a less
|
|
ambitious translator than <literal>rman</literal>, but almost every
|
|
Linux user has it already, so it is worth making sure that
|
|
<literal>man2html</literal> does not choke on your man page.</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="q10"><title>How do I get a plain text man
|
|
page without all that ^H^_ stuff?</title>
|
|
|
|
<para>Have a look at <literal>col</literal>(1), because
|
|
<literal>col</literal> can filter out backspace sequences. Just in
|
|
case you can't wait that long:</para>
|
|
|
|
<para><literal>funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 |
|
|
col -bx > manpage.txt</literal></para>
|
|
|
|
<para>The <literal>-t</literal> and <literal>-e</literal> switches
|
|
tell <literal>groff</literal> to preprocess using
|
|
<literal>tbl</literal> and <literal>eqn</literal>. This is overkill
|
|
for man pages that don't require preprocessing but it does no
|
|
harm apart from a few CPU cycles wasted. On the other hand, not
|
|
using <literal>-t</literal> when it is actually required does harm:
|
|
the table is terribly formatted. You can even find out (well,
|
|
"guess" is a better word) what command is needed to
|
|
format a certain <literal>groff</literal> document (not just man
|
|
pages) by issuing</para>
|
|
|
|
<para><programlisting>funnyprompt$ grog /usr/man/man7/signal.7
|
|
groff -t -man /usr/man/man7/signal.7</programlisting></para>
|
|
|
|
<para>"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, thereby saving you a
|
|
few pages (and mother nature a tree) when printing long and
|
|
elaborate man pages. Save it in a file named
|
|
<literal>strip-headers</literal> & chmod 755.</para>
|
|
|
|
<programlisting>
|
|
#!/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;
|
|
</programlisting>
|
|
|
|
<para>You have to use it as the first filter after the
|
|
<literal>man</literal> command as it relies on the number of
|
|
newlines being output by <literal>groff</literal>. For
|
|
example:</para>
|
|
|
|
<para><literal>funnyprompt$ man bash | strip-headers | col -bx >
|
|
bash.txt</literal></para>
|
|
</sect1>
|
|
|
|
<sect1 id="q11"><title>How do I get a high quality
|
|
PostScript man page?</title>
|
|
|
|
<para><literal>funnyprompt$ groff -t -e -mandoc -Tps manpage.1 >
|
|
manpage.ps</literal></para>
|
|
|
|
<para>Print or view that using your favorite PostScript
|
|
printer/viewer. See <link linkend="q10">question 10)</link> for an
|
|
explanation of the options.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="q12"><title>How do I get `apropos' and `whatis' to work?</title>
|
|
|
|
<para>Suppose you wonder what compilers are installed on your
|
|
system and how these can be invoked. To answer this (frequently
|
|
asked) question you say</para>
|
|
|
|
<programlisting>
|
|
funnyprompt$ apropos compiler
|
|
f77 (1) - Fortran 77 compiler
|
|
gcc (1) - GNU C and C++ compiler
|
|
pc (1) - Pascal compiler
|
|
</programlisting>
|
|
|
|
<para><literal>Apropos</literal> and <literal>whatis</literal> are
|
|
used to quickly report which man page has information on a certain
|
|
topic. Both programs search a number of files named `whatis'
|
|
that may be found in each of the manual base directories. As
|
|
previously stated, the whatis data base files contain a one line
|
|
entry for any man page in the respective directory tree. In fact,
|
|
that line is exactly the NAME section (to be precise: joined on one
|
|
line and with hyphenation removed; note that the section is
|
|
mentioned within parentheses). The whatis database files are
|
|
created with the <literal>makewhatis</literal>(8) program. There
|
|
are several versions around, so please refer to the man page to
|
|
determine what options are available. In order for
|
|
<literal>makewhatis</literal> to be able to extract the NAME
|
|
sections correctly it is important that you, the manual writer,
|
|
adhere to the NAME section format described under
|
|
<link linkend="q3">question 3)</link>. The differences between
|
|
<literal>apropos</literal> and <literal>whatis</literal> are simply
|
|
where in the line they look, and what they are looking for.
|
|
<literal>Apropos</literal> (which is equivalent to <literal>man
|
|
-k</literal>) searches the argument string anywhere on the line,
|
|
whereas <literal>whatis</literal> (equivalent to <literal>man
|
|
-f</literal>) tries to match a complete command name only on the
|
|
part before the dash. Consequently, `<literal>whatis
|
|
cc</literal>' will report if there is a <literal>cc</literal>
|
|
manual and remain quiet for <literal>gcc</literal>.</para>
|
|
|
|
<para>Corrections and suggestions welcome!</para>
|
|
</sect1>
|
|
|
|
<sect1 id="copying"><title>Copying conditions</title>
|
|
|
|
<para>Copyright 1995-2001 by Jens Schweikhardt. All rights
|
|
reserved.</para>
|
|
|
|
<programlisting>
|
|
"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.
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="acknowledgements"><title>Acknowledgements</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Michael Miller for proofreading the whole HOWTO (in February
|
|
2001); Gordon Torrie for many helpful grammar remarks (in August
|
|
2001). Any remaining grammar or style bogons are entirely my
|
|
fault.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink url="http://www.SuSE.de/">S.u.S.E. (.de)</ulink> (or
|
|
<ulink url="http://www.SuSE.com/">.com</ulink>) who are the only
|
|
distributor to keep sending me a free copy of their latest product,
|
|
acknowledging my work as a howto author.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>George B. Moody for additional suggestions on how to polish
|
|
a man page.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>If your name is missing here, drop me a note.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="changelog"><title>Changelog</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>March 6 2001: HTML source now passes <literal>weblint
|
|
-pedantic</literal>. <link linkend="q6">Paragraph 6:</link> Added
|
|
workarounds for <literal>tbl</literal> screw-ups. Added
|
|
<link linkend="acknowledgements">Acknowledgements</link> and
|
|
<link linkend="changelog">Changelog</link>. Added RCS Id.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>August 9 2001: Howto put under a two clause BSD
|
|
license.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>August 20 2001: Improved grammar. Use a numbered list for the
|
|
TOC.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>October 28 2001: Added refs to mdoc(7), mdoc.samples(7) and
|
|
groff_man(7).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>April 28 2002: Fix a grammar bogon by
|
|
s/particular/particularly/.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>April 30 2002: Update the link to the groff_mdoc BSD tutorial.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>November 29 2002: More suggestions for polishing your man page.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>December 15 2002: Publish SGML derived HTML. Removed dead link
|
|
to LSM.</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
</article>
|
|
|