2 Background

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.