COSC 479/592 Assignment 3: A CGI to serve Manual Pages

Background

The Unix Manual Pages are an online documentation facility that goes back to the early days of Unix. The idea is that every command, function, and system file has documentation that can be accessed online in a uniform way while logged into the system. This is done with the man command, which takes the item whose documentation is wanted as an argument. Examples:

• man sort - displays documentation on the sort command
• man man - documentation on the man command itself
• man fgets - documentation on fgets(), a function that can be called from a C program to read a line of input.
• man termcap - documentation on the format of the termcap file, a standard system file that provides a database of terminals and their capabilities

The manual is divided into eight sections as follows:

1. Commands - can be invoked by a user at a shell command prompt
2. System calls - requests for operating system services that can be called from programs
3. Functions - standard functions that can be called from programs
4. Special files and devices
5. File formats and protocols
6. Games
7. Miscellaneous
8. System administration commands

Optionally, you can supply the section number as an argument to man. Sometimes this is necessary to avoid ambiguity. For example, a command might have the same name as a C function.

• man 1 sleep - documentation on the sleep command
• man 3 sleep - documentation on the sleep function

For a description of what is in section N (for N = 1 to 8), type man N intro. This will display an "introduction" to the section.

Different Unix and Linux distributions may organize the manual in somewhat different ways. The section list given above is for the Fedora Core 1 distribution running on our oriole server.

There are two other commands that access the manual page database. The apropos command searches the database and lists manual pages relevant to a keyword. The whatis command gives a one-line summary description rather than the full documentation.

• apropos internet - commands, functions, etc. relevant to the internet
• whatis passwd - brief description of everything named passwd. In this case, the passwd command (for changing your password) and the passwd file (account database).

(In my experience, apropos is a fairly weak search facility that often misses relevant material.)

Assignment

You are to write a Perl CGI that provides a web interface to the manual pages stored on the Oriole server. Minimally, you must implement the following:

• User interface (front end) - a web page with a form that includes a set of eight radio buttons for selecting the manual section, and an input area for typing the name of the desired manual page. The web page should be decently formatted (use a style sheet!) and its contents should make it clear what service is being provided. It should also be valid XHTML 1.1, of course.
• Perl script (back end) - program to parse the form data and serve the specified manual page in HTML format.

The above are minimal requirements for a grade of B. For a shot at a higher grade you can do one or more optional parts, described later.

You may work by yourself or in teams of two people. To level the playing field, a two-person team starts with a grade of C+ for doing just the minimum, so teams must do more to get the same grade as someone working alone.

Since this is a programming assignment, you are expected to follow good practice regarding style, documentation, and readability of the source code.

Implementation considerations

The manual pages are stored under the directory /usr/share/man. The subdirectories man1 through man8 contain manual pages for sections 1 through 8, respectively. Each manual page is stored in a compressed ("gzipped") file whose name consists of the name of the manual page, the section number, and the suffix gz, separated by periods. For example, the path to the manual page for the ls command is /usr/share/man/man1/ls.1.gz.

The gunzip command, with input redirected to such a file, will send its uncompressed contents to the standard output. Try this:

            gunzip < /usr/share/man/man1/ls.1.gz

You'll see the contents of the manual page for ls, interspersed with "troff" markup (e.g. lines that begin with a period) that determine how the man command will display the page on a text-based display screen. This markup is of course not HTML, and a web browser won't be able to interpret it.

Luckily there is a command called man2html that can interpret troff markup and convert it to HTML. Try this:

            gunzip < /usr/share/man/man1/ls.1.gz | man2html

You'll see the ls page with HTML formatting. If you use output redirection to save this in a file in your web directory and then view the file in a browser, it will show up as a well-formatted web version of the ls man page.

Perl can execute shell commands, such as those given above, using the built-in system function, or using back-quotes.

Extras

Here are some things you can do for extra credit. If additional things occur to you that aren't listed here, they might be worth extra credit too, but check with me first to be sure.

• Augment the above user interface by giving the user the option of displaying an index of the names of the commands in a manual section, such that if the user clicks on a name, the manual page is fetched and displayed.
• Build an interface to whatis into your user interface. One suggestion: Use the title attribute to display the whatis information when the user points to the name with the mouse.
• Build an interface to apropos into your user interface.
• Instead of using man2html, write your own Perl code to convert the troff markup to HTML. This will give you full control over the appearance of the manual page on the web. (But it's also a fairly ambitious undertaking -- anybody who does it successfully and produces HTML that is better than that produced by man2html gets a big chunk of extra credit.

As mentioned above, other ideas for enhancing the functionality of all this are welcome.