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 a single forward quote. An escape sequences 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 section `Documentation Commands' in

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. The only way in which WoMan affects man is that it adds a timer to indicate how long man has taken to format a man page. The timing is as compatible as possible with the timing built into WoMan, for as fair a comparison as possible. The time comparison seems to depend on the details of the platform, the version of man in use, etc, but times are similar and WoMan is never significantly slower than man. This is despite the fact that WoMan is running byte code whereas most of the formatting done by man uses machine code, and is a testimony to the quality of the Emacs Lisp system.

NROFF simulates non-ASCII characters by using one or more ASCII characters. WoMan should be able to do much better than this. I have recently begun to add support for WoMan to use more of the characters in its default font and to use a symbol font, and it is an aspect that I intend to develop further in the near future. It should be possible to move WoMan from an emulation of NROFF to an emulation of TROFF as GNU Emacs moves to providing bit-mapped display facilities.

mail: