<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
>
