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
man pages.
Other options include info documents, and documents in any
format (text, HTML, PostScript, ...) in
/usr/share/doc.
It is also common to have brief help displayed when the user of your
command uses it wrongly, or asks for help with a “-h”
or “--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 macros.
This allows 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 foo.1.gz.
The Gnu 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 nroff).
So you can't see the actual file contents this way.
Use less -L, or more or vi instead.
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 /usr/share/man (historically
they were in /usr/man) or in /usr/local/man.
The list of standard locations is in /etc/man.config
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 /usr/local/man.
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
subdirectory.
For regular user commands (section 1), put their man pages in
.../man/man1.
For files, DLLs, administrator commands, etc.,
use (or create if not present) the appropriately
named subdirectory
(man<section number>).
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
use "man -k keyword"
or "apropos keyword"
to locate the command.
As root the mandb (or makewhatis)
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 ~/bin),
they can create a directory or man page repository
to hold the corresponding
man pages: ~/man.
(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
look.
MANPATH should list the top directory (such as
~/man) and not the directory where the man page
is (such as ~/man/man1).
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
~/man):
export MANPATH=$(manpath):~/man
This is probably not be needed on modern Linux systems, as man
should already look in ~/man/ by default!
(In fact, setting this variable may cause man to
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
directory.
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 “,v” appended
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
“$keyword$”.
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 1.0
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 1.1.
Finally you will use various RCS commands to see the
log of changes and to see the differences between the first and
second versions.
See a RCS sample
session that used RCS when creating a
nusers shell script.
Also review the following man pages:
rcsdemo, ci, co,
rlog, and rcsdiff.
/usr/!) ls,
date, and 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 sudo have
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 -man macros
for the first version of the todo
command 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
“MANPATH”.
/usr/*, so just put it under your home directory some place.
man command can locate your man page
under your home directory?
RCS
(“~/RCS”). todo.1 man 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.
ci removes 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. todo
command 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. $Id$
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.1 to 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 co command later. $Id$" keyword you added?
What is the output of the rlog todo.1 command?
What is the output of the rcsdiff -r1.0 todo.1
command? todo.1,v file there.
What is the pathname of your
RCS repository?
What permissions should it have?
Ensure you have RCS installed on your system.
mandb command 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 apropos and/or the whatis
command to locate your newly installed man page.
If this didn't work try the mandb command again
with different options, or examine the man system
configuration file to make sure man is looking in the
correct directories for your man pages.
Then try apropos again.
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
~/.todo file.
The display will include adding line numbers to the output.
todo command, version 1:
$ todo
1 Buy some milk
2 Walk the dog
3 Empty garbage before dad flips
$
If the 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 ~/.todo file.
The command will also take a single optional argument of
“-h”, which will display a help message.
todo command, 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 todo.1,v
RCS file.
(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
command configuration).
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
See the col(1) man page for more information.
Also see the man page resources on our class syllabus.