Manual pages are the most common UNIX online documentation format.

Demos

You can see all the manual pages on your system by setting the MANPATH environment variable (and running Java 5). Here are some sample pages that don't require configuration of the MANPATH.

• The manual page for Tk's photo(n) command collapses the page into an outline by section title so that the full scope of the page can be seen at once. Click on an outline heading to open up that section. Very short sections, in this case Name, Synopsis, and Keywords, are flattened, so there is no need to click on them to see their contents.

  Within otherwise collapsed sections, certain lines that are likely to be very important override the outlining. These overrides are Notemarks. Often one calls up a man page in order to recall a command line option, so these are displayed immediately, whereas in other manual page viewers you'd have to scroll for many screens while visually scanning all the while. Click on a Notemark to expand that outline section and scrolls there to read the full information.

• Tcl's regsub(n) is short enough to fit entirely on the screen, so there is no need for outlining.
• man(5) has references to other manual pages, in the See Also section at the bottom of the page. References to pages that actually exist (regardless of section), are shown in blue, and references that to pages that don't exist (which is all of them if you don't have a MANPATH set) are given a overstrike.

Description

The manual page source (roff commands) is interpreted for the highest quality display, in contrast to the standard man command which renders the page in ASCII for a tty terminal. (In fact, you can delete the formatted versions of your man pages in ..../man/catN directories.)

Outlining

Manual page don't have explicit hyperlinks, but likely references to other man pages are made into hyperlinks. Any word can be treated as a man page reference by clicking the alternative mouse button over the word. References to pages that don't exist are given an overstrike, so you don't click on one only to discover that it doesn't exist.

Volume listings are also available, single volume or all, also in a convenient outline form to reduce scrolling. Volume lists can be annotated. For instance, highlight your most-used manual pages, so that they are Notemarks that override collapsed outline sections and therefore can be directly clicked on and viewed.

Of course, it takes advantage of Multivalent system: annotation, bookmarking, searching, history, date last modified, ....

Manual pages and the various volume lists are available from other documents with a simple HTML A tag with the protocol set to manualpage or manpage, or programmatically with an openDocument semantic event. For example, manualpage:ls(1), which searches for ls in any volume; manpage:ascii.5, which searches for ascii in volume 5 only; manpagevol:ALL, which displays the full list of pages. If there are multiple man pages with the same name, a list of links of all matches is given.

Multivalent Comparison with TkMan

The Multivalent Browser replaces dedicated manual page browsers such as xman and even TkMan. (TkMan still works great and is available for free.)

The specialized capabilities of TkMan have / are being / can be translated into generalized Multivalent behaviors. The Multivalent manual page module has not had anywhere near the same amount of work invested, but since it relies on functionality provided by the rest of the system, it didn't need to. For instance, TkMan's highlight is just one of many Multivalent annotation styles, and TkMan's manual page filter is just one of many Multivalent media adaptors.

Clearly better in the Multivalent man page reader:

• Faster, since don't have to exec at least one process (rman, and maybe troff and others) to process pages into Tcl commands strings, which are then parsed and converted back into data structures. We directly interpret the source, without other processes.
• Page reading from source is so fast that no cached formatted ("cat") versions of pages are needed, and hence neither is their messy maintenance.
• More portable and more easily portable, since rely on Java only and not on troff, gzip and other supporting utilities.
• More reliable, since it doesn't rely on other software. Affecting TkMan, glimpse was passed on to a different group for maintenance, and changed the version reporting option to return a system error code! The groff maintainer made a change that broke an option used in formatting with "line lines" (vs for the width of a tty screen) hence the formatting of all new pages (the current version of groff has fixed this). The groff maintainer broke TkMan for a second time by changing the method for indicating bold and italic characters. Tcl/Tk 8.4 disabled the buttons, though that's within its right since TkMan was reaching into Tk's private variable space, which it had to do to implement button-menubuttons.

These features come for free, from operating within the Multivalent framework:

• highlighting, as well as many more kinds of annotation
• outlining
• Notemarks
• bookmarks
• history
• multiple browser instances
• search
• autosearch
• document map
• great text widget (with elision)

These didn't prove to be useful, and are dropped:

• apropos (not useful itself, and to be superceded by full-text search)
• regular expression pattern search on names
• programmable volume groupings (though I used it)
• switchable Paths

These would be too painful to continue to support:

• stray cats
• Direct support for Solaris, HP/UX, IRIX, and OSF/1 -- refer to System-specific Notes to learn how to make your system compatible.
• bzip2 compressed pages (unless someone has a Java implementation of the uncompressor — simply convert to gzip format)

Still to go:

• diagnostics
• full-text search (will pick up general system's, when it's implemented)
• statistics (times page read, last time, ...)
• Texinfo

System-specific Notes

• All systems - When installing a man page, don't simply copy it from the software's distribution format (the .tar or .zip). Always go through its installation procedure, as often it will process the text of the man page source. At this writing, Java doesn't support symbolic links, but the old one-line ".so main page" works fine.
• Solaris 7 and higher now maintains its documentation as SGML, which is in general a good idea. Until SGML is directly supported, you can convert the pages to roff format with catman -c.
• HP/UX has a weird naming scheme in which compressed man pages do not have a compression suffix but their directory does (e.g., .../man/man1.Z/ls.1 is a compressed file). You could convert these directories to a compatible format, however, by renaming the ".Z" from the directories and add ".Z" to all the files therein.
• I hear that Slackware Linux compresses their pages with bzip2. Simply uncompress them, and if you'd like, compress them with gzip, support for which is built into Java.
• Digital UNIX aka OSF/1 aka something else now probably won't work (I haven't tried) as it relies on a huge macro set. Use TkMan instead.
• SGI IRIX supplies manual pages in formatted form only. Tell SGI to get a clue. Use TkMan instead.
• BSD macros aren't supported, at least until someone sends me a list of macros, definitions, and English descriptions.

If you report a missing macro, be sure to supply its definition too!

Status

It works great for most pages. It is not a complete roff interpreter, however, and there are some commands that will be unfamiliar. It does not presently support tables, which are actually relatively rarely used, nor equations (eqn macros), which are hardly ever used, nor registers, which are just plain esoteric. Tables are problematic because different macro sets have different table schemes, but I plan to implement the one defined by GNU tbl.

To do:

• handle Solaris subvolumes better (e.g., 1s, not just 1)
• handle .nf .. .fi (monospaced) regions better
• support language-specific subdirectories of pages

See Also

Related work:

• TkMan
• RosettaMan/PolyglotMan
• GnomeHelp's manual page reader (3735 lines), which internally converts to HTML first and passes to its HTML parser
• The defunct Nautilus, which uses Rosetta... er, PolyglotMan to process pages into HTML
• the primoridial graphical man page browser, xman