\input texinfo @c -*-texinfo-*-
-@c $Id: woman.texi,v 1.5 2001/02/17 16:58:25 rms 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 Free Software Foundation, Inc.
-
-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.
+Copyright @copyright{} 2001, 2002, 2003, 2004,
+2005, 2006 Free Software Foundation, Inc.
-@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
@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}
Microsoft Windows, but has also been tested on MS-DOS, and various
versions of UNIX and GNU/Linux.
-WoMan is distributed with GNU Emacs 21, and the current source code and
-documentation files are available from
-@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web server}.
+WoMan is distributed with GNU Emacs. In addition, the current source
+code and documentation files are available from
+@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, the WoMan web
+server}.
WoMan implements a subset of the formatting performed by the Emacs
-@code{man} (or @code{manual-entry}) command to format a 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}
works less well on idiosyncratic files that ``break the rules'' or use
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}.
@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''
+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
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
+@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
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
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
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!
@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
+@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
@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:
+@file{.emacs} initialization file:
@lisp
(add-to-list 'load-path "my-lisp")
@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
+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
@lisp
(autoload 'woman "woman"
- "Decode and browse a UN*X man page." t)
+ "Decode and browse a Unix man page." t)
(autoload 'woman-find-file "woman"
- "Find, decode and browse a specific UN*X man-page file." t)
+ "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
(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}.
+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
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}:
+initialization file @file{.bashrc}:
@example
man() @{ gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; @}
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
@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
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}.
("/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
@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
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
@item woman-bold-headings
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} behaviour.]
+@code{man} behavior.]
@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} behaviour.
+ignored. Default is @code{t}. This gives the standard @code{ROFF} behavior.
If @code{nil} then they are left in the buffer, which may aid debugging.
@item woman-preserve-ascii
-A boolean value. If non-@code{nil} then preserve @sc{ascii} characters in the
-WoMan buffer. Otherwise, non-@sc{ascii} characters (that display as
-@sc{ascii}) may remain, which is irrelevant unless the buffer is to be
+A boolean value. If non-@code{nil} then preserve @acronym{ASCII} characters in the
+WoMan buffer. Otherwise, non-@acronym{ASCII} characters (that display as
+@acronym{ASCII}) may remain, which is irrelevant unless the buffer is to be
saved to a file. Default is @code{nil}.
@item woman-emulation
@item woman-fontify
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 colours or different fonts.
+either colors or different fonts.
@item woman-italic-face
Face for italic font in man pages. Default: italic, underlined,
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-@code{nil} then WoMan may use non-@sc{ascii} characters
+A boolean value. If non-@code{nil} then WoMan may use non-@acronym{ASCII} characters
from the default font. Default is @code{t}.
@item woman-use-symbol-font
@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-@code{nil} (by default it is @code{nil}) then
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
@printindex cp
@bye
+
+@ignore
+ arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028
+@end ignore