Easy and pretty display of local manual pages

Manpage.cgi presents manual pages via HTTP. It also renders internal anchors for the sections in the page, links to other manual pages, and the description of options. in the page, links to other manual pages, and the description of options.

To understand this document

It would help a lot if you knew a bit of HTML and how manual pages should be formatted. I wrote 2 other pages to describe how to layout a manual page: manstyle(1l) and ckman(8l). If you read those, then this page will be more clear to you.

There is a lot to me said for having all the documentation for the system commands available to everyone, all the time. Having used many time sharing systems and command-line interfaces in my time, take this an my attestation that there is no substitute for quick and easy access to the up-to-the minute documentation on the screen when you need it.

To that end I coded a simple CGI script to push nroff formatted manual pages into a browser. I did that because the hypertext navigation in a browser complements a terminal session nicely, and one can awlays use lynx when stuck on a serial console. Altenatives like recoding every document in info do not apeal to me. Mostly because that doesn't add any value to the existing work.

The web interface to the old-school manual pages

First we should build hypertext links to the other manual pages, so long as the common format for a reference is used. If we see a bold word followed by a section number in parenthesis we should make it a link to the manual page CGI. So ls(1) should become:
<A href="/cgi-bin/manpage.cgi?ls&amp;1"><b>ls</b>(1)</A>
Rendered as:
ls(1)

Hypertext anchors we might build

When we look at the structure of each manual page we see that there is a lot of information we can data-mine from it to build hypertext anchors. There are sections which we could build internal anchors for (NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, and SEE ALSO). I chose to build the links in that same way that I built them in my own web pages. The sections get the first word in the section name as the anchor:
<b id="OPTIONS">OPTIONS</b>
<b id="SEE">SEE ALSO</b>
Let's also build anchors for the desciption of each command-line option. Each option description should also get an anchor tag opt_letter for the lowercase letters or opt_uLetter for the uppercase Letters. So the options -h and -H get markup like:
<b id="opt_h">-h</b>
<b id="opt_uh">-H</b>

Text format

We can also preserve the underline, italic, bold, and other font markup. So there is should be no loss of information in the transformation to HTML from manual page markup.

Details

We also need to handle hyphenation of manual page names. That was really one of the harder issues to solve. I did 2 things. First I added a hyphenation suppression mark to the SEE ALSO section of all my manual pages, becasue it looks better without the hyphens. Then I fixed the manual page rendered to cleanup the hypertext target on output.

Summary

This CGI allows you to link from any HTML page to a known spot in the online manual system. It is not limited to the top of the page, anchors for sections and option descriptions allow as least some helpful navigation of the pages. See the ckman HTML document.

$Id: manpage.html,v 1.7 2013/05/18 21:42:05 ksb Exp $ by .