WoMan is a browser for traditional Unix-style manual page documentation.
Each such document is conventionally referred to as a manual page,
or man page for short, even though some are very much longer than
one page. A man page is a document written using the Unix “man”
macros, which are themselves written in the nroff/troff text processing
markup language. nroff and troff are text processors
originally written for the UNIX operating system by Joseph F. Ossanna at
Bell Laboratories, Murray Hill, New Jersey, USA. They are closely
related, and except in the few cases where the distinction between them
is important I will refer to them both ambiguously as roff.
roff markup consists of requests and escape
sequences. A request occupies a complete line and begins with either a
period or an apostrophe. An escape sequence is embedded
within the input text and begins (by default) with a backslash. The
original man macro package defines 20 new roff requests
implemented as macros, which were considered to be sufficient for
writing man pages. But whilst in principle man pages use only the man
macros, in practice a significant number use many other roff
requests.
The distinction between troff and nroff is that
troff was designed to drive a phototypesetter whereas
nroff was designed to produce essentially ASCII output for a
character-based device similar to a teletypewriter (usually abbreviated
to “teletype” or “tty”). Hence, troff supports much finer
control over output positioning than does nroff and can be seen
as a forerunner of TeX. Traditionally, man pages are either
formatted by troff for typesetting or by nroff for
printing on a character printer or displaying on a screen. Of course,
over the last 25 years or so, the distinction between typeset output on
paper and characters on a screen has become blurred by the fact that
most screens now support bit-mapped displays, so that any information
that can be printed can also be rendered on screen, the only difference
being the resolution.
Nevertheless, Unix-style manual page documentation is still normally
browsed on screen by running a program called man. This program
looks in a predefined set of directories for the man page matching a
specified topic, then either formats the source file by running
nroff or recovers a pre-formatted file, and displays it via a
pager such as more. nroff normally formats for a printer,
so it paginates the output, numbers the pages, etc., most of which is
irrelevant when the document is browsed as a continuous scrollable
document on screen. The only concession to on-screen browsing normally
implemented by the man program is to squeeze consecutive blank
lines into a single blank line.
For some time, Emacs has offered an improved interface for browsing man
pages in the form of the Emacs man (or manual-entry)
command, see Documentation Commands in GNU
Emacs Manual.
This command runs man as described above, perhaps in
the background, and then post-processes the output to remove much of the
nroff pagination such as page headers and footers, and places the
result into an Emacs buffer. It puts this buffer into a special major
mode, which is tailored for man page browsing, and provides a number of
useful navigation commands, support for following references, etc. It
provides some support for special display faces (fonts), but no special
menu or mouse support. The Emacs man package appears to have been
developed over about 10 years, from the late 1980s to the late 1990s.
There is considerable inefficiency in having nroff paginate a
document and then removing most of the pagination!
WoMan is an Emacs Lisp library that provides an emulation of the
functionality of the Emacs man command, the main difference being
that WoMan does not use any external programs. The only situation in
which WoMan might use an external program is when the source file is
compressed, when WoMan will use the standard Emacs automatic
decompression facility, which does call an external program.
I began developing WoMan in the Spring of 1997 and the first version was
released in May 1997. The original motivation for WoMan was the fact
that many GNU and Unix programs are ported to other platforms and come
with Unix-style manual page documentation. This may be difficult to
read because ports of the Unix-style man program can be a little
awkward to set up. I decided that it should not be too hard to emulate
the 20 man macros directly, without treating them as macros and
largely ignoring the underlying roff requests, given the text
processing capabilities of Emacs. This proved to be essentially true,
and it did not take a great deal of work to be able to format simple man
pages acceptably.
One problem arose with the significant number of man pages that use
roff requests in addition to the man macros, and since
releasing the first version of WoMan I have been continually extending
it to support more roff requests. WoMan can now format a
significant proportion of the man pages that I have tested, either well
or at least readably. However, I have added capabilities partly by
making additional passes through the document, a design that is
fundamentally flawed. This can only be solved by a major re-design of
WoMan to handle the major formatting within a single recursive pass,
rather than the present multiple passes without any significant
recursion. There are some roff requests that cannot be handled
satisfactorily within the present design. Some of these are currently
handled by kludges that “usually more or less work.”
The principle advantage of WoMan is that it does not require man,
and indeed the name WoMan is a contraction of “without man.” But it
has other advantages. It does not paginate the document, so it does not
need to un-paginate it again, thereby saving time. It could take full
advantage of the display capabilities available to it, and I hope to
develop WoMan to take advantage of developments in Emacs itself. At
present, WoMan uses several display faces to support bold and italic
text, to indicate other fonts, etc. The default faces are also
colored, but the choice of faces is customizable. WoMan provides menu
support for navigation and mouse support for following references, in
addition to the navigation facilities provided by man mode.
WoMan has (this) texinfo documentation!
WoMan does not replace man, although it does use a number
of the facilities implemented in the Emacs man library. WoMan
and man can happily co-exist, which is very useful for comparison and
debugging purposes.