All commands should be documented, so users can locate a command
and know how to use it.
Once you have written your own commands (or shell scripts) you should
learn to document them correctly.
In Unix the standard location for documentation is the
Other options include info documents, and documents in any
format (text, HTML, PostScript, ...) in
It is also common to have brief help displayed when the user of your
command uses it wrongly, or asks for help with a “
--help” command line argument.
However such documentation is of no use in locating the command in
the first place.
This is why every command you write or add to your system should
have a man page.
Man pages are written using the
nroff text formatting
system and the
man to generate a good-looking man page
for any output device (printer or different terminal emulators)
on the fly.
Man pages once generated may be cached for quick display
the next time.
(This feature is usually not worth using and can be disabled.)
All Unix/Linux man pages have a similar appearance (but not
identical) which is easily created using the macro package.
Take a moment to look at a few man pages and note the format.
Although it is possible to create a plain text man page you should
learn to use
nroff and the standard macros.
Doing this is an objective for some certification exams.
Here is the source for a
sample man page
for the command
nusers, a simple shell script.
You can use this nroff source as a model for your own man pages.
Man pages are named after the command, with an extension to indicate
the manual section and type of file.
Thus the man page for a user command
foo should be called
foo.1, or if compressed
less command has a “feature” that causes it
to detect some file types (such as man page source files), and pre-process
files through filters (such as
So you can't see the actual file contents this way.
less -L, or
Once written the new man page must be placed in the proper location.
For system-wide commands (to be used by people other than just yourself)
man pages are placed under
they were in
/usr/man) or in
The list of standard locations is in
on Linux, or
/usr/share/man/man.cf on Solaris.
This file should be edited to include additional system-wide man page
directories such as
No man pages are placed directly in this top directory.
Instead within this directory are further subdirectories that
correspond to the various sections of the manual.
The actual man page files are placed within the appropriate
For regular user commands (section 1), put their man pages in
For files, DLLs, administrator commands, etc.,
use (or create if not present) the appropriately
Section numbers will vary between Linux and Unix/Solaris.
Also remember that such files and directories must have the correct
permissions so that everyone can access the man pages.
After installing a new system-wide man page in the correct location,
the last step is to rebuild the keyword search index so users can
man -k keyword"
to locate the command.
As root the
command is used to rebuild this database.
(This is normally run from
cron, but if you don't run
it yourself you must wait until
cron runs it before you
can find your new man page with keyword searches.)
For commands that users write themselves (or download and install in
their home directories, say in
they can create a directory or man page repository
to hold the corresponding
(Or use any other name they like.)
For such man pages, the
MANPATH environment variable
may need to be set so that the
man command knows where to
MANPATH should list the top directory (such as
~/man) and not the directory where the man page
is (such as
For commands written or installed by individual users (such as
the shell scripts you write), the users may need add the following
to their login scripts (assuming their man page repository is
This is probably not be needed on modern Linux systems, as
should already look in
~/man/ by default!
(In fact, setting this variable may cause
not look in the standard locations, rendering some
man pages unusable.)
You will also practice using the RCS source code control system, also called a version control system (VCS), a source management system, and other such names. Such systems allow an easy way to keep track of versions of code, to control who can change code, to record why any changes are made, compare different versions, and to retrieve old versions. Previously, CVS was the source code control system of choice for most projects (including sourceforge.net). Today git is more common, but its powerful network and multi-user features make it difficult to learn to use. Another good and powerful (and thus complex) tool is subversion. This system is useful for projects but not system administration, since it doesn't provide versioning on a per file basis.
Traditional VCS have a single repository for a project's files. Here is kept all the history (back versions, log entries, etc.), access control, etc. for the files in that project. Newer, more useful systems don't have a single repository but rather multiple repositories that can be merged as needed. These systems are known as distributed VCS. Some examples include mercurial, bazaar, and of course git.
There are many such systems available. We will use RCS, which is very good but simpler than most other source code management/control systems. (RCS may be simple but is very useful for small groups of users (or for a single user) on a single computer, does versioning on a per file basis, and thus is very suitable for system administration use.)
RCS keeps a repository for each
Just create a sub-directory called “RCS”.
The files that you check in to the repository will be
represented by a single file within that repository, one with
the same name as the file but with “
to the name.
To put a new file into the repository, you do an initial check-in:
ci -i1.0 -u file
Once this is done you can edit the file by checking out a locked
copy, and when done check it back in (remembering to use the
-u” option to check out a new working copy
at the same time.)
Like many VCS, RCS allows special keywords
in the file to be expanded upon check-out.
You can put such keywords in comments to identify the version or
other information about the file.
RCS uses keywords of the form
You will create a couple of versions of a sample man page for a shell script. You don't have to write the script, just the man page for it.
First you will create an initial
version of your man page, then check in this version into
an RCS repository.
You next will check out the man page for editing, make your
final changes (and test them), then check in the modified
version as revision
Finally you will use various RCS commands to see the
log of changes and to see the differences between the first and
See a RCS sample
session that used RCS when creating a
nusers shell script.
Also review the following
sudo, on YborStudent or similar Linux system. What sections (e.g., NAME, DESCRIPTION) do all these man pages have in common? What sections does the man page for
sudohave that the others don't? (Note this question refers to the contents of these man pages, and has nothing to do with their section numbers.)
nroff -manmacros for the first version of the
todocommand described here. Use the man page for the nusers command as a template for your own man pages. Build your man page on YborStudent.hccfl.edu so you can work from either on- or off-campus on this project. When done, test your man page to make sure it displays properly. You may have to make changes to environment variables such as “
/usr/*, so just put it under your home directory some place.
mancommand can locate your man page under your home directory?
todo.1man page to your home directory, then check in the initial version using the command
ci -i1.0 todo.1. You will be asked to provide a description of your man page.
The RCS commands can accept an additional pathname. Besides the file you are checking in (or out), you can supply the pathname to the RCS file. If you use this form of the commands then you don't have to copy the file first, since you can check into or out of any RCS repository and not just the one within the current working directory.
ciremoves the copy of the file you check in. To get a read-only copy back, use the command “
co todo.1”. Note you may have to move the checked-out file to the correct location.
todocommand described here. You must check out a copy of the man page for editing by using the command
co -l todo.1. Now edit the file to make the necessary changes. Test your man page to make sure it displays properly.
This can be placed in a
nroff comment, or in some
section (so the version shows up when the page is viewed).
ci -u todo.1to check in the new version (version
1.1). The "
-u" option says to check out the file at the same time you check it in, so you don't need to use the
$Id$" keyword you added? What is the output of the
rlog todo.1command? What is the output of the
rcsdiff -r1.0 todo.1command?
todo.1,vfile there. What is the pathname of your RCS repository? What permissions should it have?
Ensure you have RCS installed on your system.
mandbcommand to rebuild the man page index. (You should examine the
mandb(8)man page first to see what options to use.) What is the exact command you used? Use the
whatiscommand to locate your newly installed man page. If this didn't work try the
mandbcommand again with different options, or examine the
mansystem configuration file to make sure
manis looking in the correct directories for your man pages. Then try
aproposagain. Repeat until you get it working.
When invoked with no arguments the
todo command displays
(to standard output) all the lines in the current user's
The display will include adding line numbers to the output.
todocommand, version 1:
$ todo 1 Buy some milk 2 Walk the dog 3 Empty garbage before dad flips $
todo command is invoked with any command line
arguments, then instead of printing a list of “to do” items
the command line arguments (i.e., the positional parameters)
should be appended to the user's
The command will also take a single optional argument of
-h”, which will display a help message.
todocommand, version 2:
$ todo 1 Buy some milk 2 Walk the dog 3 Empty garbage before dad flips $ todo Win the lotto $ todo 1 Buy some milk 2 Walk the dog 3 Empty garbage before dad flips 4 Win the lotto $
The final version of the
(Not the man page itself, I want the RCS file.)
Also the answers to the questions above and the journal entries
describing the steps you have taken to create and manage your
man page on your local system (for example, changes to the man
These should be clearly written.
Use Canvas and submit to the project's drop-box.
Please see your syllabus for more information about submitting projects.
You can produce a formatted text-only version of any man page using a pipeline such as this:
LC_ALL=POSIX TERM=dumb man todo | col -bx > todo.txt
col(1) man page for more information.
Also see the man page resources on our class syllabus.