Homepage: http://centaur.maths.qmul.ac.uk/Emacs/WoMan
Author: Francis J. Wright
Browse UN*X manual pages `wo (without) man'
WoMan implements a subset of the formatting performed by the Emacs
`man' (or `manual-entry') command to format a UN*X manual `page'
for display, but without calling any external programs. It is
intended to emulate the whole of the -man macro package, plus those
?roff requests that are most commonly used in man pages. However,
the emulation is modified to include the reformatting done by the
Emacs `man' command. No hyphenation is performed.
Advantages
Much more direct, does not require any external programs.
Supports completion on man page names.
Disadvantages
Not a complete emulation. Currently no support for eqn or tbl.
Slightly slower for large man pages (but usually faster for
small- and medium-size pages).
This browser works quite well on simple well-written man files. It
works less well on idiosyncratic files that `break the rules' or
use the more obscure ?roff requests directly. Current test results
are available in the file woman.status.
WoMan supports the use of compressed man files via
`auto-compression-mode' by turning it on if necessary. But you may
need to adjust the user option `woman-file-compression-regexp'.
Read on for (currently) the only documentation for WoMan!
See also the documentation for the WoMan interactive commands and
user option variables, all of which begin with the prefix `woman-'.
This can be done most easily by loading WoMan and then running the
command `woman-mini-help', or selecting the WoMan menu option `Mini
Help' when WoMan is running.
WoMan is still under development! Please let me know what doesn't
work -- I am adding and improving functionality as testing shows
that it is necessary. See below for guidance on reporting bugs.
Recommended use
===============
Either (1 -- *RECOMMENDED*): If the `MANPATH' environment
variable is set then WoMan will use it; otherwise you may need to
reset the Lisp variable `woman-manpath', and you may also want to
set the Lisp variable `woman-path'. Please see the online
documentation for these variables. Now you can execute the
extended command `woman', enter or select a manual entry topic,
using completion, and if necessary select a filename, using
completion. By default, WoMan suggests the word nearest to the
cursor in the current buffer as the topic.
Or (2): Execute the extended command `woman-find-file' and enter a
filename, using completion. This mode of execution may be useful
for temporary files outside the standard UN*X manual directory
structure.
Or (3): Put the next two sexpr's in your .emacs:
(autoload 'woman-dired-find-file "woman"
"In dired, run the WoMan man-page browser on this file." t)
(add-hook 'dired-mode-hook
(lambda ()
(define-key dired-mode-map "W" 'woman-dired-find-file)))
and open the directory containing the man page file using dired,
put the cursor on the file, and press `W'.
In each case, the result should (!) be a buffer in Man mode showing
a formatted manual entry. When called from WoMan, Man mode should
work as advertised, but modified where necessary in the context of
WoMan. (However, `Man' will still invoke the standard Emacs
manual-browsing facility rather than `WoMan' -- this is
intentional!)
(By default, WoMan will automatically define the dired keys "W" and
"w" when it loads, but only if they are not already defined. This
behavior is controlled by the user option `woman-dired-keys'.
Note that the `dired-x' (dired extra) package binds
`dired-copy-filename-as-kill' to the key "w" (as pointed out by Jim
Davidson), although "W" appears to be really unused. The `dired-x'
package will over-write the WoMan binding to "w", whereas (by
default) WoMan will not overwrite the `dired-x' binding.)
Using the word at point as the default topic
============================================
The `woman' command uses the word nearest to point in the current
buffer as the default topic to look up if it matches the name of a
manual page installed on the system. The default topic can also be
used without confirmation by setting the user-option
`woman-use-topic-at-point' to t; thanks to Benjamin Riefenstahl for
suggesting this functionality.
The variable `woman-use-topic-at-point' can be rebound locally,
which may be useful to provide special private key bindings, e.g.
(global-set-key "\C-cw"
(lambda ()
(interactive)
(let ((woman-use-topic-at-point t))
(woman)))))
Customization, Hooks and Imenu
==============================
WoMan supports the GNU Emacs customization facility, and puts
a customization group called `woman' in the `help' group under the
top-level `emacs' group.
WoMan currently runs two hooks: `woman-pre-format-hook' immediately
before formatting a buffer and `woman-post-format-hook' immediately
after formatting a buffer. These hooks can be used for special
customizations that require code to be executed, etc., although
most customization should be possible by setting WoMan user option
variables, e.g. in `.emacs' and should NOT require the use of the
hooks. `woman-pre-format-hook' might be appropriate for face
customization, whereas `woman-post-format-hook' might be
appropriate for installing a dynamic menu using `imenu' (although
it is better to use the built-in WoMan imenu support).
The WoMan menu provides an option to make a contents menu for the
current man page (using imenu). Alternatively, if you set the
variable `woman-imenu' to t then WoMan will do it automatically
for every man page. The menu title is the value of the variable
`woman-imenu-title', which is "CONTENTS" by default. By default,
the menu shows manual sections and subsections, but you can change
this by changing the value of `woman-imenu-generic-expression'.
This facility is not yet widely tested and may be fooled by obscure
man pages that `break the rules'.
WoMan is configured not to replace spaces in an imenu *Completion*
buffer. For further documentation of the use of imenu, such as
menu sorting, see the source file imenu.el, which is distributed
with GNU Emacs.
Howard Melman made (essentially) the following suggestions, which
are slightly different from the expression that I currently use.
You may prefer one of Howard's suggestions, which I think assume
that `case-fold-search' is t (which it is by default):
(setq woman-imenu-generic-expression
'((nil "^\\( \\)?\\([A-Z][A-Z ]+[A-Z]\\)[ \t]*$" 2)))
will give support for .SH and .SS, though it won't show the heading
name hierarchy. If you just want .SH in the imenu then use:
(setq woman-imenu-generic-expression
'((nil "^\\([A-Z][A-Z ]+[A-Z]\\)[ \t]*$" 1)))
Vertical spacing and blank lines
================================
The number of consecutive blank lines in the formatted buffer
should be either 0 or 1. A blank line should leave a space like
.sp 1 (p. 14). Current policy is to output vertical space only
immediately before text is output.
Horizontal and vertical spacing and resolution
==============================================
WoMan currently assumes 10 characters per inch horizontally, hence
a horizontal resolution of 24 basic units, and 5 lines per inch
vertically, hence a vertical resolution of 48 basic units. (nroff
uses 240 per inch).
The *WoMan-Log* buffer
======================
This is modeled on the byte-compiler. It logs all files formatted
by WoMan, and if WoMan finds anything that it cannot handle then it
writes a warning to this buffer. If the variable `woman-show-log'
is non-nil (by default it is nil) then WoMan automatically
displays this buffer. Many WoMan warnings can be completely
ignored, because they are reporting the fact that WoMan has ignored
requests that it is correct to ignore. In some future version this
level of paranoia will be reduced, but not until WoMan is more
reliable. At present, all warnings should be treated with some
suspicion. Uninterpreted escape sequences are also logged (in some
cases).
Uninterpreted ?roff requests can optionally be left in the
formatted buffer to indicate precisely where they occur by
resetting the variable `woman-ignore' to nil (by default it is
t).
Automatic initiation of woman decoding
(Probably not a good idea. If you use it, be careful!)
Put something like this in your .emacs. The call to
set-visited-file-name is to avoid font-locking triggered by
automatic major mode selection.
(autoload 'woman-decode-region "woman")
(setq format-alist
(cons
'(man "UN*X man-page source format" "\\.\\(TH\\|ig\\) "
woman-decode-region nil nil
(lambda (arg)
set-visited-file-name
(file-name-sans-extension buffer-file-name)))))
format-alist))
Reporting Bugs
==============
If WoMan fails completely, or formats a file incorrectly
(i.e. obviously wrongly or significantly differently from man) or
inelegantly, then please
(a) check that you are running the latest version of woman.el
available from my web site (see above),
(b) check that the problem is not already described in the file
woman.status, also available from my web site.
If both of the above are true then please email me the entry from
the *WoMan-Log* buffer relating to the problem file, together with
a brief description of the problem. Please indicate where you got
the source file from, but do not send it to me unless I ask you to!
Thanks. (There is at present no automated bug-reporting facility
for WoMan.)
NOTE:
CASE-DEPENDENCE OF FILENAMES. By default, WoMan ignores case in
file pathnames only when it seems appropriate. MS-Windows users
who want complete case independence should set the NTEmacs variable
`w32-downcase-file-names' to t and use all lower case when
setting WoMan file paths.
(1) INCOMPATIBLE CHANGE! WoMan no longer uses a persistent topic
cache by default. (It caused too much confusion!) Explicitly set
the variable `woman-cache-filename' to save the cache between Emacs
sessions. This is recommended only if the command `woman' is too
slow the first time that it is run in an Emacs session, while it
builds its cache in main memory, which MAY be VERY slow.
(2) The user option `woman-cache-level' controls the amount of
information cached (in main memory and, optionally, saved to disc).
(3) UPDATING THE CACHE. A prefix argument always causes the
`woman' command (only) to rebuild its topic cache, and to re-save
it to `woman-cache-filename' if this variable has a non-nil value.
This is necessary if the NAMES (not contents) of any of the
directories or files in the paths specified by `woman-manpath' or
`woman-path' change. If WoMan user options that affect the cache
are changed then WoMan will automatically update its cache file on
disc (if one is in use) the next time it is run in a new Emacs
session.
TO DO
=====
Reconsider case sensitivity of file names.
MUST PROCESS .if, .nr IN ORDER ENCOUNTERED IN FILE! (rcsfile, mf).
Allow general delimiter in `\v', cf. `\h'.
Improve major-mode documentation.
Pre-process conditionals in macro bodies if possible for speed?
Emulate more complete preprocessor support for tbl (.TS/.TE)
Emulate some preprocessor support for eqn (.EQ/.EN)
Re-write filling and adjusting code!
Allow word wrap at comma (for long option lists)?
Buffer list handling not quite right.
Make 10 or 12 pitch (cpi) optional -- 12 => ll = 78
Use unpaddable space for tabbing?
Tidy up handling of fonts when filling and adjusting
-- see text/text properties?
Improve speed
Add font-lock support (for quoted strings, etc.)?
Optionally save large files in enriched format?
Add apropos facility by searching NAME (?) entry in man files?
Documentation -- optional auto-display of formatted WoMan man page?
Implement a bug reporter?
Support diversion and traps (to some extent) - for Tcl/tk pages?
Add a menu of WoMan buffers?
Fix .fc properly?
Implementation strategy [this description is now well out of date!]
-- three main passes, each to process respectively:
1) non-breaking `.' requests including font macros
2) \ escape sequences, mainly special characters and font changes
3) breaking `.' requests, mainly filling and justification
For each pass, a control function finds and pre-processes the
escape or request and then calls the appropriate function to
perform the required formatting. Based originally on enriched.el
and format.el.
The background information that made this project possible is
freely available courtesy of Bell Labs from
http://cm.bell-labs.com/7thEdMan/
Acknowledgments
===============
For Heather, Kathryn and Madelyn, the women in my life
(although they will probably never use it)!
I also thank the following for helpful suggestions, bug reports,
code fragments, general interest, etc.:
Jari Aalto
Dean Andrews
Juanma Barranquero
Karl Berry
Jim Chapman
Kin Cho
Frederic Corne
Peter Craft
Charles Curley
Jim Davidson
Kevin D'Elia
John Fitch
Hans Frosch
Guy Gascoigne-Piggford
Brian Gorka
Nicolai Henriksen
Thomas Herchenroeder
Alexander Hinds
Stefan Hornburg
Theodore Jump
David Kastrup
Paul Kinnucan
Jonas Linde
Andrew McRae
Howard Melman
Dennis Pixton
T. V. Raman
Bruce Ravel
Benjamin Riefenstahl
Kevin Ruland
Tom Schutter
Wei-Xue Shi
Fabio Somenzi
Karel Sprenger
Chris Szurgot
Paul A. Thompson
Arrigo Triulzi
Geoff Voelker
Eli Zaretskii