by Guido Socher (homepage)
About the author:
Guido likes Linux because it is a very flexible and offers much more possibilities than any other operating system.
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.
Traditional Linux command line utilities have always been documented in man-pages. A simple man commandname will tell you how to use the command.
The advantage of man-pages over other forms of documentation is that
> whichman -0 printf /usr/share/man/man1/printf.1.bz2 /usr/share/man/man3/printf.3.bz2The different sections are:
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.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).
To check if there are multiple versions of man pages you can
either use the whichman command as shown above (download from
my homepage or
you just enter "man:printf" in konqueror and it will tell you:
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"After setting the man path you can try "man Pod::Man" to see if you get one of the pages from perl.
.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
.nf _your_pre_fromatted_ _text_goes_here_____ .fiNote 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.
All man-page formatter macros are documented in the man-page called groff_man(7) (Click here to view a html version of the groff_man(7) page). 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.
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.
.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)Click here (cdspeed.html) to view the above page.
nroff -man your_manpagefile.1 | lessor
groff -man -Tascii your_manpagefile.1 | lessTo convert a man page to plain pre-formatted text (e.g for spell checking) use:
nroff -man your_manpagefile.1 | col -b > xxxx.txtTo convert it to Postscript (for printing or further conversion to pdf) use:
groff -man -Tps your_manpagefile.1 > your_manpagefile.psTo convert the man page to html use:
pod2man your_manpagefile.pod > your_manpagefile.1The 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.
=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)
Webpages maintained by the LinuxFocus Editor team
© Guido Socher, FDL
2003-09-14, generated by lfparser version 2.38