1 \input texinfo @c -*-texinfo-*-
2 @c $Id: woman.texi,v 1.7 2001/03/05 15:11:21 eliz Exp $
4 @setfilename ../info/woman
5 @settitle WoMan: Browse Unix Manual Pages ``Wo (without) Man''
6 @c Manual last updated:
7 @set UPDATED Time-stamp: <2002-12-04 09:12:13 pavel>
9 @set VERSION 0.54 (beta)
11 @c With different size paper the printed page breaks will need attention!
12 @c Look for @page and @need commands.
13 @setchapternewpage off
19 * WoMan: (woman). Browse UN*X Manual Pages `Wo (without) Man'.
23 This file documents WoMan: A program to browse Unix manual pages `wo
26 Copyright @copyright{} 2001 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.1 or
30 any later version published by the Free Software Foundation; with no
31 Invariant Sections, with the Front-Cover texts being ``A GNU
32 Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
33 license is included in the section entitled ``GNU Free Documentation
34 License'' in the Emacs manual.
36 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
37 this GNU Manual, like GNU software. Copies published by the Free
38 Software Foundation raise funds for GNU development.''
40 This document is part of a collection distributed under the GNU Free
41 Documentation License. If you want to distribute this document
42 separately from the collection, you can do so by adding a copy of the
43 license to the document, as described in section 6 of the license.
50 @subtitle Browse Unix Manual Pages ``Wo (without) Man''
51 @subtitle Software Version @value{VERSION}
52 @author Francis J. Wright
54 @author School of Mathematical Sciences
55 @author Queen Mary and Westfield College
56 @author (University of London)
57 @author Mile End Road, London E1 4NS, UK
58 @author @email{F.J.Wright@@qmw.ac.uk}
59 @author @uref{http://centaur.maths.qmw.ac.uk/}
61 @author Manual Last Updated @value{UPDATED}
63 @comment The following two commands start the copyright page.
65 @vskip 0pt plus 1filll
67 Copyright @copyright{} 2001 Free Software Foundation, Inc.
69 Permission is granted to copy, distribute and/or modify this document
70 under the terms of the GNU Free Documentation License, Version 1.1 or
71 any later version published by the Free Software Foundation; with no
72 Invariant Sections, with the Front-Cover texts being ``A GNU
73 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
74 license is included in the section entitled ``GNU Free Documentation
75 License'' in the Emacs manual.
77 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
78 this GNU Manual, like GNU software. Copies published by the Free
79 Software Foundation raise funds for GNU development.''
81 This document is part of a collection distributed under the GNU Free
82 Documentation License. If you want to distribute this document
83 separately from the collection, you can do so by adding a copy of the
84 license to the document, as described in section 6 of the license.
89 @c ===================================================================
92 @node Top, Introduction, (dir), (dir)
93 @comment node-name, next, previous, up
94 @top WoMan: Browse Unix Manual Pages ``Wo (without) Man''
97 Software Version @value{VERSION}
98 Manual Last Updated @value{UPDATED}
100 @email{F.J.Wright@@qmw.ac.uk, Francis J. Wright}
101 @uref{http://centaur.maths.qmw.ac.uk/, School of Mathematical Sciences}
102 Queen Mary and Westfield College (University of London)
103 Mile End Road, London E1 4NS, UK
108 * Introduction:: Introduction
109 * Background:: Background
110 * Installation:: Installation and Setup
111 * Finding:: Finding and Formatting Man Pages
112 * Browsing:: Browsing Man Pages
113 * Customization:: Customization
114 * Log:: The *WoMan-Log* Buffer
115 * Technical:: Technical Details
116 * Bugs:: Reporting Bugs
117 * Acknowledgements:: Acknowledgements
118 * Command Index:: Command Index
119 * Variable Index:: Variable Index
120 * Keystroke Index:: Keystroke Index
121 * Concept Index:: Concept Index
124 @c ===================================================================
126 @node Introduction, Background, Top, Top
127 @comment node-name, next, previous, up
128 @chapter Introduction
131 This version of WoMan should run with GNU Emacs 20.3 or later on any
132 platform. It has not been tested, and may not run, with any other
133 version of Emacs. It was developed primarily on various versions of
134 Microsoft Windows, but has also been tested on MS-DOS, and various
135 versions of UNIX and GNU/Linux.
137 WoMan is distributed with GNU Emacs 21, and the current source code and
138 documentation files are available from
139 @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web server}.
141 WoMan implements a subset of the formatting performed by the Emacs
142 @code{man} (or @code{manual-entry}) command to format a Unix-style
143 @dfn{manual page} (usually abbreviated to @dfn{man page}) for display,
144 but without calling any external programs. It is intended to emulate
145 the whole of the @code{ROFF -man} macro package, plus those @code{ROFF}
146 requests (@pxref{Background, , Background}) that are most commonly used
147 in man pages. However, the emulation is modified to include the
148 reformatting done by the Emacs @code{man} command. No hyphenation is
153 Much more direct, does not require any external programs. Supports
154 completion on man page names.
156 Not a complete emulation. Currently no support for @code{eqn} or
157 @code{tbl}. Slightly slower for large man pages (but usually faster for
158 small- and medium-size pages).
161 This browser works quite well on simple well-written man files. It
162 works less well on idiosyncratic files that ``break the rules'' or use
163 the more obscure @code{ROFF} requests directly. Current test results
164 are available in the file
165 @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/files/woman.status,
166 @file{woman.status}}.
168 WoMan supports the use of compressed man files via
169 @code{auto-compression-mode} by turning it on if necessary. But you may
170 need to adjust the user option @code{woman-file-compression-regexp}.
171 @xref{Interface Options, , Interface Options}.
173 Brief help on the WoMan interactive commands and user options, all of
174 which begin with the prefix @code{woman-} (or occasionally
175 @code{WoMan-}), is available most easily by loading WoMan and then
176 either running the command @code{woman-mini-help} or selecting the WoMan
177 menu option @samp{Mini Help}.
179 WoMan is (of course) still under development! Please
180 @email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work---I am
181 adding and improving functionality as testing shows that it is
182 necessary. Guidance on reporting bugs is given below. @xref{Bugs, ,
185 @c ===================================================================
187 @node Background, Installation, Introduction, Top
188 @comment node-name, next, previous, up
192 WoMan is a browser for traditional Unix-style manual page documentation.
193 Each such document is conventionally referred to as a @dfn{manual page},
194 or @dfn{man page} for short, even though some are very much longer than
195 one page. A man page is a document written using the Unix ``man''
196 macros, which are themselves written in the NROFF/TROFF text processing
197 markup language. @code{NROFF} and @code{TROFF} are text processors
198 originally written for the UNIX operating system by Joseph F. Ossanna at
199 Bell Laboratories, Murray Hill, New Jersey, USA@. They are closely
200 related, and except in the few cases where the distinction between them
201 is important I will refer to them both ambiguously as @dfn{ROFF}.
203 @code{ROFF} markup consists of @dfn{requests} and @dfn{escape
204 sequences}. A request occupies a complete line and begins with either a
205 period or a single forward quote. An escape sequences is embedded
206 within the input text and begins (by default) with a backslash. The
207 original man macro package defines 20 new @code{ROFF} requests
208 implemented as macros, which were considered to be sufficient for
209 writing man pages. But whilst in principle man pages use only the man
210 macros, in practice a significant number use many other @code{ROFF}
213 The distinction between @code{TROFF} and @code{NROFF} is that
214 @code{TROFF} was designed to drive a phototypesetter whereas
215 @code{NROFF} was designed to produce essentially @sc{ascii} output for a
216 character-based device similar to a teletypewriter (usually abbreviated
217 to ``teletype'' or ``tty''). Hence, @code{TROFF} supports much finer
218 control over output positioning than does @code{NROFF} and can be seen
219 as a forerunner of @TeX{}. Traditionally, man pages are either
220 formatted by @code{TROFF} for typesetting or by @code{NROFF} for
221 printing on a character printer or displaying on a screen. Of course,
222 over the last 25 years or so, the distinction between typeset output on
223 paper and characters on a screen has become blurred by the fact that
224 most screens now support bit-mapped displays, so that any information
225 that can be printed can also be rendered on screen, the only difference
226 being the resolution.
228 Nevertheless, Unix-style manual page documentation is still normally
229 browsed on screen by running a program called @code{man}. This program
230 looks in a predefined set of directories for the man page matching a
231 specified topic, then either formats the source file by running
232 @code{NROFF} or recovers a pre-formatted file, and displays it via a
233 pager such as @code{more}. @code{NROFF} normally formats for a printer,
234 so it paginates the output, numbers the pages, etc., most of which is
235 irrelevant when the document is browsed as a continuous scrollable
236 document on screen. The only concession to on-screen browsing normally
237 implemented by the @code{man} program is to squeeze consecutive blank
238 lines into a single blank line.
240 For some time, Emacs has offered an improved interface for browsing man
241 pages in the form of the Emacs @code{man} (or @code{manual-entry})
242 command, see @ref{Documentation, man, Documentation Commands, emacs, GNU
244 This command runs @code{man} as described above, perhaps in
245 the background, and then post-processes the output to remove much of the
246 @code{NROFF} pagination such as page headers and footers, and places the
247 result into an Emacs buffer. It puts this buffer into a special major
248 mode, which is tailored for man page browsing, and provides a number of
249 useful navigation commands, support for following references, etc. It
250 provides some support for special display faces (fonts), but no special
251 menu or mouse support. The Emacs man package appears to have been
252 developed over about 10 years, from the late 1980s to the late 1990s.
254 There is considerable inefficiency in having @code{NROFF} paginate a
255 document and then removing most of the pagination!
257 WoMan is an Emacs Lisp library that provides an emulation of the
258 functionality of the Emacs @code{man} command, the main difference being
259 that WoMan does not use any external programs. The only situation in
260 which WoMan might use an external program is when the source file is
261 compressed, when WoMan will use the standard Emacs automatic
262 decompression facility, which does call an external program.
264 I began developing WoMan in the Spring of 1997 and the first version was
265 released in May 1997. The original motivation for WoMan was the fact
266 that many GNU and Unix programs are ported to other platforms and come
267 with Unix-style manual page documentation. This may be difficult to
268 read because ports of the Unix-style @code{man} program can be a little
269 awkward to set up. I decided that it should not be too hard to emulate
270 the 20 @code{man} macros directly, without treating them as macros and
271 largely ignoring the underlying @code{ROFF} requests, given the text
272 processing capabilities of Emacs. This proved to be essentially true,
273 and it did not take a great deal of work to be able to format simple man
276 One problem arose with the significant number of man pages that use
277 @code{ROFF} requests in addition to the @code{man} macros, and since
278 releasing the first version of WoMan I have been continually extending
279 it to support more @code{ROFF} requests. WoMan can now format a
280 significant proportion of the man pages that I have tested, either well
281 or at least readably. However, I have added capabilities partly by
282 making additional passes through the document, a design that is
283 fundamentally flawed. This can only be solved by a major re-design of
284 WoMan to handle the major formatting within a single recursive pass,
285 rather than the present multiple passes without any significant
286 recursion. There are some @code{ROFF} requests that cannot be handled
287 satisfactorily within the present design. Some of these are currently
288 handled by kludges that ``usually more or less work.''
290 The principle advantage of WoMan is that it does not require @code{man},
291 and indeed the name WoMan is a contraction of ``without man.'' But it
292 has other advantages. It does not paginate the document, so it does not
293 need to un-paginate it again, thereby saving time. It could take full
294 advantage of the display capabilities available to it, and I hope to
295 develop WoMan to take advantage of developments in Emacs itself. At
296 present, WoMan uses several display faces to support bold and italic
297 text, to indicate other fonts, etc. The default faces are also
298 coloured, but the choice of faces is customizable. WoMan provides menu
299 support for navigation and mouse support for following references, in
300 addition to the navigation facilities provided by @code{man} mode.
301 WoMan has (this) texinfo documentation!
303 WoMan @emph{does not} replace @code{man}, although it does use a number
304 of the facilities implemented in the Emacs @code{man} library. WoMan
305 and man can happily co-exist, which is very useful for comparison and
306 debugging purposes. The only way in which WoMan affects @code{man} is
307 that it adds a timer to indicate how long @code{man} has taken to format
308 a man page. The timing is as compatible as possible with the timing
309 built into WoMan, for as fair a comparison as possible. The time
310 comparison seems to depend on the details of the platform, the version
311 of @code{man} in use, etc, but times are similar and WoMan is never
312 significantly slower than @code{man}. This is despite the fact that
313 WoMan is running byte code whereas most of the formatting done by
314 @code{man} uses machine code, and is a testimony to the quality of the
317 @code{NROFF} simulates non-@sc{ascii} characters by using one or more
318 @sc{ascii} characters. WoMan should be able to do much better than
319 this. I have recently begun to add support for WoMan to use more of the
320 characters in its default font and to use a symbol font, and it is an
321 aspect that I intend to develop further in the near future. It should
322 be possible to move WoMan from an emulation of @code{NROFF} to an
323 emulation of @code{TROFF} as GNU Emacs moves to providing bit-mapped
326 @c ===================================================================
328 @node Installation, Finding, Background, Top
329 @comment node-name, next, previous, up
330 @chapter Installation and Setup
334 No installation is necessary if you just want to run the version of
335 WoMan distributed with GNU Emacs 21 or later, although some additional
336 setup may still be desirable.
338 If you are installing @file{woman.el}, either to update the version
339 distributed with GNU Emacs or because WoMan was not distributed with
340 your version of Emacs, then you need to put the file in a directory in
341 your Emacs load path and byte compile it. A good directory to use is
342 the @file{site-lisp} directory in your Emacs file tree, e.g.@:
343 @file{/usr/local/share/emacs/@var{version}/site-lisp/} (where
344 @var{version} is your Emacs version), provided you have write access to
345 it. If you use a directory that is not included by default in your
346 Emacs load path then you need to add something like this to your
347 @file{.emacs} initialisation file:
350 (add-to-list 'load-path "my-lisp")
354 where @file{my-lisp} is the pathname of the directory. @xref{Init File, ,
355 The Init File ~/.emacs, emacs, The Emacs Editor}, for further details on
356 customizing Emacs in general.
358 You can byte-compile the file by using the Emacs command
359 @code{byte-compile-file} or by opening the directory containing the
360 file, putting point on it and pressing the key @kbd{B}. (In fact, if
361 the file is compiled then it is only the compiled file that needs to be
362 in the Emacs load path, but leaving the source file there will do no
367 Setup that is either necessary or desirable consists of adding a small
368 amount of Emacs Lisp code to your @file{.emacs} initialisation file. It
369 may be necessary (or at least convenient) to make WoMan autoload (if you
370 are not running GNU Emacs 21 or later) and to set the search path used
371 by the @code{woman} interface. You may also find it convenient to make
372 various WoMan menu and key bindings available and to make WoMan
373 customizable even before WoMan has been loaded.
375 It is possible to run WoMan from a command line (from outside or even
376 from inside Emacs) by suitably configuring your command interpreter.
379 * Autoloading:: Autoloading
380 * Search Path:: Search Path
381 * Auto Bindings:: Preloading Menu and Key Bindings
382 * Auto Customization:: Preloading Customization
383 * Command Line:: Command Line Access
387 @node Autoloading, Search Path, Installation, Installation
388 @comment node-name, next, previous, up
392 If you are not running GNU Emacs 21 or later then you are recommended to
393 add these autoloads to your @file{.emacs} file:
396 (autoload 'woman "woman"
397 "Decode and browse a Unix man page." t)
398 (autoload 'woman-find-file "woman"
399 "Find, decode and browse a specific Unix man-page file." t)
400 (autoload 'woman-dired-find-file "woman"
401 "In dired, run the WoMan man-page browser on this file." t)
405 (In GNU Emacs 21 and later these autoloads are predefined.)
408 @node Search Path, Auto Bindings, Autoloading, Installation
409 @comment node-name, next, previous, up
413 The next step is necessary if you want to use the friendliest WoMan
414 interface, which is recommended in general. If the @code{MANPATH}
415 environment variable is set then WoMan will use it; alternatively (or
416 additionally), if your platform uses a man configuration file (as do
417 many versions of Linux) then WoMan will use it, provided it can find it.
418 (This may need configuration. @xref{Interface Options, , Interface
419 Options}.) If these mechanisms correctly define the search path for man
420 pages then no further action is required.
422 Otherwise you may need to customize the user option
423 @code{woman-manpath}, and you may also want to customize the user option
424 @code{woman-path}. @xref{Customization, , Customization}. Now you can
425 execute the extended command @code{woman} and enter or select a manual
426 topic using completion, and if necessary select a filename, again using
427 completion. By default, WoMan suggests the word nearest to point in the
428 current buffer as the topic.
431 @node Auto Bindings, Auto Customization, Search Path, Installation
432 @comment node-name, next, previous, up
433 @section Preloading Menu and Key Bindings
434 @cindex preloading menu and key bindings
435 @cindex menu bindings, preloading
436 @cindex key bindings, preloading
437 @cindex bindings, preloading
439 Once WoMan is loaded it adds an item to the @samp{Help} menu and defines
440 one or more keys in dired mode to run WoMan on the current file. If you
441 would like these facilities always to be available, even before WoMan is
442 loaded, then add the following to your @file{.emacs} file:
445 (define-key-after menu-bar-manuals-menu [woman]
446 '(menu-item "Read Man Page (WoMan)..." woman
447 :help "Man-page documentation Without Man") t)
449 (add-hook 'dired-mode-hook
451 (define-key dired-mode-map "W" 'woman-dired-find-file)))
454 (By default, WoMan will automatically define the dired keys @kbd{W} and
455 @kbd{w} when it loads, but only if they are not already defined. This
456 behaviour is controlled by the user option @code{woman-dired-keys}.
457 Note that the @code{dired-x} (dired extra) package binds
458 @code{dired-copy-filename-as-kill} to the key @kbd{w}, although @kbd{W}
459 appears to be unused. The @code{dired-x} package will over-write the
460 WoMan binding for @kbd{w}, whereas (by default) WoMan will not overwrite
461 the @code{dired-x} binding.)
464 @node Auto Customization, Command Line, Auto Bindings, Installation
465 @comment node-name, next, previous, up
466 @section Preloading Customization
467 @cindex preloading customization
468 @cindex customization, preloading
470 WoMan supports the GNU Emacs 20+ customization facility, and puts a
471 customization group called @code{WoMan} in the @code{Help} group under
472 the top-level @code{Emacs} group. In order to be able to customize
473 WoMan without first loading it, add the following to your @file{.emacs}
478 "Browse UNIX manual pages `wo (without) man'."
479 :tag "WoMan" :group 'help :load "woman")
483 @node Command Line, , Auto Customization, Installation
484 @comment node-name, next, previous, up
485 @section Command Line Access
486 @cindex command line access
488 If you really want to square the man-woman circle then you can! If you
489 run the GNU command interpreter @code{bash} then you might care to
490 define the following @code{bash} function in your @code{bash}
491 initialisation file @file{.bashrc}:
494 man() @{ gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; @}
497 If you use a Microsoft command interpreter (@file{command.com} or
498 @file{cmd.exe}) then you can create a file called @file{man.bat}
499 somewhere in your path containing the two lines:
503 gnudoit -q (raise-frame (selected-frame)) (woman \"%1\")
506 and then (e.g.@: from a command prompt or the @samp{Run...} option in the
507 Windows @samp{Start} menu) just execute
513 (Of course, if you already have a @code{man} command installed then you
514 could call these commands @code{woman} instead of @code{man}.)
516 The above examples assume that you have the @code{gnuserv} Emacs
517 client-server package installed (which I recommend). It would be
518 possible to do something similar by calling Emacs directly, but that is
519 less satisfactory, because you are likely to end up with multiple copies
520 of Emacs running, which is generally inelegant, inefficient and
521 inconvenient. If you run a different command interpreter then something
522 similar to the above suggestions should be possible.
524 @c ===================================================================
526 @node Finding, Browsing, Installation, Top
527 @comment node-name, next, previous, up
528 @chapter Finding and Formatting Man Pages
529 @cindex using, finding man pages
530 @cindex using, formatting man pages
531 @cindex finding man pages
532 @cindex formatting man pages
533 @cindex man pages, finding
534 @cindex man pages, formatting
536 WoMan provides three user interfaces for finding and formatting man pages:
540 a topic interface similar to that provided by the standard Emacs
544 a family of filename interfaces analogous to the standard Emacs
545 @code{view-file} command;
548 an automatic interface that detects the file type from its contents.
549 (This is currently neither well tested, well supported nor recommended!)
552 The topic and filename interfaces support completion in the usual way.
554 The topic interface is generally the most convenient for regular use,
555 although it may require some special setup, especially if your machine
556 does not already have a conventional @code{man} installation (which
557 WoMan tries to detect).
559 The simplest filename interface command @code{woman-find-file} can
560 always be used with no setup at all (provided WoMan is installed and
561 loaded or set up to autoload).
563 The automatic interface always requires special setup.
566 @heading Case-Dependence of Filenames
568 @cindex case-sensitivity
569 @vindex w32-downcase-file-names
570 By default, WoMan ignores case in file pathnames only when it seems
571 appropriate. Microsoft Windows users who want complete case
572 independence should set the special NTEmacs variable
573 @code{w32-downcase-file-names} to @code{t} and use all lower case when
574 setting WoMan file paths.
578 * Topic:: Topic Interface
579 * Filename:: Filename Interface
580 * Automatic:: Automatic Interface
583 @node Topic, Filename, Finding, Finding
584 @comment node-name, next, previous, up
585 @section Topic Interface
586 @cindex topic interface
588 The topic interface is accessed principally via the command
589 @code{woman}. The same command can be accessed via the menu item
590 @samp{Help->Manuals->Read Man Page (WoMan)...} either once WoMan has been
591 loaded or if it is set up specially. @xref{Installation, , Installation
592 and Setup}. The command reads a manual topic in the minibuffer, which
593 can be the @dfn{basename} of a man file anywhere in the man file
594 structure. The ``basename'' in this context means the filename without
595 any directory component and without any extension or suffix components
596 that relate to the file type. So, for example, if there is a compressed
597 source file in Chapter 5 of the UNIX Programmer's Manual with the full
598 pathname @file{/usr/local/man/man5/man.conf.5.gz} then the topic is
599 @code{man.conf}. Provided WoMan is configured correctly, this topic
600 will appear among the completions offered by @code{woman}. If more than
601 one file has the same topic name then WoMan will prompt for which file
602 to format. Completion of topics is case insensitive.
604 Clearly, @code{woman} has to know where to look for man files and there
605 are two customizable user options that store this information:
606 @code{woman-manpath} and @code{woman-path}. @xref{Interface Options, ,
607 Interface Options}. If @code{woman-manpath} is not set explicitly then
608 WoMan tries to pick up the information that would be used by the
609 @code{man} command, as follows. If the environment variable
610 @code{MANPATH} is set, which seems to be the standard mechanism under
611 UNIX, then WoMan parses that. Otherwise, if WoMan can find a
612 configuration file named (by default) @file{man.conf} (or something very
613 similar), which seems to be the standard mechanism under GNU/Linux, then
614 it parses that. To be precise, ``something very similar'' means having
615 two name components separated by a dot and respectively containing
616 @samp{man} and beginning with @samp{conf}, e.g.@: @file{manual.configuration}.
617 The search path and/or precise full path name for this file are set by
618 the value of the customizable user option @code{woman-man.conf-path}.
619 If all else fails, WoMan uses a plausible default man search path.
621 If the above default configuration does not work correctly for any
622 reason then simply customize the value of @code{woman-manpath}. To
623 access man files that are not in a conventional man file hierarchy,
624 customize the value of @code{woman-path} to include the directories
625 containing the files. In this way, @code{woman} can access manual files
626 @emph{anywhere} in the entire file system.
628 There are two differences between @code{woman-manpath} and
629 @code{woman-path}. Firstly, the elements of @code{woman-manpath} must
630 be directories that contain @emph{directories of} man files, whereas the
631 elements of @code{woman-path} must be directories that contain man files
632 @emph{directly}. Secondly, the last directory component of each element
633 of @code{woman-path} is treated as a regular (Emacs) match expression
634 rather than a fixed name, which allows collections of related
635 directories to be specified succinctly.
637 For topic completion to work, WoMan must build a list of all the manual
638 files that it can access, which can be very slow, especially if a
639 network is involved. For this reason, it caches various amounts of
640 information, after which retrieving it from the cache is very fast. If
641 the cache ever gets out of synchronism with reality, running the
642 @code{woman} command with a prefix argument (e.g.@: @kbd{C-u M-x woman})
643 will force it to rebuild its cache. This is necessary only if the names
644 or locations of any man files change; it is not necessary if only their
645 contents change. It would always be necessary if such a change occurred
646 whilst Emacs were running and after WoMan has been loaded. It may be
647 necessary if such a change occurs between Emacs sessions and persistent
648 caching is used, although WoMan can detect some changes that invalidate
649 its cache and rebuild it automatically.
651 Customize the variable @code{woman-cache-filename} to save the cache
652 between Emacs sessions. This is recommended only if the @code{woman}
653 command is too slow the first time it is run in an Emacs session, while
654 it builds its cache in main memory, which @emph{may} be @emph{very}
655 slow. @xref{Cache, , The WoMan Topic Cache}, for further details.
659 * Cache:: The WoMan Topic Cache
660 * Word at point:: Using the ``Word at Point'' as a Topic Suggestion
663 @node Cache, Word at point, Topic, Topic
664 @comment node-name, next, previous, up
665 @subsection The WoMan Topic Cache
669 The amount of information that WoMan caches (in main memory and,
670 optionally, saved to disc) is controlled by the user option
671 @code{woman-cache-level}. There is a trade-off between the speed with
672 which WoMan can find a file and the size of the cache, and the default
673 setting gives a reasonable compromise.
675 The @code{woman} command always performs a certain amount of caching in
676 main memory, but it can also write its cache to the filestore as a
677 persistent cache under control of the user option
678 @code{woman-cache-filename}. If persistent caching is turned on then
679 WoMan re-loads its internal cache from the cache file almost
680 instantaneously, so that there is never any perceptible start-up delay
681 @emph{except} when WoMan rebuilds its cache. Persistent caching is
682 currently turned off by default. This is because users with persistent
683 caching turned on may overlook the need to force WoMan to rebuild its
684 cache the first time they run it after they have installed new man
685 files; with persistent caching turned off, WoMan automatically rebuilds
686 its cache every time it is run in a new Emacs session.
688 A prefix argument always causes the @code{woman} command (only) to
689 rebuild its topic cache, and to re-save it to
690 @code{woman-cache-filename} if this variable has a non-@code{nil} value. This
691 is necessary if the @emph{names} of any of the directories or files in
692 the paths specified by @code{woman-manpath} or @code{woman-path} change.
693 If WoMan user options that affect the cache are changed then WoMan will
694 automatically update its cache file on disc (if one is in use) the next
695 time it is run in a new Emacs session.
698 @node Word at point, , Cache, Topic
699 @comment node-name, next, previous, up
700 @subsection Using the ``Word at Point'' as a Topic Suggestion
701 @cindex word at point
702 @cindex point, word at
704 By default, the @code{woman} command uses the word nearest to point in
705 the current buffer as a suggestion for the topic to look up. The topic
706 must be confirmed or edited in the minibuffer. This suggestion can be
707 turned off, or @code{woman} can use the suggested topic without
708 confirmation if possible, which is controlled by customizing the user
709 option @code{woman-topic-at-point} to @code{nil} or @code{t}
710 respectively. (Its default value is neither @code{nil} nor @code{t},
711 meaning ask for confirmation.)
713 The variable @code{woman-topic-at-point} can also be rebound locally
714 (using @code{let}), which may be useful to provide special private key
715 bindings, e.g.@: this key binding for @kbd{C-c w} runs WoMan on the topic
716 at point without seeking confirmation:
719 (global-set-key "\C-cw"
722 (let ((woman-topic-at-point t))
727 @node Filename, Automatic, Topic, Finding
728 @comment node-name, next, previous, up
729 @section Filename Interface
730 @cindex filename interface
732 The commands in this family are completely independent of the topic
733 interface, caching mechanism, etc.
735 @findex woman-find-file
736 The filename interface is accessed principally via the extended command
737 @code{woman-find-file}, which is available without any configuration at
738 all (provided WoMan is installed and loaded or set up to autoload).
739 This command can be used to browse any accessible man file, regardless
740 of its filename or location. If the file is compressed then automatic
741 file decompression must already be turned on (e.g.@: see the
742 @samp{Help->Options} submenu)---it is turned on automatically only by
743 the @code{woman} topic interface.
745 @findex woman-dired-find-file
746 Once WoMan is loaded (or if specially set up), various additional
747 commands in this family are available. In a dired buffer, the command
748 @code{woman-dired-find-file} allows the file on the same line as point
749 to be formatted and browsed by WoMan. It is bound to the key @kbd{W} in
750 the dired mode map and added to the dired major mode menu. It may also
751 be bound to @kbd{w}, unless this key is bound by another library, which
752 it is by @code{dired-x}, for example. Because it is quite likely that
753 other libraries will extend the capabilities of such a commonly used
754 mode as dired, the precise key bindings added by WoMan to the dired mode
755 map are controlled by the user option @code{woman-dired-keys}.
757 @findex woman-tar-extract-file
758 When a tar (Tape ARchive) file is visited in Emacs, it is opened in tar
759 mode, which parses the tar file and shows a dired-like view of its
760 contents. The WoMan command @code{woman-tar-extract-file} allows the
761 file on the same line as point to be formatted and browsed by WoMan. It
762 is bound to the key @kbd{w} in the tar mode map and added to the tar
765 The command @code{woman-reformat-last-file}, which is bound to the key
766 @kbd{R} in WoMan mode and available on the major mode menu, reformats
767 the last file formatted by WoMan. This may occasionally be useful if
768 formatting parameters, such as the fill column, are changed, or perhaps
769 if the buffer is somehow corrupted.
771 @findex woman-decode-buffer
772 The command @code{woman-decode-buffer} can be used to decode and browse
773 the current buffer if it is visiting a man file, although it is
774 primarily used internally by WoMan.
777 @node Automatic, , Filename, Finding
778 @comment node-name, next, previous, up
779 @section Automatic Interface
780 @cindex automatic interface
782 Emacs provides an interface to detect automatically the format of a file
783 and decode it when it is visited. It is used primarily by the
784 facilities for editing rich (i.e.@: formatted) text, as a way to store
785 formatting information transparently as @sc{ascii} markup. WoMan can in
786 principle use this interface, but it must be configured explicitly.
788 This use of WoMan does not seem to be particularly advantageous, so it
789 is not really supported. It originated during early experiments on how
790 best to implement WoMan, before I implemented the current topic
791 interface, and I subsequently stopped using it. I might revive it as a
792 mechanism for storing pre-formatted WoMan files, somewhat analogous to
793 the standard Unix @code{catman} facility. In the meantime, it exists
794 for anyone who wants to experiment with it. Once it is set up it is
795 simply a question of visiting the file and there is no WoMan-specific
798 To use it, put something like this in your @file{.emacs} file. [The
799 call to @code{set-visited-file-name} is to avoid font-locking triggered
800 by automatic major mode selection.]
803 (autoload 'woman-decode-region "woman")
805 (add-to-list 'format-alist
806 '(man "Unix man-page source format" "\\.\\(TH\\|ig\\) "
807 woman-decode-region nil nil
809 set-visited-file-name
810 (file-name-sans-extension buffer-file-name))))
813 @c ===================================================================
815 @node Browsing, Customization, Finding, Top
816 @comment node-name, next, previous, up
817 @chapter Browsing Man Pages
818 @cindex using, browsing man pages
819 @cindex browsing man pages
820 @cindex man pages, browsing
822 Once a man page has been found and formatted, WoMan provides a browsing
823 interface that is essentially the same as that provided by the standard
824 Emacs @code{man} command (and much of the code is inherited from the
825 @code{man} library, which WoMan currently requires). Many WoMan
826 facilities can be accessed from the WoMan major mode menu as well as via
829 WoMan does not produce any page breaks or page numbers, and in fact does
830 not paginate the man page at all, since this is not appropriate for
831 continuous online browsing. It produces a document header line that is
832 constructed from the standard man page header and footer. Apart from
833 that, the appearance of the formatted man page should be almost
834 identical to what would be produced by @code{man}, with consecutive
835 blank lines squeezed to a single blank line.
838 * Fonts:: Fonts and Faces
839 * Navigation:: Navigation
840 * References:: Following References
841 * Changing:: Changing the Current Man Page
842 * Convenience:: Convenience Key Bindings
843 * Imenu:: Imenu Support; Contents Menu
846 @node Fonts, Navigation, Browsing, Browsing
847 @comment node-name, next, previous, up
848 @section Fonts and Faces
852 Fonts used by @code{ROFF} are handled by WoMan as faces, the details of
853 which are customizable. @xref{Faces, , Faces}. WoMan supports both the
854 italic and bold fonts normally used in man pages, together with a single
855 face to represent all unknown fonts (which are occasionally used in
856 ``non-standard'' man pages, usually to represent a ``typewriter'' font)
857 and a face to indicate additional symbols introduced by WoMan. This
858 currently means the characters ^ and _ used to indicate super- and
859 sub-scripts, which are not displayed well by WoMan.
862 @node Navigation, References, Fonts, Browsing
863 @comment node-name, next, previous, up
867 Man (and hence WoMan) mode can be thought of as a superset of view mode.
868 The buffer cannot be edited, so keys that would normally self-insert are
869 used for navigation. The WoMan key bindings are a minor modification of
870 the @code{man} key bindings.
876 Scroll the man page up the window (@code{scroll-up}).
881 Scroll the man page down the window (@code{scroll-down}).
885 @findex Man-next-section
886 Move point to the Nth next section---default 1 (@code{Man-next-section}).
890 @findex Man-previous-section
891 Move point to Nth previous section---default 1
892 (@code{Man-previous-section}).
896 @findex Man-goto-section
897 Move point to the specified section (@code{Man-goto-section}).
901 @findex Man-goto-see-also-section
902 Move point to the ``SEE ALSO'' section
903 (@code{Man-goto-see-also-section}). Actually the section moved to is
904 described by @code{Man-see-also-regexp}.
908 @node References, Changing, Navigation, Browsing
909 @comment node-name, next, previous, up
910 @section Following References
911 @cindex following references
914 Man pages usually contain a ``SEE ALSO'' section containing references
915 to other man pages. If these man pages are installed then WoMan can
916 easily be directed to follow the reference, i.e.@: to find and format the
917 man page. When the mouse is passed over a correctly formatted reference
918 it is highlighted, in which case clicking the middle button
919 @kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively,
920 when point is over such a reference the key @key{RET} will follow the
923 Any word in the buffer can be used as a reference by clicking
924 @kbd{Mouse-2} over it provided the Meta key is also used (although in
925 general such a ``reference'' will not lead to a man page).
926 Alternatively, the key @kbd{r} allows completion to be used to select a
927 reference to follow, based on the word at point as default.
932 @findex woman-mouse-2
933 Run WoMan with word under mouse as topic (@code{woman-mouse-2}). The
934 word must be mouse-highlighted unless @code{woman-mouse-2} is used with
940 Get the man page for the topic under (or nearest to) point
945 @findex Man-follow-manual-reference
946 Get one of the man pages referred to in the ``SEE ALSO'' section
947 (@code{Man-follow-manual-reference}). Specify which reference to use;
948 default is based on word at point.
952 @node Changing, Convenience, References, Browsing
953 @comment node-name, next, previous, up
954 @section Changing the Current Man Page
955 @cindex changing current man page
956 @cindex current man page, changing
958 The man page currently being browsed by WoMan can be changed in several
959 ways. The command @code{woman} can be invoked to format another man
960 page, or the current WoMan buffer can be buried or killed. WoMan
961 maintains a ring of formatted man pages, and it is possible to move
962 forwards and backwards in this ring by moving to the next or previous
963 man page. It is sometimes useful to reformat the current page, for
964 example after the right margin (the wrap column) or some other
965 formatting parameter has been changed.
967 Buffers formatted by Man and WoMan are completely unrelated, even though
968 some of the commands to manipulate them are superficially the same (and
975 Run the command @code{man} to get a Un*x manual page and put it in a
976 buffer. This command is the top-level command in the man package. It
977 runs a Un*x command to retrieve and clean a man page in the background
978 and places the results in a Man mode (man page browsing) buffer. If a
979 man buffer already exists for this man page, it will display
980 immediately. This works exactly the same if WoMan is loaded, except
981 that the formatting time is displayed in the mini-buffer.
986 Run the command @code{woman} exactly as if the extended command or menu
992 Bury the buffer containing the current man page (@code{Man-quit}),
993 i.e.@: move it to the bottom of the buffer stack.
998 Kill the buffer containing the current man page (@code{Man-kill}),
999 i.e.@: delete it completely so that it can be retrieved only by formatting
1004 @findex WoMan-previous-manpage
1005 Find the previous WoMan buffer (@code{WoMan-previous-manpage}).
1009 @findex WoMan-next-manpage
1010 Find the next WoMan buffer (@code{WoMan-next-manpage}).
1014 @findex woman-reformat-last-file
1015 Call WoMan to reformat the last man page formatted by WoMan
1016 (@code{woman-reformat-last-file}), e.g.@: after changing the fill column.
1020 @node Convenience, Imenu, Changing, Browsing
1021 @comment node-name, next, previous, up
1022 @section Convenience Key Bindings
1023 @cindex convenience key bindings
1024 @cindex key bindings, convenience
1029 @findex negative-argument
1030 Begin a negative numeric argument for the next command
1031 (@code{negative-argument}).
1035 @findex digit-argument
1036 Part of the numeric argument for the next command
1037 (@code{digit-argument}).
1043 @findex beginning-of-buffer
1044 Move point to the beginning of the buffer; leave mark at previous
1045 position (@code{beginning-of-buffer}).
1049 @findex end-of-buffer
1050 Move point to the end of the buffer; leave mark at previous position
1051 (@code{end-of-buffer}).
1055 @findex describe-mode
1056 Display documentation of current major mode and minor modes
1057 (@code{describe-mode}). The major mode description comes first,
1058 followed by the minor modes, each on a separate page.
1062 @node Imenu, , Convenience, Browsing
1063 @comment node-name, next, previous, up
1064 @section Imenu Support; Contents Menu
1065 @cindex imenu support
1066 @cindex contents menu
1068 The WoMan menu provides an option to make a contents menu for the
1069 current man page (using @code{imenu}). Alternatively, if you customize
1070 the option @code{woman-imenu} to @code{t} then WoMan will do it
1071 automatically for every man page. The menu title is set by the option
1072 @code{woman-imenu-title}, which is ``CONTENTS'' by default. The menu
1073 shows manual sections and subsections by default, but you can change
1074 this by customizing @code{woman-imenu-generic-expression}.
1076 WoMan is configured not to replace spaces in an imenu
1077 @code{*Completion*} buffer. For further documentation on the use of
1078 imenu, such as menu sorting, see the source file @file{imenu.el}, which
1079 is distributed with GNU Emacs.
1081 @c ===================================================================
1083 @node Customization, Log, Browsing, Top
1084 @comment node-name, next, previous, up
1085 @chapter Customization
1086 @cindex customization
1088 All WoMan user options are customizable, and it is recommended to change
1089 them only via the standard Emacs customization facilities. WoMan
1090 defines a top-level customization group called @code{WoMan} under the
1091 parent group @code{Help}. The WoMan customization group is available
1092 only once WoMan has been loaded unless it is specially set up to be
1093 automatically available. @xref{Auto Customization, , Preloading
1094 Customization}. It can be accessed either via the standard Emacs
1095 facilities, e.g.@: via the @samp{Help->Customize} submenu, or via the
1096 WoMan major mode menu.
1098 The top-level WoMan group contains only a few general options and three
1099 subgroups. The hooks are provided only for special purposes that, for
1100 example, require code to be executed, and should be changed only via
1101 @code{Customization} or the function @code{add-hook}. Most
1102 customization should be possible via existing user options.
1105 @item woman-show-log
1106 A boolean value that defaults to @code{nil}. If non-@code{nil} then show the
1107 @code{*WoMan-Log*} buffer if appropriate, i.e.@: if any warning messages
1108 are written to it. @xref{Log, , The *WoMan-Log* Buffer}.
1110 @item woman-pre-format-hook
1111 A hook run immediately before formatting a buffer. It might, for
1112 example, be used for face customization. @xref{Faces, , Faces},
1115 @item woman-post-format-hook
1116 A hook run immediately after formatting a buffer. It might, for
1117 example, be used for installing a dynamic menu using @code{imenu}.
1118 (However. in this case it is better to use the built-in WoMan
1119 @code{imenu} support. @xref{Imenu, , Imenu Support; Contents Menu}.)
1122 @heading Customization Subgroups
1125 @item WoMan Interface
1126 These options control the process of locating the appropriate file to
1127 browse, and the appearance of the browsing interface.
1129 @item WoMan Formatting
1130 These options control the layout that WoMan uses to format the man page.
1133 These options control the display faces that WoMan uses to format the
1138 * Interface Options::
1139 * Formatting Options::
1144 @node Interface Options, Formatting Options, Customization, Customization
1145 @comment node-name, next, previous, up
1146 @section Interface Options
1147 @cindex interface options
1149 These options control the process of locating the appropriate file to
1150 browse, and the appearance of the browsing interface.
1153 @item woman-man.conf-path
1154 A list of strings representing directories to search and/or files to try
1155 for a man configuration file. The default is
1158 ("/etc" "/usr/local/lib")
1162 [for GNU/Linux and Cygwin respectively.] A trailing separator (@file{/}
1163 for UNIX etc.) on directories is optional and the filename matched if a
1164 directory is specified is the first to match the regexp
1165 @code{man.*\.conf}. If the environment variable @code{MANPATH} is not
1166 set but a configuration file is found then it is parsed instead (or as
1167 well) to provide a default value for @code{woman-manpath}.
1170 A list of strings representing @emph{directory trees} to search for Unix
1171 manual files. Each element should be the name of a directory that
1172 contains subdirectories of the form @file{man?}, or more precisely
1173 subdirectories selected by the value of @code{woman-manpath-man-regexp}.
1174 Non-directory and unreadable files are ignored.
1176 @cindex @code{MANPATH}, environment variable
1177 If not set then the environment variable @code{MANPATH} is used. If no
1178 such environment variable is found, the default list is determined by
1179 consulting the man configuration file if found. By default this is
1180 expected to be either @file{/etc/man.config} or
1181 @file{/usr/local/lib/man.conf}, which is controlled by the user option
1182 @code{woman-man.conf-path}. An empty substring of @code{MANPATH}
1183 denotes the default list. Otherwise, the default value of this variable
1187 ("/usr/man" "/usr/local/man")
1190 Any environment variables (names of which must have the Unix-style form
1191 @code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
1192 regardless of platform) are evaluated first but each element must
1193 evaluate to a @emph{single} directory name. Trailing @file{/}s are
1194 ignored. (Specific directories in @code{woman-path} are also searched.)
1196 On Microsoft platforms I recommend including drive letters explicitly,
1200 ("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man")
1203 @cindex directory separator character
1204 @cindex @code{MANPATH}, directory separator
1205 The @code{MANPATH} environment variable may be set using DOS
1206 semi-colon-separated or Unix-style colon-separated syntax (but not
1209 @item woman-manpath-man-regexp
1210 A regular expression to match man directories @emph{under} the
1211 @code{woman-manpath} directories. These normally have names of the form
1212 @file{man?}. Its default value is @code{"[Mm][Aa][Nn]"}, which is
1213 case-insensitive mainly for the benefit of Microsoft platforms. Its
1214 purpose is to avoid directories such as @file{cat?}, @file{.},
1218 A list of strings representing @emph{specific directories} to search for
1219 Unix manual files. For example
1225 These directories are searched in addition to the directory trees
1226 specified in @code{woman-manpath}. Each element should be a directory
1227 string or @code{nil}, which represents the current directory when the
1228 path is expanded and cached. However, the last component (only) of each
1229 directory string is treated as a regexp (Emacs, not shell) and the
1230 string is expanded into a list of matching directories. Non-directory
1231 and unreadable files are ignored. The default value on MS-DOS is
1234 ("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]")
1238 and on other platforms is @code{nil}.
1240 Any environment variables (names of which must have the Unix-style form
1241 @code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR},
1242 regardless of platform) are evaluated first but each element must
1243 evaluate to a @emph{single} directory name (regexp, see above). For
1258 Trailing @file{/}s are discarded. (The directory trees in
1259 @code{woman-manpath} are also searched.) On Microsoft platforms I
1260 recommend including drive letters explicitly.
1262 @item woman-cache-level
1263 A positive integer representing the level of topic caching:
1267 cache only the topic and directory lists (uses minimal memory, but not
1270 cache also the directories for each topic (faster, without using much
1273 cache also the actual filenames for each topic (fastest, but uses twice
1277 The default value is currently 2, a good general compromise. If the
1278 @code{woman} command is slow to find files then try 3, which may be
1279 particularly beneficial with large remote-mounted man directories. Run
1280 the @code{woman} command with a prefix argument or delete the cache file
1281 @code{woman-cache-filename} for a change to take effect. (Values < 1
1282 behave like 1; values > 3 behave like 3.)
1284 @item woman-cache-filename
1285 Either a string representing the full pathname of the WoMan directory
1286 and topic cache file, or @code{nil}. It is used to save and restore the
1287 cache between Emacs sessions. This is especially useful with
1288 remote-mounted man page files! The default value of @code{nil}
1289 suppresses this action. The ``standard'' non-@code{nil} filename is
1290 @file{~/.wmncach.el}. Remember that a prefix argument forces the
1291 @code{woman} command to update and re-write the cache.
1293 @item woman-dired-keys
1294 A list of @code{dired} mode keys to be defined to run WoMan on the
1295 current file, e.g.@: @code{("w" "W")} or any non-@code{nil} atom to
1296 automatically define @kbd{w} and @kbd{W} if they are unbound, or
1297 @code{nil} to do nothing. Default is @code{t}.
1299 @item woman-imenu-generic-expression
1300 Imenu support for Sections and Subsections: an alist with elements of
1301 the form @code{(MENU-TITLE REGEXP INDEX)}---see the documentation for
1302 @code{imenu-generic-expression}. Default value is
1305 ((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE
1306 ("*Subsections*" "^ \\([A-Z].*\\)" 1))
1310 A boolean value that defaults to @code{nil}. If non-@code{nil} then WoMan adds
1311 a Contents menu to the menubar by calling @code{imenu-add-to-menubar}.
1313 @item woman-imenu-title
1314 A string representing the title to use if WoMan adds a Contents menu to
1315 the menubar. Default is @code{"CONTENTS"}.
1317 @item woman-topic-at-point
1318 A symbol, which may be either @code{t}, @code{nil} or @code{confirm},
1319 that controls the use by @code{woman} of the ``word at point'' as a
1320 topic suggestion. If it is non-@code{nil} then the @code{woman} command uses
1321 the word at point as an initial topic suggestion when it reads a topic
1322 from the minibuffer; if it is @code{t} then @code{woman} uses the word
1323 at point @emph{without interactive confirmation} if it exists as a
1324 topic. The value @code{confirm} means suggest a topic and ask for
1325 confirmation. The default value is that of
1326 @code{woman-topic-at-point-default}.
1328 @item woman-topic-at-point-default
1329 A symbol, which may be either @code{t}, @code{nil} or @code{confirm},
1330 representing the default value for @code{woman-topic-at-point}. The
1331 default value is @code{confirm}. [The variable
1332 @code{woman-topic-at-point} may be @code{let}-bound when @code{woman} is
1333 loaded, in which case its global value does not get defined. The
1334 function @code{woman-file-name} sets it to this value if it is unbound.]
1336 @item woman-uncompressed-file-regexp
1337 A regular match expression used to select man source files (ignoring any
1338 compression extension). The default value is
1339 @code{"\\.\\([0-9lmnt]\\w*\\)"} [which means a filename extension is
1342 @emph{Do not change this unless you are sure you know what you are doing!}
1344 The SysV standard man pages use two character suffixes, and this is
1345 becoming more common in the GNU world. For example, the man pages in
1346 the @code{ncurses} package include @file{toe.1m}, @file{form.3x}, etc.
1348 @strong{Note:} an optional compression regexp will be appended, so this
1349 regexp @emph{must not} end with any kind of string terminator such as
1350 @code{$} or @code{\\'}.
1352 @item woman-file-compression-regexp
1353 A regular match expression used to match compressed man file extensions
1354 for which decompressors are available and handled by auto-compression
1355 mode. It should begin with @code{\\.} and end with @code{\\'} and
1356 @emph{must not} be optional. The default value is
1357 @code{"\\.\\(g?z\\|bz2\\)\\'"}, which matches the @code{gzip} and
1358 @code{bzip2} compression extensions.
1360 @emph{Do not change this unless you are sure you know what you are doing!}
1362 [It should be compatible with the @code{car} of
1363 @code{jka-compr-file-name-handler-entry}, but that is unduly
1364 complicated, includes an inappropriate extension (@file{.tgz}) and is
1365 not loaded by default!]
1367 @item woman-use-own-frame
1368 If non-@code{nil} then use a dedicated frame for displaying WoMan windows.
1369 This is useful only when WoMan is run under a window system such as X or
1370 Microsoft Windows that supports real multiple frames, in which case the
1371 default value is non-@code{nil}.
1375 @node Formatting Options, Faces, Interface Options, Customization
1376 @comment node-name, next, previous, up
1377 @section Formatting Options
1378 @cindex formatting options
1380 These options control the layout that WoMan uses to format the man page.
1383 @item woman-fill-column
1384 An integer specifying the right margin for formatted text. Default is
1387 @item woman-fill-frame
1388 A boolean value. If non-@code{nil} then most of the frame width is used,
1389 overriding the value of @code{woman-fill-column}. Default is @code{nil}.
1391 @item woman-default-indent
1392 An integer specifying the default prevailing indent for the @code{-man}
1393 macros. Default is 5. Set this variable to 7 to emulate GNU/Linux man
1396 @item woman-bold-headings
1397 A boolean value. If non-@code{nil} then embolden section and subsection
1398 headings. Default is @code{t}. [Heading emboldening is @emph{not} standard
1399 @code{man} behaviour.]
1402 A boolean value. If non-@code{nil} then unrecognised requests etc. are
1403 ignored. Default is @code{t}. This gives the standard @code{ROFF} behaviour.
1404 If @code{nil} then they are left in the buffer, which may aid debugging.
1406 @item woman-preserve-ascii
1407 A boolean value. If non-@code{nil} then preserve @sc{ascii} characters in the
1408 WoMan buffer. Otherwise, non-@sc{ascii} characters (that display as
1409 @sc{ascii}) may remain, which is irrelevant unless the buffer is to be
1410 saved to a file. Default is @code{nil}.
1412 @item woman-emulation
1413 WoMan emulation, currently either @code{NROFF} or @code{TROFF}. Default
1414 is @code{NROFF}. @code{TROFF} emulation is experimental and largely
1419 @node Faces, Special symbols, Formatting Options, Customization
1420 @comment node-name, next, previous, up
1424 These options control the display faces that WoMan uses to format the
1429 A boolean value. If non-@code{nil} then WoMan assumes that face support is
1430 available. It defaults to a non-@code{nil} value if the display supports
1431 either colours or different fonts.
1433 @item woman-italic-face
1434 Face for italic font in man pages. Default: italic, underlined,
1435 foreground red. This is overkill! @code{TROFF} uses just italic;
1436 @code{NROFF} uses just underline. You should probably select either
1437 italic or underline as you prefer, but not both, although italic and
1438 underline work together perfectly well!
1440 @item woman-bold-face
1441 Face for bold font in man pages. Default: bold, foreground blue.
1443 @item woman-unknown-face
1444 Face for all unknown fonts in man pages. Default: foreground brown.
1445 Brown is a good compromise: it is distinguishable from the default but
1446 not enough so as to make font errors look terrible. (Files that use
1447 non-standard fonts seem to do so badly or in idiosyncratic ways!)
1449 @item woman-addition-face
1450 Face for all additions made by WoMan to man pages.
1451 Default: foreground orange.
1455 @node Special symbols, , Faces, Customization
1456 @comment node-name, next, previous, up
1457 @section Special symbols
1458 @cindex special symbols
1460 This section currently applies @emph{only} to Microsoft Windows.
1462 WoMan provides partial experimental support for special symbols,
1463 initially only for MS-Windows and only for MS-Windows fonts. This
1464 includes both non-@sc{ascii} characters from the main text font and use
1465 of a separate symbol font. Later, support will be added for other font
1466 types (e.g.@: @code{bdf} fonts) and for the X Window System. In Emacs
1467 20.7, the current support works partially under Windows 9x but may not
1468 work on any other platform.
1471 @item woman-use-extended-font
1472 A boolean value. If non-@code{nil} then WoMan may use non-@sc{ascii} characters
1473 from the default font. Default is @code{t}.
1475 @item woman-use-symbol-font
1476 A boolean value. If non-@code{nil} then WoMan may use the symbol font.
1477 Default is @code{nil}, mainly because it may change the line spacing (at
1478 least in NTEmacs 20).
1480 @item woman-symbol-font
1481 A string describing the symbol font to use for special characters.
1482 It should be compatible with, and the same size as, the default text font.
1483 Under MS-Windows, the default is
1486 "-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol"
1491 @c ===================================================================
1493 @node Log, Technical, Customization, Top
1494 @comment node-name, next, previous, up
1495 @chapter The *WoMan-Log* Buffer
1499 This is modelled on the Emacs byte-compiler. It logs all files
1500 formatted by WoMan and the time taken. If WoMan finds anything that it
1501 cannot handle then it writes a warning to this buffer. If the variable
1502 @code{woman-show-log} is non-@code{nil} (by default it is @code{nil}) then
1503 WoMan automatically displays this buffer. @xref{Interface Options, ,
1504 Interface Options}. Many WoMan warnings can be completely ignored,
1505 because they are reporting the fact that WoMan has ignored requests that
1506 it is correct for WoMan to ignore. In some future version this level of
1507 paranoia may be reduced, but not until WoMan is deemed more reliable.
1508 At present, all warnings should be treated with some suspicion.
1509 Uninterpreted escape sequences are also logged (in some cases).
1511 By resetting the variable @code{woman-ignore} to @code{nil} (by default
1512 it is @code{t}), uninterpreted @code{ROFF} requests can optionally be
1513 left in the formatted buffer to indicate precisely where they occurred.
1514 @xref{Interface Options, , Interface Options}.
1516 @c ===================================================================
1518 @node Technical, Bugs, Log, Top
1519 @comment node-name, next, previous, up
1520 @chapter Technical Details
1521 @cindex technical details
1522 @cindex horizontal spacing
1523 @cindex spacing, horizontal and vertical
1524 @cindex vertical spacing
1527 @heading Horizontal and vertical spacing and resolution
1529 WoMan currently assumes 10 characters per inch horizontally, hence a
1530 horizontal resolution of 24 basic units, and 5 lines per inch
1531 vertically, hence a vertical resolution of 48 basic units.
1532 (@code{NROFF} uses 240 per inch.)
1534 @heading Vertical spacing and blank lines
1536 The number of consecutive blank lines in the formatted buffer should be
1537 either 0 or 1. A blank line should leave a space like .sp 1.
1538 Current policy is to output vertical space only immediately before text
1541 @c ===================================================================
1543 @node Bugs, Acknowledgements, Technical, Top
1544 @comment node-name, next, previous, up
1545 @chapter Reporting Bugs
1546 @cindex reporting bugs
1547 @cindex bugs, reporting
1549 If WoMan fails completely, or formats a file incorrectly (i.e.@:
1550 obviously wrongly or significantly differently from @code{man}) or
1551 inelegantly, then please
1555 check that you are running the latest version of @file{woman.el}
1556 available from @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web
1560 check that the problem is not already described in the file
1561 @file{woman.status}, also available from
1562 @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, my web site}.
1565 If both of the above are true then please
1566 @email{F.J.Wright@@qmw.ac.uk,email me} the entry from the
1567 @code{*WoMan-Log*} buffer relating to the problem file, together with a
1568 brief description of the problem. Please indicate where you got the man
1569 source file from, but do not send it to me unless I ask you to! Thanks.
1570 (At present WoMan has no automated bug-reporting facility.)
1572 @c ===================================================================
1574 @node Acknowledgements, Command Index, Bugs, Top
1575 @comment node-name, next, previous, up
1576 @chapter Acknowledgements
1577 @cindex acknowledgements
1579 For Heather, Kathryn and Madelyn, the women in my life (although they
1580 will probably never use it)!
1582 I also thank the following for helpful suggestions, bug reports, code
1583 fragments, general interest, etc.:
1586 Jari Aalto, @email{jari.aalto@@cs.tpu.fi}@*
1587 Dean Andrews, @email{dean@@dra.com}@*
1588 Juanma Barranquero, @email{barranquero@@laley-actualidad.es}@*
1589 Karl Berry, @email{kb@@cs.umb.edu}@*
1590 Jim Chapman, @email{jchapman@@netcomuk.co.uk}@*
1591 Frederic Corne, @email{frederic.corne@@erli.fr}@*
1592 Peter Craft, @email{craft@@alacritech.com}@*
1593 Charles Curley, @email{ccurley@@trib.com}@*
1594 Jim Davidson, @email{jdavidso@@teknowledge.com}@*
1595 Kevin D'Elia, @email{Kevin.DElia@@mci.com}@*
1596 John Fitch, @email{jpff@@maths.bath.ac.uk}@*
1597 Hans Frosch, @email{jwfrosch@@rish.b17c.ingr.com}@*
1598 Guy Gascoigne-Piggford, @email{ggp@@informix.com}@*
1599 Brian Gorka, @email{gorkab@@sanchez.com}@*
1600 Nicolai Henriksen, @email{nhe@@lyngso-industri.dk}@*
1601 Thomas Herchenroeder, @email{the@@software-ag.de}@*
1602 Alexander Hinds, @email{ahinds@@thegrid.net}@*
1603 Stefan Hornburg, @email{sth@@hacon.de}@*
1604 Theodore Jump, @email{tjump@@cais.com}@*
1605 Paul Kinnucan, @email{paulk@@mathworks.com}@*
1606 Jonas Linde, @email{jonas@@init.se}@*
1607 Andrew McRae, @email{andrewm@@optimation.co.nz}@*
1608 Howard Melman, @email{howard@@silverstream.com}@*
1609 Dennis Pixton, @email{dennis@@math.binghamton.edu}@*
1610 T. V. Raman, @email{raman@@Adobe.com}@*
1611 Bruce Ravel, @email{bruce.ravel@@nist.gov}@*
1612 Benjamin Riefenstahl, @email{benny@@crocodial.de}@*
1613 Kevin Ruland, @email{kruland@@seistl.com}@*
1614 Tom Schutter, @email{tom@@platte.com}@*
1615 Wei-Xue Shi, @email{wxshi@@ma.neweb.ne.jp}@*
1616 Fabio Somenzi, @email{fabio@@joplin.colorado.edu}@*
1617 Karel Sprenger, @email{ks@@ic.uva.nl}@*
1618 Chris Szurgot, @email{szurgot@@itribe.net}@*
1619 Paul A. Thompson, @email{pat@@po.cwru.edu}@*
1620 Arrigo Triulzi, @email{arrigo@@maths.qmw.ac.uk}@*
1621 Geoff Voelker, @email{voelker@@cs.washington.edu}@*
1622 Eli Zaretskii, @email{eliz@@is.elta.co.il}
1625 @c ===================================================================
1627 @comment END OF MANUAL TEXT
1630 @node Command Index, Variable Index, Acknowledgements, Top
1631 @comment node-name, next, previous, up
1632 @unnumbered Command Index
1636 @node Variable Index, Keystroke Index, Command Index, Top
1637 @comment node-name, next, previous, up
1638 @unnumbered Variable Index
1642 @c Without a page throw here, the page length seems to get reset to the
1643 @c depth of the index that fits on the page after the previous index.
1644 @c This must be a bug!
1648 @node Keystroke Index, Concept Index, Variable Index, Top
1649 @comment node-name, next, previous, up
1650 @unnumbered Keystroke Index
1654 @c Without a page throw here, the page length seems to get reset to the
1655 @c depth of the index that fits on the page after the previous index.
1656 @c This must be a bug!
1660 @node Concept Index, , Keystroke Index, Top
1661 @comment node-name, next, previous, up
1662 @unnumbered Concept Index