- Manual pages in Linux,
- Different sections of the man page,
- Several formatting options of the man page,
- How to write manual pages in Linux,
- Linking man pages
Need for Man Pages
Linux provides several commands, many system calls, administrative tools & daemons etc. It is not easy for a Linux user to remember all the usages of all the features provided by Linux. To deal with this and make every user of Linux comfortable and convenient to use its features, Linux provides a built-in utility of manual pages for all its features.
In general, not only for man pages, there is always a need for good documentation of manual pages as
- More documentation means easier usage
- More documentation means better add-on modules
- Happier users
- As soon as a user stuck trying to get a command or Linux utility to work, the user can quickly refer to the manual pages in a quick time to troubleshoot the problem.
- Creating well structured and well-written documentation will make it easy for the user to get that feature to work.
Man pages can be accessible by using ‘man’ followed by the command name, for which the manual to be searched. Man pages are generally located at /usr/share/man directory. There are often subdirectories named manx, where x are sections of manual pages, that will be described in the next section. All the manual pages are generally compressed in gun zip format.
The standard sections of the manual pages are:
Section 1
User Commands that could be used by any user from the shell
Section 2
System Calls, these are the several interfaces (API’s) provided by the kernel to enter special privileged mode from the user mode.
Section 3
C Library Functions; these are the standard library routines, used by applications.
Section 4
Devices and Special Files, this section talks about the device files (/dev) and special files in Linux file system.
Section 5
File Formats and Conventions, files having special format are dealt in this section.
Ex: /etc/password
Section 6
Games
Section 7
Miscellaneous, macro packages and conventions
Section 8
System Administration tools and Daemons, these are the tools that only the system admin/root can use, and this section also documents the different system daemons that runs in Linux (like crond)
A man page can be formatted with few several sections with headers, text could be highlighted bold or italic, indented, paragraphed etc. Following are few of the formatting options available in Linux:
.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
.B Bold
.BI Bold alternating with italics
.BR Bold alternating with Roman
.I Italics
.IB Italics alternating with bold
.IR Italics alternating with Roman
.RB Roman alternating with bold
.RI Roman alternating with italics
.SM Small (scaled 9/10 of the regular size)
.SB Small bold (not small alternating with bold)
X alternating with Y means that the odd arguments are typeset in X while the even arguments are typeset in Y.
For example
.BI "Arg 1 is Bold, " "Arg 2 is Italics, " "and Bold, " "and Italics."
For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:
.BI "myfunction(int " argc ", char **" argv );
Filenames are always in italics, except in the SYNOPSIS section, where included files are in bold.
.I /usr/include/stdio.h and .B #include
Special macros, which are usually in upper case, are in bold:
.B MAXINT
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:
.TP
.B EBADF
.I fd is not a valid file descriptor.
.TP
.B EINVAL
.I fd is unsuitable for reading
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:
.BR man (7)
Acronyms look best when typeset in small type face. So I recommend
.SM UNIX
.SM ASCII
.SM TAB
.SM NFS
.SM LALR(1)
Any man page in Linux will have most of the following standard sections.
Title
This displays the title of the man page
The syntax of .TH is:
.TH [name of program] [section number] [center footer] [left footer] [center header]
EX:
.TH STRCMP 3 1993-04-11 "" "Linux Programmer's Manual"
Name
This section contains the name of the man page that this man page will be accessed with. 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
Ex:
.SH NAME
strcmp, strncmp \- compare two strings
SYNOPSIS
This section 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.
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int strcmp(const char *" s1 ", const char *" s2 );
.sp
.BI "int strncmp(const char *" s1 ", const char *" s2 ", size_t " n );
.fi
DESCRIPTION
This section contains all the description about the purpose of the command, system call or the library routine, and its format.
.SH DESCRIPTION
The
.BR strcmp ()
function compares the two strings \fIs1\fP and
\fIs2\fP.
It returns an integer less than, equal to, or greater
than zero if \fIs1\fP is found, respectively, to be less than,
to match, or be greater than \fIs2\fP.
.PP
The
.BR strncmp ()
function is similar, except it only compares
the first (at most) \fIn\fP characters of \fIs1\fP and \fIs2\fP.
OPTIONS
This section gives a brief description of all the options provided by this command.
FILES
Lists files the program or function uses. For example, it lists configuration files, startup files, and files the program directly operates on.
ENVIRONMENT
.This section lists all environment variables that affect the command/function. Most commonly the variables will hold pathnames, filenames or default options.
DIAGNOSTICS
This secition gives an overview of the most common error messages on using/executing the command/system call.
BUGS
This section discusses about the bugs of the command/function if any. Ideally this section shouldn’t exist.
AUTHOR
This section contains the author name who implemented the command/function. It is also nice to have names of people who fixed bugs in the command, and also name of the one who maintains the code.
.SH AUTHOR
Written by Paul Rubin and David MacKenzie.
SEE ALSO
This section lists commands/functions of related man pages in alphabetical order.
.SH "SEE ALSO"
.BR bcmp (3),
.BR memcmp (3),
.BR strcasecmp (3),
.BR strcoll (3),
.BR strncasecmp (3),
.BR wcscmp (3),
.BR wcsncmp (3)
.SH
This page is part of release 3.09 of the Linux
.I man-pages
project.
A description of the project,
and information about reporting documentation bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
A screen shot of man page of whatis command is shown below:
To view the man page, type: man whatis in shell.
Man Page Location
Man page for whatis is located in man1 (1 is the command section) directory under the standard man pages directory /usr/share/man in gunzip format whatis.1.gz
Script for whatis Man Page
To view the whatis script, unzip the whatis.1.gz using gunzip command to a local directory.
.TH whatis 1 "September 19, 2005"
.LO 1
.SH NAME
whatis \- search the whatis database for complete words.
.SH SYNOPSIS
.BI whatis
keyword ...
.SH DESCRIPTION
whatis searches a set of database files containing short descriptions
of system commands for keywords and displays the result on the
standard output. Only complete word matches are displayed.
The whatis database is created using the command /usr/sbin/makewhatis.
.SH AUTHOR
John W. Eaton was the original author of
.BR "man" .
Zeyd M. Ben-Halim released man 1.2, and Andries Brouwer followed up with versions 1.3 thru 1.5p.
Federico Lucifredi
.SH "SEE ALSO"
apropos(1), man(1).
An edited man page can be viewed using a text processor called groff. roff is the general name for a set of type-setting programs, known under names like troff, nroff, ditroff, groff, etc. A roff type-setting system consists of an extensible text formatting language and a set of programs for printing and converting to other text formats. Traditionally, it is the main text processing system of UNIX; every Unix-like operating system still distributes a roff system as a core package.
The most common roff system today is the free software implementation GNU roff, groff(1). groff is the only roff system that is available for every (or almost every) computer system it is the de-facto roff standard today.
groff -man -Tascii whasc.1
groff -man -Tascii whas.1 > whas.ps
While writing a man-page, it can be viewed from time to time using the following roff command:
Type:
nroff -man your_manpagefile.1 less
or
groff -man -Tascii your_manpagefile.1 less
roff also helps to convert the man page to postscript format for printing that man page or further conversion to pdf.
To convert it to Postscript use:
groff -man -Tps your_manpagefile.1 > your_manpagefile.ps
To convert the man page to html use:
man2html your_manpagefile.1
apropos and whatis searches a set of database files (whatis database file: that may be found in each of the manual base directories) containing short descriptions of system commands for keywords and displays the result on the standard output. These 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. The whatis database is created using the command /usr/sbin/makewhatis. In order for makewhatis to be able to extract the NAME sections correctly it is important to adhere to the NAME section format described in the above section.
The differences between apropos and whatis are simply where in the line they look, and what they are looking for. Apropos (which is equivalent to man -k) searches the argument string anywhere on the line, whereas whatis (equivalent to man -f) tries to match a complete command name only on the part before the dash.
makewhatis reads all the manual pages contained in the given sections of manpath or the preformatted pages contained in the given sections of catpath. For each page, it writes a line in the whatis database; each line consists of the name of the page and a short description, separated by a dash. The description is extracted using the content of the NAME section of the manual page.
Since other languages use a different term for the NAME section, make- whatis recognizes the equivalent terms in Czech, Italian, Finnish, French, German and Spanish.
If no manpath argument is given, /usr/man is assumed by default.
Ex:
To rebuild only /usr/X11R6/man/whatis and /usr/local/man/whatis
makewhatis /usr/X11R6/man /usr/local/man
Man pages Installation
On Linux, all man pages are installed (using `make install`) located in the 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 section. Not all of the sections may be represented by a subdirectory because there simply is no reason to keep an empty mano'(others sections) subdirectory. However, there may be directories named cat(s), dvi(s) and ps(s) which hold documentation that is ready to display or print. The only other file in any base directory should be a file named whatis. 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) or in the standard man directory.
A man page could be referred by more than one command in Linux. i.e., a single man page can be written to provide information about more than one command, if these commands are similar.
Ex: grep, egrep, fgrep
- It is time consuming to write man pages individually for these different commands (grep, egrep and fgrep).
- If the options/functionality of these different commands is same, it need not be represented separately
- Having different man pages also consumes unnecessary disk space.
To group the similar commands, manual page for one command could be implemented and the rest of the commands can simply link them.
Ex: egrep’s man page actually contains the below line, which would link to the manual page of grep in section 1.
.so man1/grep.1
Linux Manual Pages
Man Page How to
No comments:
Post a Comment