-M option of the man command can be used to
specify a directory to be searched instead of using the MANPATH.
-M option is especially useful for testing a new
man page you are writing. For example, you could create the
subdirectories man, man/man1, and man/man3 in a project directory
and put the man page for a new command in man/man1/xxx.1 and the man
page for a new library function in man/man3/yyy.3. Then, from the
project directory the command "man -M ./man xxx"
would display the man page for your xxx command and the command
"man -M ./man yyy" would display the man page for
your yyy library function. (Not all projects for this course
involve writing both commands and library functions; write just the
pages that are assigned.)
Man pages are text files, and whatever you put in them will be displayed by the man command. But to get them to look like "real" man pages, they have to be written in a special way, which brings us to the next topic: Text Processing on Unix systems.
There are many programs that perform text formatting on Unix
systems. Most operate as filters that read ASCII characters
from stdin, modify the text layout, and write formatted text
to stdout. The man(1) command itself sets up a
pipeline to pass an ASCII man page (such as
through a series of these filters, which do such things as format
paragraphs to fit on the page properly, indent headings and
sub-headings properly, and even to do such things as formatting
tables and equations that might be embedded in the document. The
crucial point is that the final appearance of a page is controlled by
commands that are embedded in your text file, not by the way you type
the original text. For example, a basic command is ".P" which marks
the beginning of a paragraph. (All commands start with a dot in the
first column of a line.) Once you type a .P command, whatever you
type, until the next command, will be formatted into a nice paragraph
with standard margins and spacing. You can type each word of the
paragraph on a separate line or 100 words per line, and the paragraph
will end up looking the same way. The only way you can mess up the
format of a paragraph is to type extra blanks, which don't get
squeezed out for you.
There is a special set of text formatting commands that you use to write man pages. You can use others as well, but the following list is all you need.
\) is an escape character that tells parts of the man system to treat the next character as a literal rather than as the beginning of a quoted string. Any time you have trouble putting a special character in a man page, you should try preceding it with a backslash.
To adhere to the Coding Guidelines for this course, you must document your man pages just as you document your source code. The first few lines of your man pages will start with something like this, assuming you are using RCS to manage the versions of your project:
.\" $Id$ .\" .\" Man page for the xyz project. .\" .\" $Log$ .\"
.THname section center-footer left-footer center-header
.THare used for the following information:
Use quotes if any of these fields contains embedded blanks. Use "CS-701" as the left-footer for the man pages you write for this course. The main page (center) heading gives the place or organization where the software being documented originated; we'll use "Queens College."
Here is an example:
.TH mycommand 1 "December 2001" "CS-701" "Queens College"
For projects that are done as a sequence of steps, add another section
heading, VERSION, with the RCS
$Revision$ keyword as the
.P This is a sentence in which the word .I word is italicized. Note that using .I does not affect the paragraph formatting.Would be output something like this:
This is a sentence in which the word word is italicized. Note that using .I does not affect the paragraph formatting.