Manual pages are the most common UNIX online documentation format.
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
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.
Man pages are used for documentation
on all flavors of UNIX including Linux. Manual pages are useful on non-UNIX systems, as
UNIX-trained hackers forced to develop on Windoze like to try to
establish a livable working environment with shells and tools from UNIX.
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
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.
which searches for ls in any volume;
which searches for ascii in volume 5 only;
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.
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
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
These features come for free, from operating within the Multivalent
- highlighting, as well as many more kinds of annotation
- multiple browser instances
- 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:
- full-text search (will pick up general system's, when it's implemented)
- statistics (times page read, last time, ...)
- 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!
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.
- handle Solaris subvolumes better (e.g., 1s, not just 1)
- handle .nf .. .fi (monospaced) regions better
- support language-specific subdirectories of pages
- 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
Last update: $Date: 2001/12/16 20:48:14 $