<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="lfparser_2.38">
<META NAME="LFCATEGORY" CONTENT="UNIXBasics">
<link rel="icon" href="../../common/images/lf-16.png" type="image/png">
<TITLE>lf309, UNIXBasics: Writing man-pages</TITLE>
<style type="text/css">
<!--
td.top {font-family: Arial,Geneva,Verdana,Helvetica,sans-serif; font-size:12 }
pre { font-family:monospace,Courier }
pre.code { font-family:monospace,Courier;background-color:#aedbe8; }
p.cl { color:#EE9500 }
a.nodec { text-decoration:none }
p.trans { font-size:8pt; text-align:right }
p.clbox { width:50%; alignment:center; background-color:#FFD700;
border-style:none; border-width:medium; border-color:#FFD700;
padding:0.5cm; text-align:center }
p.code { width:80%; alignment:center; background-color:#aedbe8;
border-style:none; border-width:medium; border-color:#aedbe8;
padding:0.1cm; text-align:left }
p.foot { background-color:#AAAAAA; color:#FFFFFF; border-style:none;
border-width:medium; border-color:#AAAAAA; padding:0.5cm ;
margin-top:0.1cm; margin-right:1cm; margin-left:1cm;
text-align:center }
.mark { background-color:#e6e6ff }
-->
</style>
</HEAD>
<BODY bgcolor="#ffffff" text="#000000">
<!-- this is generated html code. NEVER use this file for your
translation work. Instead get the file with the same article number
and .meta.shtml in its name. Translate this meta file and then
use lfparser program to generate the final article -->
<!-- lfparser can be obtained from http://www.linuxfocus.org/~guido/dev/lfparser.html -->
<!-- this is used by a number of tools:
=LF=AUTHOR: Guido Socher
=LF=CAT___: UNIXBasics
=LF=TITLE_: Writing man-pages
=LF=NUMBER: 309
=LF=ANAME_: article309.shtml
-->
<!-- 2pdaIgnoreStart -->
<!-- start navegation bar, style=2 -->
<!-- top navegation bar -->
<TABLE summary="topbar_1" cellspacing="0" cellpadding="0" border="0" align="center" width="90%">
<TR bgcolor="#2e2292">
<TD class="top"><TABLE summary="topbar_1_logo" cellspacing="0" cellpadding="0" border="0" width=
"100%">
<TR><TD width="319"><IMG src="../../common/images/logolftop_319x45.gif"
alt="[LinuxFocus-icon]" width="319" height="45" align="left"
border="0"></TD>
<TD class="top">
<TABLE summary="topbar_1_links" width="100%">
<TR align="right">
<TD class="top">
<A class="nodec" href="index.shtml"><FONT color=
"#DDDDDD" size="2"><--</FONT></A> |
<A class="nodec" href="../index.shtml"><FONT color=
"#DDDDDD" size="2">Home</FONT></A> |
<A class="nodec" href="../map.html"><FONT color=
"#DDDDDD" size="2">Map</FONT></A> |
<A class="nodec" href="../indice.html"><FONT color=
"#DDDDDD" size="2">Index</FONT></A> |
<A class="nodec" href="../Search/index.html"><FONT color=
"#DDDDDD" size="2">Search</FONT></A> </TD>
</TR>
<TR align="right">
<TD class="top">
<HR width="100%" noshade size="1">
</TD>
</TR>
</TABLE>
</TD>
</TR>
</TABLE>
</TD>
</TR>
</TABLE>
<!-- end top navegation bar -->
<!-- blue bar -->
<TABLE summary="topbar_2" cellspacing="0" cellpadding="0" border="0" align="center"
width="90%">
<TR bgcolor="#00ffff">
<TD><IMG src="../../common/images/transpix.gif" width="1" height=
"2" alt=""></TD>
</TR>
</TABLE>
<!-- end blue bar -->
<!-- bottom navegation bar -->
<TABLE summary="topbar_3" cellspacing="0" cellpadding="0" border="0" align="center"
width="94%">
<TR bgcolor="#000000">
<TD>
<TABLE summary="topbar_3_links" cellspacing="0" cellpadding="1" border="0" width=
"100%">
<TR align="center">
<TD WIDTH="20%"><A class="nodec" href="../News/index.html"><FONT color=
"#FFFFFF">News</FONT></A> </TD>
<TD WIDTH="5%"><FONT color="#FFFFFF">|</FONT> </TD>
<TD WIDTH="20%"><A class="nodec" href="../Archives/index.html"><FONT color=
"#FFFFFF">Archives</FONT></A> </TD>
<TD WIDTH="5%"><FONT color="#FFFFFF">|</FONT> </TD>
<TD WIDTH="20%"><A class="nodec" href="../Links/index.html"><FONT color=
"#FFFFFF">Links</FONT></A> </TD>
<TD WIDTH="5%"><FONT color="#FFFFFF">|</FONT> </TD>
<TD WIDTH="20%"><A class="nodec" href="../aboutus.html"><FONT color=
"#FFFFFF">About LF</FONT></A> </TD>
</TR>
</TABLE>
</TD>
</TR>
</TABLE>
<!-- end bottom navegation bar -->
<!-- stop navegation bar -->
<!-- SSI_INFO -->
<!-- tr_staticssi include virtual -->
<!-- tr_staticssi exec cmd -->
<!-- addedByLfdynahead ver 1.4 --><TABLE ALIGN="right" border=0><TR><TD ALIGN="right"><FONT SIZE="-1" FACE="Arial,Helvetica">This document is available in: <A href="../../English/November2003/article309.shtml">English</a> <A href="../../Castellano/November2003/article309.shtml">Castellano</a> <A href="../../Deutsch/November2003/article309.shtml">Deutsch</a> <A href="../../Francais/November2003/article309.shtml">Francais</a> <A href="../../Italiano/November2003/article309.shtml">Italiano</a> <A href="../../Nederlands/November2003/article309.shtml">Nederlands</a> <A href="../../Russian/November2003/article309.shtml">Russian</a> <A href="../../Turkce/November2003/article309.shtml">Turkce</a> </FONT></TD></TR></TABLE><br>
<!-- SSI_INFO STOP -->
<!-- 2pdaIgnoreStop -->
<!-- SHORT BIO ABOUT THE AUTHOR -->
<TABLE ALIGN=LEFT BORDER=0 WIDTH="190" summary="about the author">
<TR>
<TD>
<img src="../../common/images/Guido-S.gif" alt=
"[Photo of the Author]" height="164" width="173">
<BR>by Guido Socher <a href="http://linuxfocus.org/~guido/"><font size="1">(homepage)</font></a>
<BR><BR>
<I>About the author:</I><BR>
<!-- aboutauthor_start -->
<p>Guido likes Linux because it is a very flexible and offers
much more possibilities than any other operating system.</p>
<!-- aboutauthor_stop -->
<!-- TRANSLATED TO en -->
<!-- TRANSLATED TO STOP -->
<BR><i>Content</i>:
<UL>
<LI><A HREF="#309lfindex0">Introduction</A></LI>
<LI><A HREF="#309lfindex1">The sections</A></LI>
<LI><A HREF="#309lfindex2">MANPATH</A></LI>
<LI><A HREF="#309lfindex3">The formatting keywords</A></LI>
<LI><A HREF="#309lfindex4">The chapters</A></LI>
<LI><A HREF="#309lfindex5">A sample man-page</A></LI>
<LI><A HREF="#309lfindex6">Viewing and formatting your man-page</A></LI>
<LI><A HREF="#309lfindex7">Using perl POD to generate man-pages</A></LI>
<LI><A HREF="#309lfindex8">References</A></LI>
<LI><A HREF="http://cgi.linuxfocus.org/cgi-bin/lftalkback?anum=309">Talkback form for this article</A></LI>
</UL>
</TD></TR></TABLE>
<!-- HEAD OF THE ARTICLE -->
<br>
<table border="0"><tr><td>
<H2>Writing man-pages</H2>
<img src="../../common/images/article309/manual.gif" alt="man" hspace="10" width="199" height="246">
<!-- ABSTRACT OF THE ARTICLE -->
<P><i>Abstract</i>:
<P>
<!-- articleabstract_start -->
Every good program that can be used from the UNIX shell should
be documented in its own man-page. This tutorial will give you
a quick introduction into writing manual pages.
<!-- articleabstract_stop -->
<br><!-- HR divider --><center><font color="#8282e0"><b>_________________ _________________ _________________</b></font></center><br>
</td></tr></table>
<!-- BODY OF THE ARTICLE -->
<A NAME="309lfindex0"> </A>
<H2>Introduction</H2>
Documentation is often more important than the software itself
especially if the software should not only be used by the
author. Even if I write a program which I do not intend to
publish I write documentation for it because a couple of month
later I might have forgotten how to use the program and good
structured documentation will tell me within seconds how to use
the program.
<p>Traditional Linux command line utilities have always been
documented in man-pages. A simple <tt>man
<i>commandname</i></tt> will tell you how to use the
command.</p>
<p>The advantage of man-pages over other forms of documentation
is that</p>
<ol>
<li>They can be viewed within seconds in any Linux
terminal</li>
<li>They can easily be converted to other formats: HTML, PDF,
Postscript, Text,...</li>
<li>Man pages can not only be viewed in terminal windows but
also other programs like konqueror (simply type:
man:commandname)</li>
</ol>
<A NAME="309lfindex1"> </A>
<H2>The sections</H2>
Man-pages are structured in sections. Just like a book which is
structured in in chapters. There are e.g two man-pages on
printf. One for the C-library function (section 3) and the
other for the shell command printf (section 1):
<pre class="code">
> whichman -0 printf
/usr/share/man/man1/printf.<b>1.</b>bz2
/usr/share/man/man3/printf.<b>3.</b>bz2
</pre>
The different sections are:
<pre class="code">
Section
1 User commands
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
n New documentation, that may be moved to a more
appropriate section.
l Local documentation referring to this particular system.
</pre>
Therefore typing "man 1 printf" will give you the documentation
about the shell command printf and "man 3 printf" will display
the description of the C-library function. Running just "man
printf" will print the page that is first found (usually printf
from section 1).
<p>To check if there are multiple versions of man pages you can
either use the whichman command as shown above (download from
<a href="http://main.linuxfocus.org/~guido/">my homepage</a> or
you just enter "man:printf" in konqueror and it will tell you:
<br>
<center>
<img src="../../common/images/article309/konqueror.gif" width=
"549" height="389"></p>
</center>
<A NAME="309lfindex2"> </A>
<H2>MANPATH</H2>
The man command searches the man pages based on the value of
the environment variable MANPATH. Unfortunately many Linux
distributions set this path incorrectly. Often
/usr/lib/perl5/man which contains a rich set of documentation
on all perl functions is not included. You can add it to your
MANPATH (in .bashrc or .tcshrc or ...) like this:
<pre class="code">
Bash:
MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
export MANPATH
Tcsh:
setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
</pre>
After setting the man path you can try "man Pod::Man" to see if
you get one of the pages from perl.
<A NAME="309lfindex3"> </A>
<H2>The formatting keywords</H2>
To write a man page is very simple. It is a simple make-up
language where keywords for the markup language start with a
dot at the beginning of the line. These keywords are also
called macros. The most important macros are:
<pre class="code">
.TH -> This starts the title/header of the man page
.SH -> Section heading
.PP -> New paragraph
." -> A comment line
.TP -> Indent the text that comes 2 lines after this macro
</pre>
<br>
<br>
The syntax of .TH is:<br>
.TH [name of program] [section number] [center footer] [left
footer] [center header] <br>
<br>
The syntax of .SH is:<br>
.SH text for a heading<br>
<br>
<br>
The syntax of .PP is very straight forward. It just causes a
line break. <br>
<br>
I find it sometimes useful to include pre-formatted text for
program code examples. This can be done with:
<pre class="code">
.nf
_your_pre_fromatted_
_text_goes_here_____
.fi
</pre>
Note that these are groff/nroff macros and do as such not
belong to the special man-page macros. They seem however to
work fine on all Unix systems.
<p>All man-page formatter macros are documented in the man-page
called groff_man(7) (<a href=
"../../common/src/article309/groff_man_7.html">Click here to
view a html version of the groff_man(7) page</a>). I will not
explain the macros here instead suggest to read the groff_man
page. The groff_man page is very detailed and contains all you
need to know.</p>
<A NAME="309lfindex4"> </A>
<H2>The chapters</H2>
Before we start to write our own page you should know that man
pages are normally structured in chapters. By convention the
possible chapter headings are as follows:
<pre class="code">
NAME Name section, the name of the function or command.
SYNOPSIS Usage.
DESCRIPTION General description
OPTIONS Should include options and parameters.
RETURN VALUES Sections two and three function calls.
ENVIRONMENT Describe environment variables.
FILES Files associated with the subject.
EXAMPLES Examples and suggestions.
DIAGNOSTICS Normally used for section 4 device interface
diagnostics.
ERRORS Sections two and three error and signal handling.
SEE ALSO Cross references and citations.
STANDARDS Conformance to standards if applicable.
BUGS Gotchas and caveats.
SECURITY CONSIDERATIONS
Security issues to be aware of.
other Customized headers may be added at the authors
discretion.
</pre>
<A NAME="309lfindex5"> </A>
<H2>A sample man-page</H2>
Here is a small sample man-page. Note that the \- is required
to make the dash distinct from hyphens. Type all that into your
text editor, and save it as cdspeed.1.
<pre class="code">
.TH cdspeed 1 "September 10, 2003" "version 0.3" "USER COMMANDS"
.SH NAME
cdspeed \- decrease the speed of you cdrom to get faster access time
.SH SYNOPSIS
.B cdspeed
[\-h] [\-d device] \-s speed
.SH DESCRIPTION
Modern cdrom drives are too fast. It can take several seconds
on a 60x speed cdrom drive to spin it up and read data from
the drive. The result is that these drives are just a lot slower
than a 8x or 24x drive. This is especially true if you are only
occasionally (e.g every 5 seconds) reading a small file. This
utility limits the speed and makes the drive more responsive
when accessing small files.
.PP
cdspeed makes the drive also less noisy and is very useful if
you want to listen to music on your computer.
.SH OPTIONS
.TP
\-h
display a short help text
.TP
\-d
use the given device instead of /dev/cdrom
.TP
\-s
set the speed. The argument is a integer. Zero means restore maximum
speed.
.SH EXAMPLES
.TP
Set the maximum speed to 8 speed cdrom:
.B cdspeed
\-s 8
.PP
.TP
Restore maximum speed:
.B cdspeed
\-s 0
.PP
.SH EXIT STATUS
cdspeed returns a zero exist status if it succeeds to change to set the
maximum speed of the cdrom drive. Non zero is returned in case of failure.
.SH AUTHOR
Guido Socher (guido (at) linuxfocus.org)
.SH SEE ALSO
eject(1)
</pre>
Click <a href="../../common/src/article309/cdspeed.html">here
(cdspeed.html)</a> to view the above page.
<A NAME="309lfindex6"> </A>
<H2>Viewing and formatting your man-page</H2>
While writing you man-page you should from time to time view it
to see that it looks right. Type:
<pre class="code">
nroff -man your_manpagefile.1 | less
</pre>
or
<pre class="code">
groff -man -Tascii your_manpagefile.1 | less
</pre>
To convert a man page to plain pre-formatted text (e.g for
spell checking) use:
<pre class="code">
nroff -man your_manpagefile.1 | col -b > xxxx.txt
</pre>
To convert it to Postscript (for printing or further conversion
to pdf) use:
<pre class="code">
groff -man -Tps your_manpagefile.1 > your_manpagefile.ps
</pre>
To convert the man page to html use:
<pre class="code">
man2html your_manpagefile.1
</pre>
<A NAME="309lfindex7"> </A>
<H2>Using perl POD to generate man-pages</H2>
I know that many people feel that it is strange to just edit a
man-page in a text editor. They want to generate the man page.
The perl POD documentation format is a good choice. You can
write the page in POD syntax and then run the command
<pre class="code">
pod2man your_manpagefile.pod > your_manpagefile.1
</pre>
The syntax of the perl pod documentation language is described
in a man page called perlpod. The above man page example would
look in pod format as shown below. Note that POD is sensitive
to space and the empty lines around the "=head" are also
needed.
<pre class="code">
=head1 NAME
cdspeed - decrease the speed of you cdrom to get faster access time
=head1 SYNOPSIS
cdspeed [-h] [-d device] -s speed
=head1 DESCRIPTION
Modern cdrom drives are too fast. It can take several seconds on a 60x
speed cdrom drive to spin it up and read data from the drive. The result
is that these drives are just a lot slower than a 8x or 24x drive.
This is especially true if you are only occasionally (e.g every 5 seconds)
reading a small file. This utility limits the speed and makes the drive
more responsive when accessing small files.
cdspeed makes the drive also less noisy and is very useful
if you want to listen to music on your computer.
=head1 OPTIONS
B<-h> display a short help text
B<-d> use the given device instead of /dev/cdrom
B<-s> set the speed. The argument is a integer. Zero
means restore maximum speed.
=head1 EXAMPLES
Set the maximum speed to 8 speed cdrom:
cdspeed -s 8
Restore maximum speed:
cdspeed -s 0
=head1 EXIT STATUS
cdspeed returns a zero exist status if it succeeds to
change to set the maximum speed of the cdrom drive. Non
zero is returned in case of failure.
=head1 AUTHOR
Guido Socher
=head1 SEE ALSO
eject(1)
</pre>
<A NAME="309lfindex8"> </A>
<H2>References</H2>
<ul>
<li><a href=
"http://www.schweikhardt.net/man_page_howto.html">Man-page
HOWTO</a></li>
<li><a href=
"../../common/src/article309/groff_man_7.html">groff_man(7),
man-page macros</a></li>
</ul>
<!-- 2pdaIgnoreStart -->
<A NAME="talkback"> </a>
<h2>Talkback form for this article</h2>
Every article has its own talkback page. On this page you can submit a comment or look at comments from other readers:
<center>
<table border="0" CELLSPACING="2" CELLPADDING="1" summary="tb-button-outerpart">
<tr BGCOLOR="#C2C2C2"><td align=center>
<table border="3" CELLSPACING="2" CELLPADDING="1" summary="tb-button">
<tr BGCOLOR="#C2C2C2"><td align=center>
<A href="http://cgi.linuxfocus.org/cgi-bin/lftalkback?anum=309"><b> talkback page </b></a>
</td></tr></table>
</td></tr></table>
</center>
<HR size="2" noshade>
<a style="background-color:#bdc6d5" href="index.shtml"><--, back to the index of this issue </a><br><HR size="2" noshade>
<!-- ARTICLE FOOT -->
<CENTER><TABLE WIDTH="98%" summary="footer">
<TR><TD ALIGN=CENTER BGCOLOR="#bdc6d5" WIDTH="50%">
<A HREF="../../common/lfteam.html">Webpages maintained by the LinuxFocus Editor team</A>
<BR><FONT COLOR="#FFFFFF">© Guido Socher, <a href="../../common/copy.html">FDL</a> <BR><a href="http://www.linuxfocus.org">LinuxFocus.org</a></FONT>
</TD>
<TD BGCOLOR="#bdc6d5">
<!-- TRANSLATION INFO -->
<font size=2>Translation information:</font>
<TABLE summary="translators">
<tr><td><font size="2">en --> -- : Guido Socher (<a href="http://linuxfocus.org/~guido/"><font size="1">homepage</font></a>)</font></td></tr>
</TABLE>
</TD>
</TR></TABLE></CENTER>
<p><font size=1>2003-09-14, generated by lfparser version 2.38</font></p>
<!-- 2pdaIgnoreStop -->
</BODY>
</HTML>