CTS 2322 (Unix/Linux Administration II) Project
Creating a man page, using RCS

 

Due: by the start of class on the date shown on the syllabus

Background:  Man Pages

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 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 must 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 should add the following to their login scripts (assuming their man page repository is ~/man):

  export MANPATH=$MANPATH:~/man

Background:  RCS

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.  Currently CVS is the source code control system of choice for most projects (including sourceforge.net), 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 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, and 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$”.

Description:

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.

Requirements:

  1. Login to your YborStudent account.  The initial part of the project should be done there.
  2. Examine the man pages for the commands 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.)
  3. Write a man page using 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”.
  4. What is the name of the man page file you created?  What directory contains your man page?  What changes to your login script did you need to make (if any), so that the man command can locate your man page?
  5. Now that the initial version of your man page is complete, you should check it into an RCS repository using the steps below.  (See the RCS sample session for additional details of how to do these steps.)
  6. Create a subdirectory called RCS (“~/RCS”).
  7. Next copy your 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.

  8. By default 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.
  9. Now you need to create a second version of your man page for second version of the 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.
  10. Add the following RCS keyword somewhere in your man page (this is case-sensitive):
    $Id$

    This can be placed in a nroff comment, or in some section (so the version shows up when the page is viewed).

  11. Once your man page is completed you should check in the final version.  Use the command 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.
  12. What happened to the "$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?
  13. Next copy your man page and the RCS file (from the repository) from YborStudent to your HCC lab computer.  What command did you use to copy your script?
  14. Become root on your system.  Copy the man page to the correct system directory for locally installed commands and man pages.  What is the absolute pathname of the installed man page?  What permissions should this man page have?
  15. Decide on a good location for the RCS repository, and copy the todo.1,v file there.  What is the pathname of your RCS repository?  What permissions should it have?
  16. As root run the 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.
  17. Update your system journal to show the installed file(s) and any configuration file changes you've made.

todo command description, version #1

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.

Example use of todo command, version 1:

   $ todo

      1  Buy some milk
      2  Walk the dog
      3  Empty garbage before dad flips
   $ 

todo command description, version #2

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.

Example use of 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
   $ 

To be turned in:

The final version of the todo.1,v 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.

You can send as email to (preferred).  If email is a problem for some reason, you may turn in a hard-copy.  In this case the pages should be readable, dated, and stapled together.  Your name should appear on the first page.

Please see your syllabus for more information about submitting projects.

Hints:

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.