Mercurial > emacs

--- a/man/woman.texi	Fri Oct 27 00:52:06 2006 +0000
+++ b/man/woman.texi	Fri Oct 27 11:58:10 2006 +0000
@@ -91,7 +91,6 @@
 @menu
 * Introduction::        Introduction
 * Background::          Background
-* Installation::        Installation and Setup
 * Finding::             Finding and Formatting Man Pages
 * Browsing::            Browsing Man Pages
 * Customization::       Customization
@@ -127,7 +126,7 @@
 @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
@@ -145,7 +144,7 @@

 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/files/woman.status,
 @file{woman.status}}.
@@ -169,7 +168,7 @@

 @c ===================================================================

-@node Background, Installation, Introduction, Top
+@node Background, Finding, Introduction, Top
 @comment  node-name,  next,  previous,  up
 @chapter Background
 @cindex background
@@ -178,31 +177,31 @@
 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 @acronym{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
@@ -214,8 +213,8 @@
 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
@@ -228,7 +227,7 @@
 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
@@ -236,7 +235,7 @@
 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
@@ -253,22 +252,22 @@
 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.''

@@ -288,227 +287,18 @@
 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.
+debugging purposes.

-@code{NROFF} simulates non-@acronym{ASCII} characters by using one or more
+@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
@@ -572,19 +362,18 @@

 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:
@@ -834,7 +623,7 @@
 @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
@@ -1070,15 +859,12 @@
 @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
@@ -1385,7 +1171,7 @@

 @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
@@ -1395,8 +1181,8 @@
 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

@@ -1417,8 +1203,8 @@

 @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!

@@ -1494,7 +1280,7 @@
 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}.

@@ -1514,7 +1300,7 @@
 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