@c %**start of header
@setfilename ../../info/woman
@settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
-@c FIXME
-@c Manual last updated:
-@set UPDATED Time-stamp: <Thu 24-Jun-2010 00:06:54 gm on grasmoor>
-@c Software version:
-@set VERSION 0.54 (beta)
+@include emacsver.texi
@afourpaper
@c With different size paper the printed page breaks will need attention!
@c Look for @page and @need commands.
@setchapternewpage off
@paragraphindent 0
+@documentencoding UTF-8
@c %**end of header
@copying
This file documents WoMan: A program to browse Unix manual pages `W.O.
(without) man'.
-Copyright @copyright{} 2001-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2001--2014 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.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+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.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@titlepage
@title WoMan
@subtitle Browse Unix Manual Pages ``W.O. (without) Man''
-@subtitle Software Version @value{VERSION}
+@subtitle as distributed with Emacs @value{EMACSVER}
@author Francis J. Wright
@sp 2
@author School of Mathematical Sciences
@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
@c ===================================================================
@ifnottex
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
+@node Top
@top WoMan: Browse Unix Manual Pages ``W.O. (without) Man''
@display
-Software Version @value{VERSION}
-Manual Last Updated @value{UPDATED}
+As distributed with Emacs @value{EMACSVER}.
+@ifnothtml
@email{F.J.Wright@@qmw.ac.uk, Francis J. Wright}
+@end ifnothtml
+@ifhtml
+Francis J. Wright
+@end ifhtml
@uref{http://centaur.maths.qmw.ac.uk/, School of Mathematical Sciences}
Queen Mary and Westfield College (University of London)
Mile End Road, London E1 4NS, UK
* Log:: The *WoMan-Log* Buffer
* Technical:: Technical Details
* Bugs:: Reporting Bugs
-* Acknowledgements:: Acknowledgements
+* Acknowledgments:: Acknowledgments
* GNU Free Documentation License:: The license for this documentation.
* Command Index:: Command Index
* Variable Index:: Variable Index
@c ===================================================================
-@node Introduction, Background, Top, Top
-@comment node-name, next, previous, up
+@node Introduction
@chapter Introduction
@cindex introduction
Microsoft Windows, but has also been tested on MS-DOS, and various
versions of UNIX and GNU/Linux.
-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 is distributed with GNU Emacs.
WoMan implements a subset of the formatting performed by the Emacs
@code{man} (or @code{manual-entry}) command to format a Unix-style
either running the command @code{woman-mini-help} or selecting the WoMan
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
-adding and improving functionality as testing shows that it is
-necessary. Guidance on reporting bugs is given below. @xref{Bugs, ,
-Reporting Bugs}.
+Guidance on reporting bugs is given below. @xref{Bugs, , Reporting Bugs}.
@c ===================================================================
-@node Background, Finding, Introduction, Top
-@comment node-name, next, previous, up
+@node Background
@chapter Background
@cindex background
and man can happily co-exist, which is very useful for comparison and
debugging purposes.
+@ignore
@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
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.
+@end ignore
-@node Finding, Browsing, Background, Top
-@comment node-name, next, previous, up
+@node Finding
@chapter Finding and Formatting Man Pages
@cindex using, finding man pages
@cindex using, formatting man pages
* Automatic:: Automatic Interface
@end menu
-@node Topic, Filename, Finding, Finding
-@comment node-name, next, previous, up
+@node Topic
@section Topic Interface
@cindex topic interface
similar), which seems to be the standard mechanism under GNU/Linux, then
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}.
+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.
network is involved. For this reason, it caches various amounts of
information, after which retrieving it from the cache is very fast. If
the cache ever gets out of synchronism with reality, running the
-@code{woman} command with a prefix argument (e.g.@: @kbd{C-u M-x woman})
+@code{woman} command with a prefix argument (e.g., @kbd{C-u M-x woman})
will force it to rebuild its cache. This is necessary only if the names
or locations of any man files change; it is not necessary if only their
contents change. It would always be necessary if such a change occurred
@menu
* Cache:: The WoMan Topic Cache
-* Word at point:: Using the ``Word at Point'' as a Topic Suggestion
+* Word at point:: Using the "Word at Point" as a Topic Suggestion
@end menu
-@node Cache, Word at point, Topic, Topic
-@comment node-name, next, previous, up
+@node Cache
@subsection The WoMan Topic Cache
@cindex topic cache
@cindex cache, topic
time it is run in a new Emacs session.
-@node Word at point, , Cache, Topic
-@comment node-name, next, previous, up
-@subsection Using the ``Word at Point'' as a Topic Suggestion
+@node Word at point
+@subsection Using the "Word at Point" as a Topic Suggestion
@cindex word at point
@cindex point, word at
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
+e.g., this key binding for @kbd{C-c w} runs WoMan on the topic at
point without seeking confirmation:
@lisp
@end lisp
-@node Filename, Automatic, Topic, Finding
-@comment node-name, next, previous, up
+@node Filename
@section Filename Interface
@cindex filename interface
all (provided WoMan is installed and loaded or set up to autoload).
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
+file decompression must already be turned on (e.g., see the
@samp{Help->Options} submenu)---it is turned on automatically only by
the @code{woman} topic interface.
primarily used internally by WoMan.
-@node Automatic, , Filename, Finding
-@comment node-name, next, previous, up
+@node Automatic
@section Automatic Interface
@cindex automatic interface
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
+facilities for editing rich (i.e., formatted) text, as a way to store
formatting information transparently as @acronym{ASCII} markup. WoMan can in
principle use this interface, but it must be configured explicitly.
@c ===================================================================
-@node Browsing, Customization, Finding, Top
-@comment node-name, next, previous, up
+@node Browsing
@chapter Browsing Man Pages
@cindex using, browsing man pages
@cindex browsing man pages
* Imenu:: Imenu Support; Contents Menu
@end menu
-@node Fonts, Navigation, Browsing, Browsing
-@comment node-name, next, previous, up
+@node Fonts
@section Fonts and Faces
@cindex fonts
@cindex faces
sub-scripts, which are not displayed well by WoMan.
-@node Navigation, References, Fonts, Browsing
-@comment node-name, next, previous, up
+@node Navigation
@section Navigation
@cindex navigation
Scroll the man page up the window (@code{scroll-up}).
@item @key{DEL}
+@itemx @kbd{S-@key{SPC}}
@kindex DEL
+@kindex S-SPC
@findex scroll-down
Scroll the man page down the window (@code{scroll-down}).
@end table
-@node References, Changing, Navigation, Browsing
-@comment node-name, next, previous, up
+@node References
@section Following References
@cindex following references
@cindex references
Man pages usually contain a ``SEE ALSO'' section containing references
to other man pages. If these man pages are installed then WoMan can
-easily be directed to follow the reference, i.e.@: to find and format the
+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
@kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively,
@end table
-@node Changing, Convenience, References, Browsing
-@comment node-name, next, previous, up
+@node Changing
@section Changing the Current Man Page
@cindex changing current man page
@cindex current man page, changing
@kindex q
@findex Man-quit
Bury the buffer containing the current man page (@code{Man-quit}),
-i.e.@: move it to the bottom of the buffer stack.
+i.e., move it to the bottom of the buffer stack.
@item k
@kindex k
@findex Man-kill
Kill the buffer containing the current man page (@code{Man-kill}),
-i.e.@: delete it completely so that it can be retrieved only by formatting
+i.e., delete it completely so that it can be retrieved only by formatting
the page again.
@item M-p
@kindex R
@findex woman-reformat-last-file
Call WoMan to reformat the last man page formatted by WoMan
-(@code{woman-reformat-last-file}), e.g.@: after changing the fill column.
+(@code{woman-reformat-last-file}), e.g., after changing the fill column.
@end table
-@node Convenience, Imenu, Changing, Browsing
-@comment node-name, next, previous, up
+@node Convenience
@section Convenience Key Bindings
@cindex convenience key bindings
@cindex key bindings, convenience
@end table
-@node Imenu, , Convenience, Browsing
-@comment node-name, next, previous, up
+@node Imenu
@section Imenu Support; Contents Menu
@cindex imenu support
@cindex contents menu
this by customizing @code{woman-imenu-generic-expression}.
WoMan is configured not to replace spaces in an imenu
-@code{*Completion*} buffer. For further documentation on the use of
+@file{*Completion*} buffer. For further documentation on the use of
imenu, such as menu sorting, see the source file @file{imenu.el}, which
is distributed with GNU Emacs.
@c ===================================================================
-@node Customization, Log, Browsing, Top
-@comment node-name, next, previous, up
+@node Customization
@chapter Customization
@cindex customization
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}
+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
@vtable @code
@item woman-show-log
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
+@file{*WoMan-Log*} buffer if appropriate, i.e., if any warning messages
are written to it. @xref{Log, , The *WoMan-Log* Buffer}.
@item woman-pre-format-hook
* Special symbols::
@end menu
-@node Interface Options, Formatting Options, Customization, Customization
-@comment node-name, next, previous, up
+@node Interface Options
@section Interface Options
@cindex interface options
@noindent
[for GNU/Linux and Cygwin respectively.] A trailing separator (@file{/}
-for UNIX etc.) on directories is optional and the filename matched if a
+for UNIX etc.)@: on directories is optional and the filename matched if a
directory is specified is the first to match the regexp
@code{man.*\.conf}. If the environment variable @code{MANPATH} is not
set but a configuration file is found then it is parsed instead (or as
@end lisp
Any environment variables (names of which must have the Unix-style form
-@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
+@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
ignored. (Specific directories in @code{woman-path} are also searched.)
On Microsoft platforms I recommend including drive letters explicitly,
-e.g.
+e.g.:
@lisp
("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man")
and on other platforms is @code{nil}.
Any environment variables (names of which must have the Unix-style form
-@code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
+@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
example
@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-@code{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}.
@end vtable
-@node Formatting Options, Faces, Interface Options, Customization
-@comment node-name, next, previous, up
+@node Formatting Options
@section Formatting Options
@cindex formatting options
@end vtable
-@node Faces, Special symbols, Formatting Options, Customization
-@comment node-name, next, previous, up
+@node Faces
@section Faces
@cindex faces
@end vtable
-@node Special symbols, , Faces, Customization
-@comment node-name, next, previous, up
+@node Special symbols
@section Special symbols
@cindex special symbols
initially only for MS-Windows and only for MS-Windows fonts. This
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
+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
work on any other platform.
@c ===================================================================
-@node Log, Technical, Customization, Top
-@comment node-name, next, previous, up
+@node Log
@chapter The *WoMan-Log* Buffer
@cindex log buffer
@cindex buffer, log
@c ===================================================================
-@node Technical, Bugs, Log, Top
-@comment node-name, next, previous, up
+@node Technical
@chapter Technical Details
@cindex technical details
@cindex horizontal spacing
@c ===================================================================
-@node Bugs, Acknowledgements, Technical, Top
-@comment node-name, next, previous, up
+@node Bugs
@chapter Reporting Bugs
@cindex reporting bugs
@cindex bugs, reporting
-If WoMan fails completely, or formats a file incorrectly (i.e.@:
+If WoMan fails completely, or formats a file incorrectly (i.e.,
obviously wrongly or significantly differently from @code{man}) or
inelegantly, then please
on @uref{http://savannah.gnu.org/projects/emacs/}. If it still fails, please
@item
-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
+use @kbd{M-x report-emacs-bug} to send a bug report.
+Please include the entry from the
+@file{*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
@c ===================================================================
-@node Acknowledgements, GNU Free Documentation License, Bugs, Top
-@comment node-name, next, previous, up
-@chapter Acknowledgements
-@cindex acknowledgements
+@node Acknowledgments
+@chapter Acknowledgments
+@cindex acknowledgments
For Heather, Kathryn and Madelyn, the women in my life (although they
will probably never use it)!
fragments, general interest, etc.:
@quotation
-Jari Aalto, @email{jari.aalto@@cs.tpu.fi}@*
-Dean Andrews, @email{dean@@dra.com}@*
-Juanma Barranquero, @email{barranquero@@laley-actualidad.es}@*
-Karl Berry, @email{kb@@cs.umb.edu}@*
-Jim Chapman, @email{jchapman@@netcomuk.co.uk}@*
-Frederic Corne, @email{frederic.corne@@erli.fr}@*
-Peter Craft, @email{craft@@alacritech.com}@*
-Charles Curley, @email{ccurley@@trib.com}@*
-Jim Davidson, @email{jdavidso@@teknowledge.com}@*
-Kevin D'Elia, @email{Kevin.DElia@@mci.com}@*
-John Fitch, @email{jpff@@maths.bath.ac.uk}@*
-Hans Frosch, @email{jwfrosch@@rish.b17c.ingr.com}@*
-Guy Gascoigne-Piggford, @email{ggp@@informix.com}@*
-Brian Gorka, @email{gorkab@@sanchez.com}@*
-Nicolai Henriksen, @email{nhe@@lyngso-industri.dk}@*
-Thomas Herchenroeder, @email{the@@software-ag.de}@*
-Alexander Hinds, @email{ahinds@@thegrid.net}@*
-Stefan Hornburg, @email{sth@@hacon.de}@*
-Theodore Jump, @email{tjump@@cais.com}@*
-Paul Kinnucan, @email{paulk@@mathworks.com}@*
-Jonas Linde, @email{jonas@@init.se}@*
-Andrew McRae, @email{andrewm@@optimation.co.nz}@*
-Howard Melman, @email{howard@@silverstream.com}@*
-Dennis Pixton, @email{dennis@@math.binghamton.edu}@*
-T. V. Raman, @email{raman@@Adobe.com}@*
-Bruce Ravel, @email{bruce.ravel@@nist.gov}@*
-Benjamin Riefenstahl, @email{benny@@crocodial.de}@*
-Kevin Ruland, @email{kruland@@seistl.com}@*
-Tom Schutter, @email{tom@@platte.com}@*
-Wei-Xue Shi, @email{wxshi@@ma.neweb.ne.jp}@*
-Fabio Somenzi, @email{fabio@@joplin.colorado.edu}@*
-Karel Sprenger, @email{ks@@ic.uva.nl}@*
-Chris Szurgot, @email{szurgot@@itribe.net}@*
-Paul A. Thompson, @email{pat@@po.cwru.edu}@*
-Arrigo Triulzi, @email{arrigo@@maths.qmw.ac.uk}@*
-Geoff Voelker, @email{voelker@@cs.washington.edu}@*
-Eli Zaretskii, @email{eliz@@is.elta.co.il}
+@c jari.aalto@@cs.tpu.fi
+Jari Aalto,
+@c dean@@dra.com
+Dean Andrews,
+@c barranquero@@laley-actualidad.es
+Juanma Barranquero,
+@c kb@@cs.umb.edu
+Karl Berry,
+@c jchapman@@netcomuk.co.uk
+Jim Chapman,
+@c frederic.corne@@erli.fr
+Frederic Corne,
+@c craft@@alacritech.com
+Peter Craft,
+@c ccurley@@trib.com
+Charles Curley,
+@c jdavidso@@teknowledge.com
+Jim Davidson,
+@c Kevin.DElia@@mci.com
+Kevin D'Elia,
+@c jpff@@maths.bath.ac.uk
+John Fitch,
+@c jwfrosch@@rish.b17c.ingr.com
+Hans Frosch,
+@c ggp@@informix.com
+Guy Gascoigne-Piggford,
+@c gorkab@@sanchez.com
+Brian Gorka,
+@c nhe@@lyngso-industri.dk
+Nicolai Henriksen,
+@c the@@software-ag.de
+Thomas Herchenroeder,
+@c ahinds@@thegrid.net
+Alexander Hinds,
+@c sth@@hacon.de
+Stefan Hornburg,
+@c tjump@@cais.com
+Theodore Jump,
+@c paulk@@mathworks.com
+Paul Kinnucan,
+@c jonas@@init.se
+Jonas Linde,
+@c andrewm@@optimation.co.nz
+Andrew McRae,
+@c howard@@silverstream.com
+Howard Melman,
+@c dennis@@math.binghamton.edu
+Dennis Pixton,
+@c raman@@Adobe.com
+T. V. Raman,
+@c bruce.ravel@@nist.gov
+Bruce Ravel,
+@c benny@@crocodial.de
+Benjamin Riefenstahl,
+@c kruland@@seistl.com
+Kevin Ruland,
+@c tom@@platte.com
+Tom Schutter,
+@c wxshi@@ma.neweb.ne.jp
+Wei-Xue Shi,
+@c fabio@@joplin.colorado.edu
+Fabio Somenzi,
+@c ks@@ic.uva.nl
+Karel Sprenger,
+@c szurgot@@itribe.net
+Chris Szurgot,
+@c pat@@po.cwru.edu
+Paul A. Thompson,
+@c arrigo@@maths.qmw.ac.uk
+Arrigo Triulzi,
+@c voelker@@cs.washington.edu
+Geoff Voelker,
+@c eliz@@is.elta.co.il
+Eli Zaretskii
@end quotation
@c ===================================================================
@page
-@node GNU Free Documentation License, Command Index, Acknowledgements, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
-@node Command Index, Variable Index, GNU Free Documentation License, Top
-@comment node-name, next, previous, up
+@node Command Index
@unnumbered Command Index
@printindex fn
-@node Variable Index, Keystroke Index, Command Index, Top
-@comment node-name, next, previous, up
+@node Variable Index
@unnumbered Variable Index
@printindex vr
@page
-@node Keystroke Index, Concept Index, Variable Index, Top
-@comment node-name, next, previous, up
+@node Keystroke Index
@unnumbered Keystroke Index
@printindex ky
@page
-@node Concept Index, , Keystroke Index, Top
-@comment node-name, next, previous, up
+@node Concept Index
@unnumbered Concept Index
@printindex cp