Mercurial > emacs
changeset 30659:ebfc33859f55
File added to the Emacs distribution.
| author | Eli Zaretskii <eliz@gnu.org> |
|---|---|
| date | Tue, 08 Aug 2000 10:38:56 +0000 |
| parents | 7ddcabbcb378 |
| children | e13ae0b7fc50 |
| files | man/woman.texi |
| diffstat | 1 files changed, 1670 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/woman.texi Tue Aug 08 10:38:56 2000 +0000 @@ -0,0 +1,1670 @@ +\input texinfo @c -*-texinfo-*- +@c $Id: woman.texinfo,v 1.2 2000-08-03 20:43:01+01 fjw Exp $ +@c %**start of header +@setfilename ../info/woman +@settitle WoMan: Browse UN*X Manual Pages ``Wo (without) Man'' +@c Manual last updated: +@set UPDATED Time-stamp: <2000-08-08 12:20:51 eliz> +@c Software version: +@set VERSION 0.54 (beta) +@afourpaper +@c With different size paper the printed page breaks will need attention! +@c Look for @page and @need commands. +@setchapternewpage off +@paragraphindent 0 +@c %**end of header + +@dircategory GNU Emacs Lisp +@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 +(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}. + +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. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@finalout + +@titlepage +@title WoMan +@subtitle Browse UN*X Manual Pages ``Wo (without) Man'' +@subtitle Software Version @value{VERSION} +@author Francis J. Wright +@sp 2 +@author School of Mathematical Sciences +@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 @uref{http://centaur.maths.qmw.ac.uk/} +@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. +@end titlepage + +@contents + +@c =================================================================== + +@ifnottex +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up +@top WoMan: Browse UN*X Manual Pages ``Wo (without) Man'' + +@display +Software Version @value{VERSION} +Manual Last Updated @value{UPDATED} + +@email{F.J.Wright@@qmw.ac.uk, Francis J. Wright} +@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 +@end display +@end ifnottex + +@menu +* Introduction:: Introduction +* Background:: Background +* Installation:: Installation and Setup +* Finding:: Finding and Formatting Man Pages +* Browsing:: Browsing Man Pages +* Customization:: Customization +* Log:: The *WoMan-Log* Buffer +* Technical:: Technical Details +* Bugs:: Reporting Bugs +* Acknowledgements:: Acknowledgements +* Command Index:: Command Index +* Variable Index:: Variable Index +* Keystroke Index:: Keystroke Index +* Concept Index:: Concept Index +@end menu + +@c =================================================================== + +@node Introduction, Background, Top, Top +@comment node-name, next, previous, up +@chapter Introduction +@cindex introduction + +This version of WoMan should run with GNU Emacs 20.3 or later on any +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. + +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 implements a subset of the formatting performed by the Emacs +@code{man} (or @code{manual-entry}) command to format a UN*X-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} +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 +performed. + +@table @b +@item Advantages +Much more direct, does not require any external programs. Supports +completion on man page names. +@item Disadvantages +Not a complete emulation. Currently no support for @code{eqn} or +@code{tbl}. Slightly slower for large man pages (but usually faster for +small- and medium-size pages). +@end table + +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 +are available in the file +@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/woman.status, +@file{woman.status}}. + +WoMan supports the use of compressed man files via +@code{auto-compression-mode} by turning it on if necessary. But you may +need to adjust the user option @code{woman-file-compression-regexp}. +@xref{Interface Options, , Interface Options}. + +Brief help on the WoMan interactive commands and user options, all of +which begin with the prefix @code{woman-} (or occasionally +@code{WoMan-}), is available most easily by loading WoMan and then +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}. + +@c =================================================================== + +@node Background, Installation, Introduction, Top +@comment node-name, next, previous, up +@chapter Background +@cindex background + +WoMan is a browser for traditional UN*X-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 +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}. + +@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 +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} +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 +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 +as a forerunner of @TeX{}. Traditionally, man pages are either +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 +most screens now support bit-mapped displays, so that any information +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 +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, +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 +implemented by the @code{man} program is to squeeze consecutive blank +lines into a single blank line. + +For some time, Emacs has offered an improved interface for browsing man +pages in the form of the Emacs @code{man} (or @code{manual-entry}) +command, see @ref{Documentation, man, Documentation Commands, emacs, GNU +Emacs Manual}. +This command runs @code{man} as described above, perhaps in +the background, and then post-processes the output to remove much of the +@code{NROFF} pagination such as page headers and footers, and places the +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 +provides some support for special display faces (fonts), but no special +menu or mouse support. The Emacs man package appears to have been +developed over about 10 years, from the late 1980s to the late 1990s. + +There is considerable inefficiency in having @code{NROFF} paginate a +document and then removing most of the pagination! + +WoMan is an Emacs Lisp library that provides an emulation of the +functionality of the Emacs @code{man} command, the main difference being +that WoMan does not use any external programs. The only situation in +which WoMan might use an external program is when the source file is +compressed, when WoMan will use the standard Emacs automatic +decompression facility, which does call an external program. + +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 +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 +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 +releasing the first version of WoMan I have been continually extending +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 +satisfactorily within the present design. Some of these are currently +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 +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 +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 +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 +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 +@comment node-name, next, previous, up +@chapter Finding and Formatting Man Pages +@cindex using, finding man pages +@cindex using, formatting man pages +@cindex finding man pages +@cindex formatting man pages +@cindex man pages, finding +@cindex man pages, formatting + +WoMan provides three user interfaces for finding and formatting man pages: + +@itemize @bullet +@item +a topic interface similar to that provided by the standard Emacs +@code{man} command; + +@item +a family of filename interfaces analogous to the standard Emacs +@code{view-file} command; + +@item +an automatic interface that detects the file type from its contents. +(This is currently neither well tested, well supported nor recommended!) +@end itemize + +The topic and filename interfaces support completion in the usual way. + +The topic interface is generally the most convenient for regular use, +although it may require some special setup, especially if your machine +does not already have a conventional @code{man} installation (which +WoMan tries to detect). + +The simplest filename interface command @code{woman-find-file} can +always be used with no setup at all (provided WoMan is installed and +loaded or set up to autoload). + +The automatic interface always requires special setup. + + +@heading Case-Dependence of Filenames + +@cindex case-sensitivity +@vindex w32-downcase-file-names +By default, WoMan ignores case in file pathnames only when it seems +appropriate. Microsoft Windows users who want complete case +independence should set the special NTEmacs variable +@code{w32-downcase-file-names} to @code{t} and use all lower case when +setting WoMan file paths. + + +@menu +* Topic:: Topic Interface +* Filename:: Filename Interface +* Automatic:: Automatic Interface +@end menu + +@node Topic, Filename, Finding, Finding +@comment node-name, next, previous, up +@section Topic Interface +@cindex topic interface + +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. + +Clearly, @code{woman} has to know where to look for man files and there +are two customizable user options that store this information: +@code{woman-manpath} and @code{woman-path}. @xref{Interface Options, , +Interface Options}. If @code{woman-manpath} is not set explicitly then +WoMan tries to pick up the information that would be used by the +@code{man} command, as follows. If the environment variable +@code{MANPATH} is set, which seems to be the standard mechanism under +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}. +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. + +If the above default configuration does not work correctly for any +reason then simply customize the value of @code{woman-manpath}. To +access man files that are not in a conventional man file hierarchy, +customize the value of @code{woman-path} to include the directories +containing the files. In this way, @code{woman} can access manual files +@emph{anywhere} in the entire file system. + +There are two differences between @code{woman-manpath} and +@code{woman-path}. Firstly, the elements of @code{woman-manpath} must +be directories that contain @emph{directories of} man files, whereas the +elements of @code{woman-path} must be directories that contain man files +@emph{directly}. Secondly, the last directory component of each element +of @code{woman-path} is treated as a regular (Emacs) match expression +rather than a fixed name, which allows collections of related +directories to be specified succinctly. + +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 +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}) +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 +whilst Emacs were running and after WoMan has been loaded. It may be +necessary if such a change occurs between Emacs sessions and persistent +caching is used, although WoMan can detect some changes that invalidate +its cache and rebuild it automatically. + +Customize the variable @code{woman-cache-filename} to save the cache +between Emacs sessions. This is recommended only if the @code{woman} +command is too slow the first time it is run in an Emacs session, while +it builds its cache in main memory, which @emph{may} be @emph{very} +slow. @xref{Cache, , The WoMan Topic Cache}, for further details. + + +@menu +* Cache:: The WoMan Topic Cache +* 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 +@subsection The WoMan Topic Cache +@cindex topic cache +@cindex cache, topic + +The amount of information that WoMan caches (in main memory and, +optionally, saved to disc) is controlled by the user option +@code{woman-cache-level}. There is a trade-off between the speed with +which WoMan can find a file and the size of the cache, and the default +setting gives a reasonable compromise. + +The @code{woman} command always performs a certain amount of caching in +main memory, but it can also write its cache to the filestore as a +persistent cache under control of the user option +@code{woman-cache-filename}. If persistent caching is turned on then +WoMan re-loads its internal cache from the cache file almost +instantaneously, so that there is never any perceptible start-up delay +@emph{except} when WoMan rebuilds its cache. Persistent caching is +currently turned off by default. This is because users with persistent +caching turned on may overlook the need to force WoMan to rebuild its +cache the first time they run it after they have installed new man +files; with persistent caching turned off, WoMan automatically rebuilds +its cache every time it is run in a new Emacs session. + +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 +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 +automatically update its cache file on disc (if one is in use) the next +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 +@cindex word at point +@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: + +@lisp +(global-set-key "\C-cw" + (lambda () + (interactive) + (let ((woman-topic-at-point t)) + (woman)))) +@end lisp + + +@node Filename, Automatic, Topic, Finding +@comment node-name, next, previous, up +@section Filename Interface +@cindex filename interface + +The commands in this family are completely independent of the topic +interface, caching mechanism, etc. + +@findex woman-find-file +The filename interface is accessed principally via the extended command +@code{woman-find-file}, which is available without any configuration at +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 +@samp{Help->Options} submenu) -- it is turned on automatically only by +the @code{woman} topic interface. + +@findex woman-dired-find-file +Once WoMan is loaded (or if specially set up), various additional +commands in this family are available. In a dired buffer, the command +@code{woman-dired-find-file} allows the file on the same line as point +to be formatted and browsed by WoMan. It is bound to the key @kbd{W} in +the dired mode map and added to the dired major mode menu. It may also +be bound to @kbd{w}, unless this key is bound by another library, which +it is by @code{dired-x}, for example. Because it is quite likely that +other libraries will extend the capabilities of such a commonly used +mode as dired, the precise key bindings added by WoMan to the dired mode +map are controlled by the user option @code{woman-dired-keys}. + +@findex woman-tar-extract-file +When a tar (Tape ARchive) file is visited in Emacs, it is opened in tar +mode, which parses the tar file and shows a dired-like view of its +contents. The WoMan command @code{woman-tar-extract-file} allows the +file on the same line as point to be formatted and browsed by WoMan. It +is bound to the key @kbd{w} in the tar mode map and added to the tar +major mode menu. + +The command @code{woman-reformat-last-file}, which is bound to the key +@kbd{R} in WoMan mode and available on the major mode menu, reformats +the last file formatted by WoMan. This may occasionally be useful if +formatting parameters, such as the fill column, are changed, or perhaps +if the buffer is somehow corrupted. + +@findex woman-decode-buffer +The command @code{woman-decode-buffer} can be used to decode and browse +the current buffer if it is visiting a man file, although it is +primarily used internally by WoMan. + + +@node Automatic, , Filename, Finding +@comment node-name, next, previous, up +@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 +formatting information transparently as @sc{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 +is not really supported. It originated during early experiments on how +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 +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! + +To use it, put something like this in your @file{.emacs} file. [The +call to @code{set-visited-file-name} is to avoid font-locking triggered +by automatic major mode selection.] + +@lisp +(autoload 'woman-decode-region "woman") + +(add-to-list 'format-alist + '(man "UN*X man-page source format" "\\.\\(TH\\|ig\\) " + woman-decode-region nil nil + (lambda (arg) + set-visited-file-name + (file-name-sans-extension buffer-file-name)))) +@end lisp + +@c =================================================================== + +@node Browsing, Customization, Finding, Top +@comment node-name, next, previous, up +@chapter Browsing Man Pages +@cindex using, browsing man pages +@cindex browsing man pages +@cindex man pages, browsing + +Once a man page has been found and formatted, WoMan provides a browsing +interface that is essentially the same as that provided by the standard +Emacs @code{man} command (and much of the code is inherited from the +@code{man} library, which WoMan currently requires). Many WoMan +facilities can be accessed from the WoMan major mode menu as well as via +key bindings, etc. + +WoMan does not produce any page breaks or page numbers, and in fact does +not paginate the man page at all, since this is not appropriate for +continuous online browsing. It produces a document header line that is +constructed from the standard man page header and footer. Apart from +that, the appearance of the formatted man page should be almost +identical to what would be produced by @code{man}, with consecutive +blank lines squeezed to a single blank line. + +@menu +* Fonts:: Fonts and Faces +* Navigation:: Navigation +* References:: Following References +* Changing:: Changing the Current Man Page +* Convenience:: Convenience Key Bindings +* Imenu:: Imenu Support; Contents Menu +@end menu + +@node Fonts, Navigation, Browsing, Browsing +@comment node-name, next, previous, up +@section Fonts and Faces +@cindex fonts +@cindex faces + +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 +``non-standard'' man pages, usually to represent a ``typewriter'' font) +and a face to indicate additional symbols introduced by WoMan. This +currently means the characters ^ and _ used to indicate super- and +sub-scripts, which are not displayed well by WoMan. + + +@node Navigation, References, Fonts, Browsing +@comment node-name, next, previous, up +@section Navigation +@cindex navigation + +Man (and hence WoMan) mode can be thought of as a superset of view mode. +The buffer cannot be edited, so keys that would normally self-insert are +used for navigation. The WoMan key bindings are a minor modification of +the @code{man} key bindings. + +@table @kbd +@item @key{SPC} +@kindex SPC +@findex scroll-up +Scroll the man page up the window (@code{scroll-up}). + +@item @key{DEL} +@kindex DEL +@findex scroll-down +Scroll the man page down the window (@code{scroll-down}). + +@item n +@kindex n +@findex 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 +(@code{Man-previous-section}). + +@item g +@kindex g +@findex Man-goto-section +Move point to the specified section (@code{Man-goto-section}). + +@item s +@kindex s +@findex Man-goto-see-also-section +Move point to the ``SEE ALSO'' section +(@code{Man-goto-see-also-section}). Actually the section moved to is +described by @code{Man-see-also-regexp}. +@end table + + +@node References, Changing, Navigation, Browsing +@comment node-name, next, previous, up +@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 +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, +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 +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 +@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 +the Meta key. + +@item @key{RET} +@kindex RET +@findex man-follow +Get the man page for the topic under (or nearest to) point +(@code{man-follow}). + +@item r +@kindex r +@findex Man-follow-manual-reference +Get one of the man pages referred to in the ``SEE ALSO'' section +(@code{Man-follow-manual-reference}). Specify which reference to use; +default is based on word at point. +@end table + + +@node Changing, Convenience, References, Browsing +@comment node-name, next, previous, up +@section Changing the Current Man Page +@cindex changing current man page +@cindex current man page, changing + +The man page currently being browsed by WoMan can be changed in several +ways. The command @code{woman} can be invoked to format another man +page, or the current WoMan buffer can be buried or killed. WoMan +maintains a ring of formatted man pages, and it is possible to move +forwards and backwards in this ring by moving to the next or previous +man page. It is sometimes useful to reformat the current page, for +example after the right margin (the wrap column) or some other +formatting parameter has been changed. + +Buffers formatted by Man and WoMan are completely unrelated, even though +some of the commands to manipulate them are superficially the same (and +share code). + +@table @kbd +@item m +@kindex m +@findex man +Run the command @code{man} to get a Un*x manual page and put it in a +buffer. This command is the top-level command in the man package. It +runs a Un*x command to retrieve and clean a man page in the background +and places the results in a Man mode (man page browsing) buffer. If a +man buffer already exists for this man page, it will display +immediately. This works exactly the same if WoMan is loaded, except +that the formatting time is displayed in the mini-buffer. + +@item w +@kindex w +@findex woman +Run the command @code{woman} exactly as if the extended command or menu +item had been used. + +@item q +@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. + +@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 +the page again. + +@item M-p +@kindex M-p +@findex WoMan-previous-manpage +Find the previous WoMan buffer (@code{WoMan-previous-manpage}). + +@item M-n +@kindex M-n +@findex WoMan-next-manpage +Find the next WoMan buffer (@code{WoMan-next-manpage}). + +@item R +@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. +@end table + + +@node Convenience, Imenu, Changing, Browsing +@comment node-name, next, previous, up +@section Convenience Key Bindings +@cindex convenience key bindings +@cindex key bindings, convenience + +@table @kbd +@item - +@kindex - +@findex negative-argument +Begin a negative numeric argument for the next command +(@code{negative-argument}). + +@item 0 .. 9 +@kindex 0 .. 9 +@findex digit-argument +Part of the numeric argument for the next command +(@code{digit-argument}). + +@item < +@kindex < +@itemx . +@kindex . +@findex beginning-of-buffer +Move point to the beginning of the buffer; leave mark at previous +position (@code{beginning-of-buffer}). + +@item > +@kindex > +@findex end-of-buffer +Move point to the end of the buffer; leave mark at previous position +(@code{end-of-buffer}). + +@item ? +@kindex ? +@findex describe-mode +Display documentation of current major mode and minor modes +(@code{describe-mode}). The major mode description comes first, +followed by the minor modes, each on a separate page. +@end table + + +@node Imenu, , Convenience, Browsing +@comment node-name, next, previous, up +@section Imenu Support; Contents Menu +@cindex imenu support +@cindex contents menu + +The WoMan menu provides an option to make a contents menu for the +current man page (using @code{imenu}). Alternatively, if you customize +the option @code{woman-imenu} to @code{t} then WoMan will do it +automatically for every man page. The menu title is set by the option +@code{woman-imenu-title}, which is ``CONTENTS'' by default. The menu +shows manual sections and subsections by default, but you can change +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 +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 +@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. + +The top-level WoMan group contains only a few general options and three +subgroups. The hooks are provided only for special purposes that, for +example, require code to be executed, and should be changed only via +@code{Customization} or the function @code{add-hook}. Most +customization should be possible via existing user options. + +@vtable @code +@item woman-show-log +A boolean value that defaults to nil. If non-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}. + +@item woman-pre-format-hook +A hook run immediately before formatting a buffer. It might, for +example, be used for face customization. @xref{Faces, , Faces}, +however. + +@item woman-post-format-hook +A hook run immediately after formatting a buffer. It might, for +example, be used for installing a dynamic menu using @code{imenu}. +(However. in this case it is better to use the built-in WoMan +@code{imenu} support. @xref{Imenu, , Imenu Support; Contents Menu}.) +@end vtable + +@heading Customization Subgroups + +@table @code +@item WoMan Interface +These options control the process of locating the appropriate file to +browse, and the appearance of the browsing interface. + +@item WoMan Formatting +These options control the layout that WoMan uses to format the man page. + +@item WoMan Faces +These options control the display faces that WoMan uses to format the +man page. +@end table + +@menu +* Interface Options:: +* Formatting Options:: +* Faces:: +* Special symbols:: +@end menu + +@node Interface Options, Formatting Options, Customization, Customization +@comment node-name, next, previous, up +@section Interface Options +@cindex interface options + +These options control the process of locating the appropriate file to +browse, and the appearance of the browsing interface. + +@vtable @code +@item woman-man.conf-path +A list of strings representing directories to search and/or files to try +for a man configuration file. The default is + +@lisp +("/etc" "/usr/local/lib") +@end lisp + +@noindent +[for GNU/Linux and Cygwin respectively.] A trailing separator (@file{/} +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 +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 +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. + +@cindex @code{MANPATH}, environment variable +If not set then the environment variable @code{MANPATH} is used. If no +such environment variable is found, the default list is determined by +consulting the man configuration file if found. By default this is +expected to be either @file{/etc/man.config} or +@file{/usr/local/lib/man.conf}, which is controlled by the user option +@code{woman-man.conf-path}. An empty substring of @code{MANPATH} +denotes the default list. Otherwise, the default value of this variable +is + +@lisp +("/usr/man" "/usr/local/man") +@end lisp + +Any environment variables (names of which must have the UN*X-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 +ignored. (Specific directories in @code{woman-path} are also searched.) + +On Microsoft platforms I recommend including drive letters explicitly, +e.g. + +@lisp +("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man") +@end lisp + +@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 +mixed). + +@item woman-manpath-man-regexp +A regular expression to match man directories @emph{under} the +@code{woman-manpath} directories. These normally have names of the form +@file{man?}. Its default value is @code{"[Mm][Aa][Nn]"}, which is +case-insensitive mainly for the benefit of Microsoft platforms. Its +purpose is to avoid directories such as @file{cat?}, @file{.}, +@file{..}, etc. + +@item woman-path +A list of strings representing @emph{specific directories} to search for +UN*X manual files. For example + +@lisp +("/emacs/etc") +@end lisp + +These directories are searched in addition to the directory trees +specified in @code{woman-manpath}. Each element should be a directory +string or @code{nil}, which represents the current directory when the +path is expanded and cached. However, the last component (only) of each +directory string is treated as a regexp (Emacs, not shell) and the +string is expanded into a list of matching directories. Non-directory +and unreadable files are ignored. The default value on MS-DOS is + +@lisp +("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]") +@end lisp + +@noindent +and on other platforms is @code{nil}. + +Any environment variables (names of which must have the UN*X-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 +example + +@lisp +("$EMACSDATA") +@end lisp + +@noindent +or equivalently + +@lisp +("$EMACS_DIR/etc") +@end lisp + +@noindent +Trailing @file{/}s are discarded. (The directory trees in +@code{woman-manpath} are also searched.) On Microsoft platforms I +recommend including drive letters explicitly. + +@item woman-cache-level +A positive integer representing the level of topic caching: + +@enumerate +@item +cache only the topic and directory lists (uses minimal memory, but not +recommended); +@item +cache also the directories for each topic (faster, without using much +more memory); +@item +cache also the actual filenames for each topic (fastest, but uses twice +as much memory). +@end enumerate + +The default value is currently 2, a good general compromise. If the +@code{woman} command is slow to find files then try 3, which may be +particularly beneficial with large remote-mounted man directories. Run +the @code{woman} command with a prefix argument or delete the cache file +@code{woman-cache-filename} for a change to take effect. (Values < 1 +behave like 1; values > 3 behave like 3.) + +@item woman-cache-filename +Either a string representing the full pathname of the WoMan directory +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 +@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 +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 +@code{imenu-generic-expression}. Default value is + +@lisp +((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE + ("*Subsections*" "^ \\([A-Z].*\\)" 1)) +@end lisp + +@item woman-imenu +A boolean value that defaults to @code{nil}. If non-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-uncompressed-file-regexp +A regular match expression used to select man source files (ignoring any +compression extension). The default value is +@code{"\\.\\([0-9lmnt]\\w*\\)"} [which means a filename extension is +required]. + +@emph{Do not change this unless you are sure you know what you are doing!} + +The SysV standard man pages use two character suffixes, and this is +becoming more common in the GNU world. For example, the man pages in +the @code{ncurses} package include @file{toe.1m}, @file{form.3x}, etc. + +@strong{Note:} an optional compression regexp will be appended, so this +regexp @emph{must not} end with any kind of string terminator such as +@code{$} or @code{\\'}. + +@item woman-file-compression-regexp +A regular match expression used to match compressed man file extensions +for which decompressors are available and handled by auto-compression +mode. It should begin with @code{\\.} and end with @code{\\'} and +@emph{must not} be optional. The default value is +@code{"\\.\\(g?z\\|bz2\\)\\'"}, which matches the @code{gzip} and +@code{bzip2} compression extensions. + +@emph{Do not change this unless you are sure you know what you are doing!} + +[It should be compatible with the @code{car} of +@code{jka-compr-file-name-handler-entry}, but that is unduly +complicated, includes an inappropriate extension (@file{.tgz}) and is +not loaded by default!] + +@item woman-use-own-frame +If non-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. +@end vtable + + +@node Formatting Options, Faces, Interface Options, Customization +@comment node-name, next, previous, up +@section Formatting Options +@cindex formatting options + +These options control the layout that WoMan uses to format the man page. + +@vtable @code +@item woman-fill-column +An integer specifying the right margin for formatted text. Default is +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. + +@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 +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.] + +@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. +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. + +@item woman-emulation +WoMan emulation, currently either @code{NROFF} or @code{TROFF}. Default +is @code{NROFF}. @code{TROFF} emulation is experimental and largely +untested. +@end vtable + + +@node Faces, Special symbols, Formatting Options, Customization +@comment node-name, next, previous, up +@section Faces +@cindex faces + +These options control the display faces that WoMan uses to format the +man page. + +@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. + +@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 +italic or underline as you prefer, but not both, although italic and +underline work together perfectly well! + +@item woman-bold-face +Face for bold font in man pages. Default: bold, foreground blue. + +@item woman-unknown-face +Face for all unknown fonts in man pages. Default: foreground brown. +Brown is a good compromise: it is distinguishable from the default but +not enough so as to make font errors look terrible. (Files that use +non-standard fonts seem to do so badly or in idiosyncratic ways!) + +@item woman-addition-face +Face for all additions made by WoMan to man pages. +Default: foreground orange. +@end vtable + + +@node Special symbols, , Faces, Customization +@comment node-name, next, previous, up +@section Special symbols +@cindex special symbols + +This section currently applies @emph{only} to Microsoft Windows. + +WoMan provides partial experimental support for special symbols, +initially only for MS-Windows and only for MS-Windows fonts. This +includes both non-@sc{ascii} characters from the main text font and use +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 +work on any other platform. + +@vtable @code +@item woman-use-extended-font +A boolean value. If non-nil then WoMan may use non-@sc{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. +Default is @code{nil}, mainly because it may change the line spacing (at +least in NTEmacs 20). + +@item woman-symbol-font +A string describing the symbol font to use for special characters. +It should be compatible with, and the same size as, the default text font. +Under MS-Windows, the default is + +@lisp +"-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol" +@end lisp +@end vtable + + +@c =================================================================== + +@node Log, Technical, Customization, Top +@comment node-name, next, previous, up +@chapter The *WoMan-Log* Buffer +@cindex log buffer +@cindex buffer, log + +This is modelled 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 +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 +it is correct for WoMan to ignore. In some future version this level of +paranoia may be reduced, but not until WoMan is deemed more reliable. +At present, all warnings should be treated with some suspicion. +Uninterpreted escape sequences are also logged (in some cases). + +By resetting the variable @code{woman-ignore} to @code{nil} (by default +it is @code{t}), uninterpreted @code{ROFF} requests can optionally be +left in the formatted buffer to indicate precisely where they occurred. +@xref{Interface Options, , Interface Options}. + +@c =================================================================== + +@node Technical, Bugs, Log, Top +@comment node-name, next, previous, up +@chapter Technical Details +@cindex technical details +@cindex horizontal spacing +@cindex spacing, horizontal and vertical +@cindex vertical spacing +@cindex resolution + +@heading Horizontal and vertical spacing and resolution + +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.) + +@heading Vertical spacing and blank lines + +The number of consecutive blank lines in the formatted buffer should be +either 0 or 1. A blank line should leave a space like .sp 1. +Current policy is to output vertical space only immediately before text +is output. + +@c =================================================================== + +@node Bugs, Acknowledgements, Technical, Top +@comment node-name, next, previous, up +@chapter Reporting Bugs +@cindex reporting bugs +@cindex bugs, reporting + +If WoMan fails completely, or formats a file incorrectly (i.e.@: +obviously wrongly or significantly differently from @code{man}) or +inelegantly, then please + +@enumerate a +@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 + +@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}. +@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 +@comment node-name, next, previous, up +@chapter Acknowledgements +@cindex acknowledgements + +For Heather, Kathryn and Madelyn, the women in my life (although they +will probably never use it)! + +I also thank the following for helpful suggestions, bug reports, code +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} +@end quotation + +@c =================================================================== + +@comment END OF MANUAL TEXT +@page + +@node Command Index, Variable Index, Acknowledgements, Top +@comment node-name, next, previous, up +@unnumbered Command Index + +@printindex fn + +@node Variable Index, Keystroke Index, Command Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index + +@printindex vr + +@c Without a page throw here, the page length seems to get reset to the +@c depth of the index that fits on the page after the previous index. +@c This must be a bug! + +@page + +@node Keystroke Index, Concept Index, Variable Index, Top +@comment node-name, next, previous, up +@unnumbered Keystroke Index + +@printindex ky + +@c Without a page throw here, the page length seems to get reset to the +@c depth of the index that fits on the page after the previous index. +@c This must be a bug! + +@page + +@node Concept Index, , Keystroke Index, Top +@comment node-name, next, previous, up +@unnumbered Concept Index + +@printindex cp + +@bye