GNU Info

(woman)Background

---

Next: Installation Prev: Introduction Up: Top

---

Enter node , (file) or (file)node

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
Note: man.  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
coloured, 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.