woman: Background
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
man (emacs)Documentation. 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.
Info Catalog
woman: Introduction
woman: Top
woman: Finding