467 lines
10 KiB
HTML
467 lines
10 KiB
HTML
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>How should a formatted man page look?</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
|
|
REL="HOME"
|
|
TITLE="Linux Man Page Howto"
|
|
HREF="index.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="How are man pages accessed?"
|
|
HREF="q2.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="How do I document several programs/functions in a
|
|
single man page?"
|
|
HREF="q4.html"></HEAD
|
|
><BODY
|
|
CLASS="SECT1"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Linux Man Page Howto</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q2.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="q4.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="Q3"
|
|
></A
|
|
>3. How should a formatted man page look?</H1
|
|
><P
|
|
>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 (<EM
|
|
>bold</EM
|
|
> and
|
|
<EM
|
|
>italics</EM
|
|
>). [TODO: the bold and italics has
|
|
disappeared with the conversion to SGML/HTML; Bring it back.]
|
|
Please refer to the paragraph
|
|
"<A
|
|
HREF="q8.html"
|
|
>What are the font
|
|
conventions?</A
|
|
>" for further explanations. Here comes the
|
|
man page for the (hypothetical) <TT
|
|
CLASS="LITERAL"
|
|
>foo</TT
|
|
>
|
|
program.</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="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 <A
|
|
HREF="mailto:howto@schweikhardt.net"
|
|
TARGET="_top"
|
|
><howto at schweikhardt dot net></A
|
|
>
|
|
|
|
SEE ALSO
|
|
bar(1), foo(5), xyzzy(1)
|
|
|
|
Linux Last change: MARCH 1995 2 </PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
>Here's the explanation as I promised.</P
|
|
><P
|
|
><EM
|
|
>The NAME section</EM
|
|
></P
|
|
><P
|
|
>...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 <TT
|
|
CLASS="LITERAL"
|
|
>makewhatis</TT
|
|
>(8), the name
|
|
sections make it into the <TT
|
|
CLASS="LITERAL"
|
|
>whatis</TT
|
|
> database files.
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>Makewhatis</TT
|
|
> is the reason the name section must
|
|
exist, and why it must adhere to the format I described. In the
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>groff</TT
|
|
> source it must look like</P
|
|
><P
|
|
><EM
|
|
>.SH NAME foo \- frobnicate the bar library</EM
|
|
></P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
><EM
|
|
>The SYNOPSIS section</EM
|
|
></P
|
|
><P
|
|
>...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.</P
|
|
><P
|
|
><EM
|
|
>The DESCRIPTION section</EM
|
|
></P
|
|
><P
|
|
>...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.</P
|
|
><P
|
|
><EM
|
|
>The OPTIONS section</EM
|
|
></P
|
|
><P
|
|
>...gives a description of how each option affects program
|
|
behaviour. You knew that, didn't you?</P
|
|
><P
|
|
><EM
|
|
>The FILES section</EM
|
|
></P
|
|
><P
|
|
>...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 <TT
|
|
CLASS="LITERAL"
|
|
>groff</TT
|
|
>
|
|
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/*</P
|
|
><P
|
|
><EM
|
|
>The ENVIRONMENT section</EM
|
|
></P
|
|
><P
|
|
>...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.</P
|
|
><P
|
|
><EM
|
|
>The DIAGNOSTICS section</EM
|
|
></P
|
|
><P
|
|
>...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
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>perror</TT
|
|
>(3)) or fatal signals (from
|
|
<TT
|
|
CLASS="LITERAL"
|
|
>psignal</TT
|
|
>(3)) as they can appear during execution
|
|
of any program.</P
|
|
><P
|
|
><EM
|
|
>The BUGS section</EM
|
|
></P
|
|
><P
|
|
>...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 ;-)</P
|
|
><P
|
|
><EM
|
|
>The AUTHOR section</EM
|
|
></P
|
|
><P
|
|
>...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.</P
|
|
><P
|
|
><EM
|
|
>The SEE ALSO section</EM
|
|
></P
|
|
><P
|
|
>...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:</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="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) </PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="q2.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="q4.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>How are man pages accessed?</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>How do I document several programs/functions in a
|
|
single man page?</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |