Merge from emacs--rel--22
[bpt/emacs.git] / man / woman.texi
index 3eae6dc..868bb51 100644 (file)
@@ -1,10 +1,9 @@
 \input texinfo   @c -*-texinfo-*-
-@c $Id: woman.texi,v 1.11 2002/08/16 06:29:40 eggert Exp $
 @c %**start of header
 @setfilename ../info/woman
 @settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
 @c Manual last updated:
-@set UPDATED Time-stamp: <2002-10-02 16:01:26 karl>
+@set UPDATED Time-stamp: <2006-03-25 14:59:03 karl>
 @c Software version:
 @set VERSION 0.54 (beta)
 @afourpaper
 This file documents WoMan: A program to browse Unix manual pages `W.O.
 (without) man'.
 
-Copyright @copyright{} 2001, 2002 Free Software Foundation, Inc.
+Copyright @copyright{} 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with the Front-Cover texts being ``A GNU
 Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the
@@ -57,8 +57,9 @@ license to the document, as described in section 6 of the license.
 @author Queen Mary and Westfield College
 @author (University of London)
 @author Mile End Road, London E1 4NS, UK
-@author @email{F.J.Wright@@qmw.ac.uk}
+@author @email{F.J.Wright@@qmul.ac.uk}
 @author @uref{http://centaur.maths.qmw.ac.uk/}
+@c He no longer maintains this manual.
 @sp 2
 @author Manual Last Updated @value{UPDATED}
 
@@ -91,7 +92,6 @@ Mile End Road, London E1 4NS, UK
 @menu
 * Introduction::        Introduction
 * Background::          Background
-* Installation::        Installation and Setup
 * Finding::             Finding and Formatting Man Pages
 * Browsing::            Browsing Man Pages
 * Customization::       Customization
@@ -99,6 +99,7 @@ Mile End Road, London E1 4NS, UK
 * Technical::           Technical Details
 * Bugs::                Reporting Bugs
 * Acknowledgements::    Acknowledgements
+* GNU Free Documentation License:: The license for this documentation.
 * Command Index::       Command Index
 * Variable Index::      Variable Index
 * Keystroke Index::     Keystroke Index
@@ -118,15 +119,16 @@ version of Emacs.  It was developed primarily on various versions of
 Microsoft Windows, but has also been tested on MS-DOS, and various
 versions of UNIX and GNU/Linux.
 
-WoMan is distributed with GNU Emacs 21, and the current source code and
-documentation files are available from
-@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web server}.
+WoMan is distributed with GNU Emacs.  In addition, the current source
+code and documentation files are available from
+@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, the WoMan web
+server}.
 
 WoMan implements a subset of the formatting performed by the Emacs
 @code{man} (or @code{manual-entry}) command to format a Unix-style
 @dfn{manual page} (usually abbreviated to @dfn{man page}) for display,
 but without calling any external programs.  It is intended to emulate
-the whole of the @code{ROFF -man} macro package, plus those @code{ROFF}
+the whole of the @code{roff -man} macro package, plus those @code{roff}
 requests (@pxref{Background, , Background}) that are most commonly used
 in man pages.  However, the emulation is modified to include the
 reformatting done by the Emacs @code{man} command.  No hyphenation is
@@ -144,9 +146,9 @@ 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 @code{ROFF} requests directly.  Current test results
+the more obscure @code{roff} requests directly.  Current test results
 are available in the file
-@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/woman.status,
+@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/files/woman.status,
 @file{woman.status}}.
 
 WoMan supports the use of compressed man files via
@@ -168,7 +170,7 @@ Reporting Bugs}.
 
 @c ===================================================================
 
-@node Background, Installation, Introduction, Top
+@node Background, Finding, Introduction, Top
 @comment  node-name,  next,  previous,  up
 @chapter Background
 @cindex background
@@ -177,31 +179,31 @@ WoMan is a browser for traditional Unix-style manual page documentation.
 Each such document is conventionally referred to as a @dfn{manual page},
 or @dfn{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.  @code{NROFF} and @code{TROFF} are text processors
+macros, which are themselves written in the nroff/troff text processing
+markup language.  @code{nroff} and @code{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 @dfn{ROFF}.
+is important I will refer to them both ambiguously as @code{roff}.
 
-@code{ROFF} markup consists of @dfn{requests} and @dfn{escape
+@code{roff} markup consists of @dfn{requests} and @dfn{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 @code{ROFF} requests
+original man macro package defines 20 new @code{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 @code{ROFF}
+macros, in practice a significant number use many other @code{roff}
 requests.
 
-The distinction between @code{TROFF} and @code{NROFF} is that
-@code{TROFF} was designed to drive a phototypesetter whereas
-@code{NROFF} was designed to produce essentially @sc{ascii} output for a
+The distinction between @code{troff} and @code{nroff} is that
+@code{troff} was designed to drive a phototypesetter whereas
+@code{nroff} was designed to produce essentially @acronym{ASCII} output for a
 character-based device similar to a teletypewriter (usually abbreviated
-to ``teletype'' or ``tty'').  Hence, @code{TROFF} supports much finer
-control over output positioning than does @code{NROFF} and can be seen
+to ``teletype'' or ``tty'').  Hence, @code{troff} supports much finer
+control over output positioning than does @code{nroff} and can be seen
 as a forerunner of @TeX{}.  Traditionally, man pages are either
-formatted by @code{TROFF} for typesetting or by @code{NROFF} for
+formatted by @code{troff} for typesetting or by @code{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
@@ -213,8 +215,8 @@ Nevertheless, Unix-style manual page documentation is still normally
 browsed on screen by running a program called @code{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
-@code{NROFF} or recovers a pre-formatted file, and displays it via a
-pager such as @code{more}.  @code{NROFF} normally formats for a printer,
+@code{nroff} or recovers a pre-formatted file, and displays it via a
+pager such as @code{more}.  @code{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
@@ -227,7 +229,7 @@ command, see @ref{Documentation, man, Documentation Commands, emacs, GNU
 Emacs Manual}.
 This command runs @code{man} as described above, perhaps in
 the background, and then post-processes the output to remove much of the
-@code{NROFF} pagination such as page headers and footers, and places the
+@code{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
@@ -235,7 +237,7 @@ 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 @code{NROFF} paginate a
+There is considerable inefficiency in having @code{nroff} paginate a
 document and then removing most of the pagination!
 
 WoMan is an Emacs Lisp library that provides an emulation of the
@@ -252,22 +254,22 @@ with Unix-style manual page documentation.  This may be difficult to
 read because ports of the Unix-style @code{man} program can be a little
 awkward to set up.  I decided that it should not be too hard to emulate
 the 20 @code{man} macros directly, without treating them as macros and
-largely ignoring the underlying @code{ROFF} requests, given the text
+largely ignoring the underlying @code{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
-@code{ROFF} requests in addition to the @code{man} macros, and since
+@code{roff} requests in addition to the @code{man} macros, and since
 releasing the first version of WoMan I have been continually extending
-it to support more @code{ROFF} requests.  WoMan can now format a
+it to support more @code{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 @code{ROFF} requests that cannot be handled
+recursion.  There are some @code{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.''
 
@@ -287,227 +289,18 @@ WoMan has (this) texinfo documentation!
 WoMan @emph{does not} replace @code{man}, although it does use a number
 of the facilities implemented in the Emacs @code{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 @code{man} is
-that it adds a timer to indicate how long @code{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 @code{man} in use, etc, but times are similar and WoMan is never
-significantly slower than @code{man}.  This is despite the fact that
-WoMan is running byte code whereas most of the formatting done by
-@code{man} uses machine code, and is a testimony to the quality of the
-Emacs Lisp system.
-
-@code{NROFF} simulates non-@sc{ascii} characters by using one or more
-@sc{ascii} characters.  WoMan should be able to do much better than
+debugging purposes.
+
+@code{nroff} simulates non-@acronym{ASCII} characters by using one or more
+@acronym{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 @code{NROFF} to an
-emulation of @code{TROFF} as GNU Emacs moves to providing bit-mapped
+be possible to move WoMan from an emulation of @code{nroff} to an
+emulation of @code{troff} as GNU Emacs moves to providing bit-mapped
 display facilities.
 
-@c ===================================================================
-
-@node Installation, Finding, Background, Top
-@comment  node-name,  next,  previous,  up
-@chapter Installation and Setup
-@cindex installation
-@cindex setup
-
-No installation is necessary if you just want to run the version of
-WoMan distributed with GNU Emacs 21 or later, although some additional
-setup may still be desirable.
-
-If you are installing @file{woman.el}, either to update the version
-distributed with GNU Emacs or because WoMan was not distributed with
-your version of Emacs, then you need to put the file in a directory in
-your Emacs load path and byte compile it.  A good directory to use is
-the @file{site-lisp} directory in your Emacs file tree, e.g.@:
-@file{/usr/local/share/emacs/@var{version}/site-lisp/} (where
-@var{version} is your Emacs version), provided you have write access to
-it.  If you use a directory that is not included by default in your
-Emacs load path then you need to add something like this to your
-@file{.emacs} initialization file:
-
-@lisp
-(add-to-list 'load-path "my-lisp")
-@end lisp
-
-@noindent
-where @file{my-lisp} is the pathname of the directory.  @xref{Init File, ,
-The Init File ~/.emacs, emacs, The Emacs Editor}, for further details on
-customizing Emacs in general.
-
-You can byte-compile the file by using the Emacs command
-@code{byte-compile-file} or by opening the directory containing the
-file, putting point on it and pressing the key @kbd{B}.  (In fact, if
-the file is compiled then it is only the compiled file that needs to be
-in the Emacs load path, but leaving the source file there will do no
-harm.)
-
-@heading Setup
-
-Setup that is either necessary or desirable consists of adding a small
-amount of Emacs Lisp code to your @file{.emacs} initialization file.  It
-may be necessary (or at least convenient) to make WoMan autoload (if you
-are not running GNU Emacs 21 or later) and to set the search path used
-by the @code{woman} interface.  You may also find it convenient to make
-various WoMan menu and key bindings available and to make WoMan
-customizable even before WoMan has been loaded.
-
-It is possible to run WoMan from a command line (from outside or even
-from inside Emacs) by suitably configuring your command interpreter.
-
-@menu
-* Autoloading::         Autoloading
-* Search Path::         Search Path
-* Auto Bindings::       Preloading Menu and Key Bindings
-* Auto Customization::  Preloading Customization
-* Command Line::        Command Line Access
-@end menu
-
-
-@node Autoloading, Search Path, Installation, Installation
-@comment  node-name,  next,  previous,  up
-@section Autoloading
-@cindex autoloading
-
-If you are not running GNU Emacs 21 or later then you are recommended to
-add these autoloads to your @file{.emacs} file:
-
-@lisp
-(autoload 'woman "woman"
-  "Decode and browse a Unix man page." t)
-(autoload 'woman-find-file "woman"
-  "Find, decode and browse a specific Unix man-page file." t)
-(autoload 'woman-dired-find-file "woman"
-  "In dired, run the WoMan man-page browser on this file." t)
-@end lisp
-
-@noindent
-(In GNU Emacs 21 and later these autoloads are predefined.)
-
-
-@node Search Path, Auto Bindings, Autoloading, Installation
-@comment  node-name,  next,  previous,  up
-@section Search Path
-@cindex search path
-
-The next step is necessary if you want to use the friendliest WoMan
-interface, which is recommended in general.  If the @code{MANPATH}
-environment variable is set then WoMan will use it; alternatively (or
-additionally), if your platform uses a man configuration file (as do
-many versions of Linux) then WoMan will use it, provided it can find it.
-(This may need configuration.  @xref{Interface Options, , Interface
-Options}.)  If these mechanisms correctly define the search path for man
-pages then no further action is required.
-
-Otherwise you may need to customize the user option
-@code{woman-manpath}, and you may also want to customize the user option
-@code{woman-path}.  @xref{Customization, , Customization}.  Now you can
-execute the extended command @code{woman} and enter or select a manual
-topic using completion, and if necessary select a filename, again using
-completion.  By default, WoMan suggests the word nearest to point in the
-current buffer as the topic.
-
-
-@node Auto Bindings, Auto Customization, Search Path, Installation
-@comment  node-name,  next,  previous,  up
-@section Preloading Menu and Key Bindings
-@cindex preloading menu and key bindings
-@cindex menu bindings, preloading
-@cindex key bindings, preloading
-@cindex bindings, preloading
-
-Once WoMan is loaded it adds an item to the @samp{Help} menu and defines
-one or more keys in dired mode to run WoMan on the current file.  If you
-would like these facilities always to be available, even before WoMan is
-loaded, then add the following to your @file{.emacs} file:
-
-@lisp
-(define-key-after menu-bar-manuals-menu [woman]
-  '(menu-item "Read Man Page (WoMan)..." woman
-              :help "Man-page documentation Without Man") t)
-
-(add-hook 'dired-mode-hook
-          (lambda ()
-            (define-key dired-mode-map "W" 'woman-dired-find-file)))
-@end lisp
-
-(By default, WoMan will automatically define the dired keys @kbd{W} and
-@kbd{w} when it loads, but only if they are not already defined.  This
-behavior is controlled by the user option @code{woman-dired-keys}.
-Note that the @code{dired-x} (dired extra) package binds
-@code{dired-copy-filename-as-kill} to the key @kbd{w}, although @kbd{W}
-appears to be unused.  The @code{dired-x} package will over-write the
-WoMan binding for @kbd{w}, whereas (by default) WoMan will not overwrite
-the @code{dired-x} binding.)
-
-
-@node Auto Customization, Command Line, Auto Bindings, Installation
-@comment  node-name,  next,  previous,  up
-@section Preloading Customization
-@cindex preloading customization
-@cindex customization, preloading
-
-WoMan supports the GNU Emacs 20+ customization facility, and puts a
-customization group called @code{WoMan} in the @code{Help} group under
-the top-level @code{Emacs} group.  In order to be able to customize
-WoMan without first loading it, add the following to your @file{.emacs}
-file:
-
-@lisp
-(defgroup woman nil
-  "Browse UNIX manual pages `wo (without) man'."
-  :tag "WoMan" :group 'help :load "woman")
-@end lisp
-
-
-@node Command Line,  , Auto Customization, Installation
-@comment  node-name,  next,  previous,  up
-@section Command Line Access
-@cindex command line access
-
-If you really want to square the man-woman circle then you can!  If you
-run the GNU command interpreter @code{bash} then you might care to
-define the following @code{bash} function in your @code{bash}
-initialization file @file{.bashrc}:
-
-@example
-man() @{ gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; @}
-@end example
-
-If you use a Microsoft command interpreter (@file{command.com} or
-@file{cmd.exe}) then you can create a file called @file{man.bat}
-somewhere in your path containing the two lines:
-
-@example
-@@echo off
-gnudoit -q (raise-frame (selected-frame)) (woman \"%1\")
-@end example
-
-and then (e.g.@: from a command prompt or the @samp{Run...} option in the
-Windows @samp{Start} menu) just execute
-
-@example
-man man_page_name
-@end example
-
-(Of course, if you already have a @code{man} command installed then you
-could call these commands @code{woman} instead of @code{man}.)
-
-The above examples assume that you have the @code{gnuserv} Emacs
-client-server package installed (which I recommend).  It would be
-possible to do something similar by calling Emacs directly, but that is
-less satisfactory, because you are likely to end up with multiple copies
-of Emacs running, which is generally inelegant, inefficient and
-inconvenient.  If you run a different command interpreter then something
-similar to the above suggestions should be possible.
-
-@c ===================================================================
-
-@node Finding, Browsing, Installation, Top
+@node Finding, Browsing, Background, Top
 @comment  node-name,  next,  previous,  up
 @chapter Finding and Formatting Man Pages
 @cindex using, finding man pages
@@ -571,19 +364,18 @@ setting WoMan file paths.
 
 The topic interface is accessed principally via the command
 @code{woman}.  The same command can be accessed via the menu item
-@samp{Help->Manuals->Read Man Page (WoMan)...} either once WoMan has been
-loaded or if it is set up specially.  @xref{Installation, , Installation
-and Setup}.  The command reads a manual topic in the minibuffer, which
-can be the @dfn{basename} of a man file anywhere in the man file
-structure.  The ``basename'' in this context means the filename without
-any directory component and without any extension or suffix components
-that relate to the file type.  So, for example, if there is a compressed
-source file in Chapter 5 of the UNIX Programmer's Manual with the full
-pathname @file{/usr/local/man/man5/man.conf.5.gz} then the topic is
-@code{man.conf}.  Provided WoMan is configured correctly, this topic
-will appear among the completions offered by @code{woman}.  If more than
-one file has the same topic name then WoMan will prompt for which file
-to format.  Completion of topics is case insensitive.
+@samp{Help->Manuals->Read Man Page (WoMan)...} once WoMan has been
+loaded.  The command reads a manual topic in the minibuffer, which can
+be the @dfn{basename} of a man file anywhere in the man file
+structure.  The ``basename'' in this context means the filename
+without any directory component and without any extension or suffix
+components that relate to the file type.  So, for example, if there is
+a compressed source file in Chapter 5 of the UNIX Programmer's Manual
+with the full pathname @file{/usr/local/man/man5/man.conf.5.gz} then
+the topic is @code{man.conf}.  Provided WoMan is configured correctly,
+this topic will appear among the completions offered by @code{woman}.
+If more than one file has the same topic name then WoMan will prompt
+for which file to format.  Completion of topics is case insensitive.
 
 Clearly, @code{woman} has to know where to look for man files and there
 are two customizable user options that store this information:
@@ -595,9 +387,9 @@ WoMan tries to pick up the information that would be used by the
 UNIX, then WoMan parses that.  Otherwise, if WoMan can find a
 configuration file named (by default) @file{man.conf} (or something very
 similar), which seems to be the standard mechanism under GNU/Linux, then
-it parses that.  To be precise, ``something very similar'' means having
-two name components separated by a dot and respectively containing
-@samp{man} and beginning with @samp{conf}, e.g.@: @file{manual.configuration}.
+it parses that.  To be precise, ``something very similar'' means
+starting with @samp{man} and ending with @samp{.conf} and possibly more
+lowercase letters, e.g.@: @file{manual.configuration}.
 The search path and/or precise full path name for this file are set by
 the value of the customizable user option @code{woman-man.conf-path}.
 If all else fails, WoMan uses a plausible default man search path.
@@ -616,7 +408,10 @@ elements of @code{woman-path} must be directories that contain man files
 @emph{directly}.  Secondly, the last directory component of each element
 of @code{woman-path} is treated as a regular (Emacs) match expression
 rather than a fixed name, which allows collections of related
-directories to be specified succinctly.
+directories to be specified succinctly.  Also, elements of
+@code{woman-manpath} can be conses, indicating a mapping from
+@samp{PATH} environment variable components to man directory
+hierarchies.
 
 For topic completion to work, WoMan must build a list of all the manual
 files that it can access, which can be very slow, especially if a
@@ -686,24 +481,22 @@ time it is run in a new Emacs session.
 @cindex point, word at
 
 By default, the @code{woman} command uses the word nearest to point in
-the current buffer as a suggestion for the topic to look up.  The topic
-must be confirmed or edited in the minibuffer.  This suggestion can be
-turned off, or @code{woman} can use the suggested topic without
-confirmation if possible, which is controlled by customizing the user
-option @code{woman-topic-at-point} to @code{nil} or @code{t}
-respectively.  (Its default value is neither @code{nil} nor @code{t},
-meaning ask for confirmation.)
-
-The variable @code{woman-topic-at-point} can also be rebound locally
-(using @code{let}), which may be useful to provide special private key
-bindings, e.g.@: this key binding for @kbd{C-c w} runs WoMan on the topic
-at point without seeking confirmation:
+the current buffer as a suggestion for the topic to look up, if it
+exists as a valid topic.  The topic can be confirmed or edited in the
+minibuffer.
+
+You can also bind the variable @code{woman-use-topic-at-point} locally
+to a non-@code{nil} value (using @code{let}), in which case
+@code{woman} will can use the suggested topic without confirmation if
+possible.  This may be useful to provide special private key bindings,
+e.g.@: this key binding for @kbd{C-c w} runs WoMan on the topic at
+point without seeking confirmation:
 
 @lisp
 (global-set-key "\C-cw"
                 (lambda ()
                   (interactive)
-                  (let ((woman-topic-at-point t))
+                  (let ((woman-use-topic-at-point t))
                     (woman))))
 @end lisp
 
@@ -766,7 +559,7 @@ primarily used internally by WoMan.
 Emacs provides an interface to detect automatically the format of a file
 and decode it when it is visited.  It is used primarily by the
 facilities for editing rich (i.e.@: formatted) text, as a way to store
-formatting information transparently as @sc{ascii} markup.  WoMan can in
+formatting information transparently as @acronym{ASCII} markup.  WoMan can in
 principle use this interface, but it must be configured explicitly.
 
 This use of WoMan does not seem to be particularly advantageous, so it
@@ -833,7 +626,7 @@ blank lines squeezed to a single blank line.
 @cindex fonts
 @cindex faces
 
-Fonts used by @code{ROFF} are handled by WoMan as faces, the details of
+Fonts used by @code{roff} are handled by WoMan as faces, the details of
 which are customizable.  @xref{Faces, , Faces}.  WoMan supports both the
 italic and bold fonts normally used in man pages, together with a single
 face to represent all unknown fonts (which are occasionally used in
@@ -1069,15 +862,12 @@ is distributed with GNU Emacs.
 @chapter Customization
 @cindex customization
 
-All WoMan user options are customizable, and it is recommended to change
-them only via the standard Emacs customization facilities.  WoMan
-defines a top-level customization group called @code{WoMan} under the
-parent group @code{Help}.  The WoMan customization group is available
-only once WoMan has been loaded unless it is specially set up to be
-automatically available.  @xref{Auto Customization, , Preloading
-Customization}.  It can be accessed either via the standard Emacs
-facilities, e.g.@: via the @samp{Help->Customize} submenu, or via the
-WoMan major mode menu.
+All WoMan user options are customizable, and it is recommended to
+change them only via the standard Emacs customization facilities.
+WoMan defines a top-level customization group called @code{WoMan}
+under the parent group @code{Help}.  It can be accessed either via the
+standard Emacs facilities, e.g.@: via the @samp{Help->Customize}
+submenu, or via the WoMan major mode menu.
 
 The top-level WoMan group contains only a few general options and three
 subgroups.  The hooks are provided only for special purposes that, for
@@ -1155,7 +945,9 @@ A list of strings representing @emph{directory trees} to search for Unix
 manual files.  Each element should be the name of a directory that
 contains subdirectories of the form @file{man?}, or more precisely
 subdirectories selected by the value of @code{woman-manpath-man-regexp}.
-Non-directory and unreadable files are ignored.
+Non-directory and unreadable files are ignored.  This can also contain
+conses, with the car indicating a @code{PATH} variable component mapped
+to the directory tree given in the cdr.
 
 @cindex @code{MANPATH}, environment variable
 If not set then the environment variable @code{MANPATH} is used.  If no
@@ -1298,24 +1090,18 @@ a Contents menu to the menubar by calling @code{imenu-add-to-menubar}.
 A string representing the title to use if WoMan adds a Contents menu to
 the menubar.  Default is @code{"CONTENTS"}.
 
-@item woman-topic-at-point
-A symbol, which may be either @code{t}, @code{nil} or @code{confirm},
-that controls the use by @code{woman} of the ``word at point'' as a
-topic suggestion.  If it is non-@code{nil} then the @code{woman} command uses
-the word at point as an initial topic suggestion when it reads a topic
-from the minibuffer; if it is @code{t} then @code{woman} uses the word
-at point @emph{without interactive confirmation} if it exists as a
-topic.  The value @code{confirm} means suggest a topic and ask for
-confirmation.  The default value is that of
-@code{woman-topic-at-point-default}.
-
-@item woman-topic-at-point-default
-A symbol, which may be either @code{t}, @code{nil} or @code{confirm},
-representing the default value for @code{woman-topic-at-point}.  The
-default value is @code{confirm}.  [The variable
-@code{woman-topic-at-point} may be @code{let}-bound when @code{woman} is
-loaded, in which case its global value does not get defined.  The
-function @code{woman-file-name} sets it to this value if it is unbound.]
+@item woman-use-topic-at-point
+A boolean value that defaults to @code{nil}.  If non-@code{nil} then
+the @code{woman} command uses the word at point as the topic,
+@emph{without interactive confirmation}, if it exists as a topic.
+
+@item woman-use-topic-at-point-default
+A boolean value representing the default value for
+@code{woman-use-topic-at-point}.  The default value is @code{nil}.
+[The variable @code{woman-use-topic-at-point} may be @code{let}-bound
+when @code{woman} is loaded, in which case its global value does not
+get defined.  The function @code{woman-file-name} sets it to this
+value if it is unbound.]
 
 @item woman-uncompressed-file-regexp
 A regular match expression used to select man source files (ignoring any
@@ -1329,9 +1115,9 @@ The SysV standard man pages use two character suffixes, and this is
 becoming more common in the GNU world.  For example, the man pages in
 the @code{ncurses} package include @file{toe.1m}, @file{form.3x}, etc.
 
-@strong{Note:} an optional compression regexp will be appended, so this
-regexp @emph{must not} end with any kind of string terminator such as
-@code{$} or @code{\\'}.
+@strong{Please note:} an optional compression regexp will be appended,
+so this regexp @emph{must not} end with any kind of string terminator
+such as @code{$} or @code{\\'}.
 
 @item woman-file-compression-regexp
 A regular match expression used to match compressed man file extensions
@@ -1384,18 +1170,18 @@ headings.  Default is @code{t}.  [Heading emboldening is @emph{not} standard
 
 @item woman-ignore
 A boolean value.  If non-@code{nil} then unrecognised requests etc. are
-ignored.  Default is @code{t}.  This gives the standard @code{ROFF} behavior.
+ignored.  Default is @code{t}.  This gives the standard @code{roff} behavior.
 If @code{nil} then they are left in the buffer, which may aid debugging.
 
 @item woman-preserve-ascii
-A boolean value.  If non-@code{nil} then preserve @sc{ascii} characters in the
-WoMan buffer.  Otherwise, non-@sc{ascii} characters (that display as
-@sc{ascii}) may remain, which is irrelevant unless the buffer is to be
+A boolean value.  If non-@code{nil} then preserve @acronym{ASCII} characters in the
+WoMan buffer.  Otherwise, non-@acronym{ASCII} characters (that display as
+@acronym{ASCII}) may remain, which is irrelevant unless the buffer is to be
 saved to a file.  Default is @code{nil}.
 
 @item woman-emulation
-WoMan emulation, currently either @code{NROFF} or @code{TROFF}.  Default
-is @code{NROFF}.  @code{TROFF} emulation is experimental and largely
+WoMan emulation, currently either @code{nroff} or @code{troff}.  Default
+is @code{nroff}.  @code{troff} emulation is experimental and largely
 untested.
 @end vtable
 
@@ -1416,8 +1202,8 @@ either colors or different fonts.
 
 @item woman-italic-face
 Face for italic font in man pages.  Default: italic, underlined,
-foreground red.  This is overkill!  @code{TROFF} uses just italic;
-@code{NROFF} uses just underline.  You should probably select either
+foreground red.  This is overkill!  @code{troff} uses just italic;
+@code{nroff} uses just underline.  You should probably select either
 italic or underline as you prefer, but not both, although italic and
 underline work together perfectly well!
 
@@ -1445,7 +1231,7 @@ This section currently applies @emph{only} to Microsoft Windows.
 
 WoMan provides partial experimental support for special symbols,
 initially only for MS-Windows and only for MS-Windows fonts.  This
-includes both non-@sc{ascii} characters from the main text font and use
+includes both non-@acronym{ASCII} characters from the main text font and use
 of a separate symbol font.  Later, support will be added for other font
 types (e.g.@: @code{bdf} fonts) and for the X Window System.  In Emacs
 20.7, the current support works partially under Windows 9x but may not
@@ -1453,7 +1239,7 @@ work on any other platform.
 
 @vtable @code
 @item woman-use-extended-font
-A boolean value.  If non-@code{nil} then WoMan may use non-@sc{ascii} characters
+A boolean value.  If non-@code{nil} then WoMan may use non-@acronym{ASCII} characters
 from the default font.  Default is @code{t}.
 
 @item woman-use-symbol-font
@@ -1493,7 +1279,7 @@ At present, all warnings should be treated with some suspicion.
 Uninterpreted escape sequences are also logged (in some cases).
 
 By resetting the variable @code{woman-ignore} to @code{nil} (by default
-it is @code{t}), uninterpreted @code{ROFF} requests can optionally be
+it is @code{t}), uninterpreted @code{roff} requests can optionally be
 left in the formatted buffer to indicate precisely where they occurred.
 @xref{Interface Options, , Interface Options}.
 
@@ -1513,7 +1299,7 @@ left in the formatted buffer to indicate precisely where they occurred.
 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.
-(@code{NROFF} uses 240 per inch.)
+(@code{nroff} uses 240 per inch.)
 
 @heading Vertical spacing and blank lines
 
@@ -1549,7 +1335,7 @@ man source file from, but do not send it unless asked to send it.
 
 @c ===================================================================
 
-@node Acknowledgements, Command Index, Bugs, Top
+@node Acknowledgements, GNU Free Documentation License, Bugs, Top
 @comment  node-name,  next,  previous,  up
 @chapter Acknowledgements
 @cindex acknowledgements
@@ -1605,7 +1391,12 @@ Eli Zaretskii, @email{eliz@@is.elta.co.il}
 @comment END OF MANUAL TEXT
 @page
 
-@node Command Index, Variable Index, Acknowledgements, Top
+
+@node GNU Free Documentation License, Command Index, Acknowledgements, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Command Index, Variable Index, GNU Free Documentation License, Top
 @comment  node-name,           next,      previous,  up
 @unnumbered Command Index
 
@@ -1642,3 +1433,7 @@ Eli Zaretskii, @email{eliz@@is.elta.co.il}
 @printindex cp
 
 @bye
+
+@ignore
+   arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028
+@end ignore