File: woman.el.html

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.

Note that M-x woman doesn’t yet support the latest features of modern man pages, so we recommend using M-x man if that is available on your system.

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(var)/auto-compression-mode(fun) 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 this in your init file:
(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(var)/woman-imenu(fun) 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 <jari.aalto@cs.tpu.fi>
  Dean Andrews <dean@dra.com>
  Juanma Barranquero <lekktu@gmail.com>
  Karl Berry <kb@cs.umb.edu>
  Jim Chapman <jchapman@netcomuk.co.uk>
  Kin Cho <kin@neoscale.com>
  Frederic Corne <frederic.corne@erli.fr>
  Peter Craft <craft@alacritech.com>
  Charles Curley <ccurley@trib.com>
  Jim Davidson <jdavidso@teknowledge.com>
  Kevin D'Elia <Kevin.DElia@mci.com>
  John Fitch <jpff@maths.bath.ac.uk>
  Hans Frosch <jwfrosch@rish.b17c.ingr.com>
  Guy Gascoigne-Piggford <ggp@informix.com>
  Brian Gorka <gorkab@sanchez.com>
  Nicolai Henriksen <nhe@lyngso-industri.dk>
  Thomas Herchenroeder <the@software-ag.de>
  Alexander Hinds <ahinds@thegrid.net>
  Stefan Hornburg <sth@hacon.de>
  Theodore Jump <tjump@cais.com>
  David Kastrup <dak@gnu.org>
  Paul Kinnucan <paulk@mathworks.com>
  Jonas Linde <jonas@init.se>
  Andrew McRae <andrewm@optimation.co.nz>
  Howard Melman <howard@silverstream.com>
  Dennis Pixton <dennis@math.binghamton.edu>
  T. V. Raman <raman@Adobe.COM>
  Bruce Ravel <bruce.ravel@nist.gov>
  Benjamin Riefenstahl <benny@crocodial.de>
  Kevin Ruland <kruland@seistl.com>
  Tom Schutter <tom@platte.com>
  Wei-Xue Shi <wxshi@ma.neweb.ne.jp>
  Fabio Somenzi <fabio@joplin.colorado.edu>
  Karel Sprenger <ks@ic.uva.nl>
  Chris Szurgot <szurgot@itribe.net>
  Paul A. Thompson <pat@po.cwru.edu>
  Arrigo Triulzi <arrigo@maths.qmw.ac.uk>
  Geoff Voelker <voelker@cs.washington.edu>
  Eli Zaretskii <eliz@gnu.org>

Defined variables (77)

Defined functions (175)

Defined faces (4)