\input texinfo @c -*-texinfo-*-
-@c $Id: woman.texi,v 1.2 2000/08/08 10:41:27 eliz Exp $
@c %**start of header
@setfilename ../info/woman
-@settitle WoMan: Browse UN*X Manual Pages ``Wo (without) Man''
+@settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
@c Manual last updated:
-@set UPDATED Time-stamp: <2000-08-08 12:20:51 eliz>
+@set UPDATED Time-stamp: <2006-03-25 14:59:03 karl>
@c Software version:
@set VERSION 0.54 (beta)
@afourpaper
@paragraphindent 0
@c %**end of header
-@dircategory Emacs
-@direntry
-* WoMan: (woman). Browse UN*X Manual Pages `Wo (without) Man'.
-@end direntry
-
-@ifinfo
-This file documents WoMan: A program to browse UN*X manual pages `wo
+@copying
+This file documents WoMan: A program to browse Unix manual pages `W.O.
(without) man'.
-Copyright @copyright{} 2000 Francis J. Wright
-
-This manual and the software that it describes are subject to the GNU
-General Public License that is distributed with GNU Emacs -- see the
-file @file{COPYING}.
+Copyright @copyright{} 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries a copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying and provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+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
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end ifinfo
+@dircategory Emacs
+@direntry
+* WoMan: (woman). Browse UN*X Manual Pages "W.O. (without) Man".
+@end direntry
@finalout
@titlepage
@title WoMan
-@subtitle Browse UN*X Manual Pages ``Wo (without) Man''
+@subtitle Browse Unix Manual Pages ``W.O. (without) Man''
@subtitle Software Version @value{VERSION}
@author Francis J. Wright
@sp 2
@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}
@comment The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 2000 Francis J. Wright
-
-This manual and the software that it describes are subject to the GNU
-General Public License that is distributed with GNU Emacs -- see the
-file @file{COPYING}.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying and provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
+@insertcopying
@end titlepage
@contents
@ifnottex
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
-@top WoMan: Browse UN*X Manual Pages ``Wo (without) Man''
+@top WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
@display
Software Version @value{VERSION}
@menu
* Introduction:: Introduction
* Background:: Background
-* Installation:: Installation and Setup
* Finding:: Finding and Formatting Man Pages
* Browsing:: Browsing Man Pages
* Customization:: Customization
* 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
platform. It has not been tested, and may not run, with any other
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 Linux.
+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 UN*X-style
+@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
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
menu option @samp{Mini Help}.
WoMan is (of course) still under development! Please
-@email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work -- I am
+@email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work---I am
adding and improving functionality as testing shows that it is
necessary. Guidance on reporting bugs is given below. @xref{Bugs, ,
Reporting Bugs}.
@c ===================================================================
-@node Background, Installation, Introduction, Top
+@node Background, Finding, Introduction, Top
@comment node-name, next, previous, up
@chapter Background
@cindex background
-WoMan is a browser for traditional UN*X-style manual page documentation.
+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 UN*X ``man''
-macros, which are themselves written in the NROFF/TROFF text processing
-markup language. @code{NROFF} and @code{TROFF} are text processors
+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
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
that can be printed can also be rendered on screen, the only difference
being the resolution.
-Nevertheless, UN*X-style manual page documentation is still normally
+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
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
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
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 UN*X programs are ported to other platforms and come
-with UN*X-style manual page documentation. This may be difficult to
-read because ports of the UN*X-style @code{man} program can be a little
+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 @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''.
+handled by kludges that ``usually more or less work.''
The principle advantage of WoMan is that it does not require @code{man},
-and indeed the name WoMan is a contraction of ``without man''. But it
+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
+colored, 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 @code{man} mode.
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} initialisation 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} initialisation 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 UN*X man page." t)
-(autoload 'woman-find-file "woman"
- "Find, decode and browse a specific UN*X 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
-behaviour 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}
-initialisation 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
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:
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
-``man'' and beginning with ``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.
@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
A prefix argument always causes the @code{woman} command (only) to
rebuild its topic cache, and to re-save it to
-@code{woman-cache-filename} if this variable has a non-nil value. This
+@code{woman-cache-filename} if this variable has a non-@code{nil} value. This
is necessary if the @emph{names} of any of the directories or files in
the paths specified by @code{woman-manpath} or @code{woman-path} change.
If WoMan user options that affect the cache are changed then WoMan will
@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
This command can be used to browse any accessible man file, regardless
of its filename or location. If the file is compressed then automatic
file decompression must already be turned on (e.g.@: see the
-@samp{Help->Options} submenu) -- it is turned on automatically only by
+@samp{Help->Options} submenu)---it is turned on automatically only by
the @code{woman} topic interface.
@findex woman-dired-find-file
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
best to implement WoMan, before I implemented the current topic
interface, and I subsequently stopped using it. I might revive it as a
mechanism for storing pre-formatted WoMan files, somewhat analogous to
-the standard UN*X @code{catman} facility. In the meantime, it exists
+the standard Unix @code{catman} facility. In the meantime, it exists
for anyone who wants to experiment with it. Once it is set up it is
simply a question of visiting the file and there is no WoMan-specific
user interface!
(autoload 'woman-decode-region "woman")
(add-to-list 'format-alist
- '(man "UN*X man-page source format" "\\.\\(TH\\|ig\\) "
+ '(man "Unix man-page source format" "\\.\\(TH\\|ig\\) "
woman-decode-region nil nil
(lambda (arg)
set-visited-file-name
@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
@item n
@kindex n
@findex Man-next-section
-Move point to the Nth next section -- default 1 (@code{Man-next-section}).
+Move point to the Nth next section---default 1 (@code{Man-next-section}).
@item p
@kindex p
@findex Man-previous-section
-Move point to Nth previous section -- default 1
+Move point to Nth previous section---default 1
(@code{Man-previous-section}).
@item g
easily be directed to follow the reference, i.e.@: to find and format the
man page. When the mouse is passed over a correctly formatted reference
it is highlighted, in which case clicking the middle button
-@key{mouse-2} will cause WoMan to follow the reference. Alternatively,
+@kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively,
when point is over such a reference the key @key{RET} will follow the
reference.
Any word in the buffer can be used as a reference by clicking
-@key{mouse-2} over it provided the Meta key is also used (although in
+@kbd{Mouse-2} over it provided the Meta key is also used (although in
general such a ``reference'' will not lead to a man page).
Alternatively, the key @kbd{r} allows completion to be used to select a
reference to follow, based on the word at point as default.
@table @kbd
-@item @key{mouse-2}
-@kindex mouse-2
+@item @kbd{Mouse-2}
+@kindex Mouse-2
@findex woman-mouse-2
Run WoMan with word under mouse as topic (@code{woman-mouse-2}). The
word must be mouse-highlighted unless @code{woman-mouse-2} is used with
@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
@vtable @code
@item woman-show-log
-A boolean value that defaults to nil. If non-nil then show the
+A boolean value that defaults to @code{nil}. If non-@code{nil} then show the
@code{*WoMan-Log*} buffer if appropriate, i.e.@: if any warning messages
are written to it. @xref{Log, , The *WoMan-Log* Buffer}.
well) to provide a default value for @code{woman-manpath}.
@item woman-manpath
-A list of strings representing @emph{directory trees} to search for UN*X
+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
("/usr/man" "/usr/local/man")
@end lisp
-Any environment variables (names of which must have the UN*X-style form
+Any environment variables (names of which must have the Unix-style form
@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
regardless of platform) are evaluated first but each element must
evaluate to a @emph{single} directory name. Trailing @file{/}s are
@cindex directory separator character
@cindex @code{MANPATH}, directory separator
The @code{MANPATH} environment variable may be set using DOS
-semi-colon-separated or UN*X / Cygwin colon-separated syntax (but not
+semi-colon-separated or Unix-style colon-separated syntax (but not
mixed).
@item woman-manpath-man-regexp
@item woman-path
A list of strings representing @emph{specific directories} to search for
-UN*X manual files. For example
+Unix manual files. For example
@lisp
("/emacs/etc")
@noindent
and on other platforms is @code{nil}.
-Any environment variables (names of which must have the UN*X-style form
+Any environment variables (names of which must have the Unix-style form
@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
regardless of platform) are evaluated first but each element must
evaluate to a @emph{single} directory name (regexp, see above). For
and topic cache file, or @code{nil}. It is used to save and restore the
cache between Emacs sessions. This is especially useful with
remote-mounted man page files! The default value of @code{nil}
-suppresses this action. The ``standard'' non-nil filename is
+suppresses this action. The ``standard'' non-@code{nil} filename is
@file{~/.wmncach.el}. Remember that a prefix argument forces the
@code{woman} command to update and re-write the cache.
@item woman-dired-keys
A list of @code{dired} mode keys to be defined to run WoMan on the
-current file, e.g.@: @code{("w" "W")} or any non-nil atom to
+current file, e.g.@: @code{("w" "W")} or any non-@code{nil} atom to
automatically define @kbd{w} and @kbd{W} if they are unbound, or
@code{nil} to do nothing. Default is @code{t}.
@item woman-imenu-generic-expression
Imenu support for Sections and Subsections: an alist with elements of
-the form @code{(MENU-TITLE REGEXP INDEX)} -- see the documentation for
+the form @code{(MENU-TITLE REGEXP INDEX)}---see the documentation for
@code{imenu-generic-expression}. Default value is
@lisp
@end lisp
@item woman-imenu
-A boolean value that defaults to @code{nil}. If non-nil then WoMan adds
+A boolean value that defaults to @code{nil}. If non-@code{nil} then WoMan adds
a Contents menu to the menubar by calling @code{imenu-add-to-menubar}.
@item woman-imenu-title
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-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
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
not loaded by default!]
@item woman-use-own-frame
-If non-nil then use a dedicated frame for displaying WoMan windows.
+If non-@code{nil} then use a dedicated frame for displaying WoMan windows.
This is useful only when WoMan is run under a window system such as X or
Microsoft Windows that supports real multiple frames, in which case the
-default value is non-nil.
+default value is non-@code{nil}.
@end vtable
65.
@item woman-fill-frame
-A boolean value. If non-nil then most of the frame width is used,
-overriding the value of @code{woman-fill-column}. Default is nil.
+A boolean value. If non-@code{nil} then most of the frame width is used,
+overriding the value of @code{woman-fill-column}. Default is @code{nil}.
@item woman-default-indent
An integer specifying the default prevailing indent for the @code{-man}
-macros. Default is 5. Set this variable to 7 to emulate Linux man
+macros. Default is 5. Set this variable to 7 to emulate GNU/Linux man
formatting.
@item woman-bold-headings
-A boolean value. If non-nil then embolden section and subsection
-headings. Default is t. [Heading emboldening is @emph{not} standard
-@code{man} behaviour.]
+A boolean value. If non-@code{nil} then embolden section and subsection
+headings. Default is @code{t}. [Heading emboldening is @emph{not} standard
+@code{man} behavior.]
@item woman-ignore
-A boolean value. If non-nil then unrecognised requests etc. are
-ignored. Default is t. This gives the standard @code{ROFF} behaviour.
+A boolean value. If non-@code{nil} then unrecognised requests etc. are
+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-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
-saved to a file. Default is nil.
+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
@vtable @code
@item woman-fontify
-A boolean value. If non-nil then WoMan assumes that face support is
-available. It defaults to a non-nil value if the display supports
-either colours or different fonts.
+A boolean value. If non-@code{nil} then WoMan assumes that face support is
+available. It defaults to a non-@code{nil} value if the display supports
+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!
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
@vtable @code
@item woman-use-extended-font
-A boolean value. If non-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
-A boolean value. If non-nil then WoMan may use the symbol font.
+A boolean value. If non-@code{nil} then WoMan may use the symbol font.
Default is @code{nil}, mainly because it may change the line spacing (at
least in NTEmacs 20).
@cindex log buffer
@cindex buffer, log
-This is modelled on the Emacs byte-compiler. It logs all files
+This is modeled on the Emacs byte-compiler. It logs all files
formatted by WoMan and the time taken. If WoMan finds anything that it
cannot handle then it writes a warning to this buffer. If the variable
-@code{woman-show-log} is non-nil (by default it is @code{nil}) then
+@code{woman-show-log} is non-@code{nil} (by default it is @code{nil}) then
WoMan automatically displays this buffer. @xref{Interface Options, ,
Interface Options}. Many WoMan warnings can be completely ignored,
because they are reporting the fact that WoMan has ignored requests that
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}.
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
obviously wrongly or significantly differently from @code{man}) or
inelegantly, then please
-@enumerate a
+@enumerate
@item
-check that you are running the latest version of @file{woman.el}
-available from @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web
-site}, and
+try the latest version of @file{woman.el} from the Emacs CVS repository
+on @uref{http://savannah.gnu.org/}. If it still fails, please
@item
-check that the problem is not already described in the file
-@file{woman.status}, also available from
-@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web site}.
+send a bug report to @email{bug-gnu-emacs@@gnu.org} and to
+@email{F.J.Wright@@qmw.ac.uk}. Please include the entry from the
+@code{*WoMan-Log*} buffer relating to the problem file, together with
+a brief description of the problem. Please indicate where you got the
+man source file from, but do not send it unless asked to send it.
@end enumerate
-If both of the above are true then please
-@email{F.J.Wright@@qmw.ac.uk,email me} the entry from the
-@code{*WoMan-Log*} buffer relating to the problem file, together with a
-brief description of the problem. Please indicate where you got the man
-source file from, but do not send it to me unless I ask you to! Thanks.
-(At present WoMan has no automated bug-reporting facility.)
-
@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
@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
@printindex cp
@bye
+
+@ignore
+ arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028
+@end ignore
HCoop / bpt / emacs.git / blobdiff