Commit | Line | Data |
---|---|---|
a9212536 | 1 | \input texinfo @c -*-texinfo-*- |
a42bec1c | 2 | @c $Id: woman.texi,v 1.6 2001/03/04 07:14:22 rms Exp $ |
a9212536 EZ |
3 | @c %**start of header |
4 | @setfilename ../info/woman | |
a42bec1c | 5 | @settitle WoMan: Browse Unix Manual Pages ``Wo (without) Man'' |
a9212536 | 6 | @c Manual last updated: |
a42bec1c | 7 | @set UPDATED Time-stamp: <2001-03-05 17:10:30 eliz> |
a9212536 EZ |
8 | @c Software version: |
9 | @set VERSION 0.54 (beta) | |
10 | @afourpaper | |
11 | @c With different size paper the printed page breaks will need attention! | |
12 | @c Look for @page and @need commands. | |
13 | @setchapternewpage off | |
14 | @paragraphindent 0 | |
15 | @c %**end of header | |
16 | ||
c45d327a | 17 | @dircategory Emacs |
a9212536 EZ |
18 | @direntry |
19 | * WoMan: (woman). Browse UN*X Manual Pages `Wo (without) Man'. | |
20 | @end direntry | |
21 | ||
22 | @ifinfo | |
a42bec1c | 23 | This file documents WoMan: A program to browse Unix manual pages `wo |
a9212536 EZ |
24 | (without) man'. |
25 | ||
a42bec1c | 26 | Copyright @copyright{} 2001 Free Software Foundation, Inc. |
a9212536 | 27 | |
a42bec1c EZ |
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. | |
a9212536 | 35 | |
a42bec1c EZ |
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.'' | |
a9212536 | 39 | |
a42bec1c EZ |
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. | |
a9212536 EZ |
44 | @end ifinfo |
45 | ||
46 | @finalout | |
47 | ||
48 | @titlepage | |
49 | @title WoMan | |
a42bec1c | 50 | @subtitle Browse Unix Manual Pages ``Wo (without) Man'' |
a9212536 EZ |
51 | @subtitle Software Version @value{VERSION} |
52 | @author Francis J. Wright | |
53 | @sp 2 | |
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/} | |
60 | @sp 2 | |
61 | @author Manual Last Updated @value{UPDATED} | |
62 | ||
63 | @comment The following two commands start the copyright page. | |
64 | @page | |
65 | @vskip 0pt plus 1filll | |
a42bec1c EZ |
66 | @noindent |
67 | Copyright @copyright{} 2001 Free Software Foundation, Inc. | |
68 | ||
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. | |
76 | ||
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.'' | |
80 | ||
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. | |
a9212536 EZ |
85 | @end titlepage |
86 | ||
87 | @contents | |
88 | ||
89 | @c =================================================================== | |
90 | ||
91 | @ifnottex | |
92 | @node Top, Introduction, (dir), (dir) | |
93 | @comment node-name, next, previous, up | |
a42bec1c | 94 | @top WoMan: Browse Unix Manual Pages ``Wo (without) Man'' |
a9212536 EZ |
95 | |
96 | @display | |
97 | Software Version @value{VERSION} | |
98 | Manual Last Updated @value{UPDATED} | |
99 | ||
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 | |
104 | @end display | |
105 | @end ifnottex | |
106 | ||
107 | @menu | |
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 | |
122 | @end menu | |
123 | ||
124 | @c =================================================================== | |
125 | ||
126 | @node Introduction, Background, Top, Top | |
127 | @comment node-name, next, previous, up | |
128 | @chapter Introduction | |
129 | @cindex introduction | |
130 | ||
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 | |
256e6c04 | 135 | versions of UNIX and GNU/Linux. |
a9212536 EZ |
136 | |
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}. | |
140 | ||
141 | WoMan implements a subset of the formatting performed by the Emacs | |
a42bec1c | 142 | @code{man} (or @code{manual-entry}) command to format a Unix-style |
a9212536 EZ |
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 | |
149 | performed. | |
150 | ||
151 | @table @b | |
152 | @item Advantages | |
153 | Much more direct, does not require any external programs. Supports | |
154 | completion on man page names. | |
155 | @item Disadvantages | |
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). | |
159 | @end table | |
160 | ||
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/woman.status, | |
166 | @file{woman.status}}. | |
167 | ||
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}. | |
172 | ||
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}. | |
178 | ||
179 | WoMan is (of course) still under development! Please | |
a42bec1c | 180 | @email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work---I am |
a9212536 EZ |
181 | adding and improving functionality as testing shows that it is |
182 | necessary. Guidance on reporting bugs is given below. @xref{Bugs, , | |
183 | Reporting Bugs}. | |
184 | ||
185 | @c =================================================================== | |
186 | ||
187 | @node Background, Installation, Introduction, Top | |
188 | @comment node-name, next, previous, up | |
189 | @chapter Background | |
190 | @cindex background | |
191 | ||
a42bec1c | 192 | WoMan is a browser for traditional Unix-style manual page documentation. |
a9212536 EZ |
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 | |
a42bec1c | 195 | one page. A man page is a document written using the Unix ``man'' |
a9212536 EZ |
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}. | |
202 | ||
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} | |
211 | requests. | |
212 | ||
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. | |
227 | ||
a42bec1c | 228 | Nevertheless, Unix-style manual page documentation is still normally |
a9212536 EZ |
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. | |
239 | ||
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 | |
243 | Emacs Manual}. | |
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. | |
253 | ||
254 | There is considerable inefficiency in having @code{NROFF} paginate a | |
255 | document and then removing most of the pagination! | |
256 | ||
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. | |
263 | ||
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 | |
a42bec1c EZ |
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 | |
a9212536 EZ |
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 | |
274 | pages acceptably. | |
275 | ||
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 | |
df9d7630 | 288 | handled by kludges that ``usually more or less work.'' |
a9212536 EZ |
289 | |
290 | The principle advantage of WoMan is that it does not require @code{man}, | |
df9d7630 | 291 | and indeed the name WoMan is a contraction of ``without man.'' But it |
a9212536 EZ |
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! | |
302 | ||
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 | |
315 | Emacs Lisp system. | |
316 | ||
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 | |
324 | display facilities. | |
325 | ||
326 | @c =================================================================== | |
327 | ||
328 | @node Installation, Finding, Background, Top | |
329 | @comment node-name, next, previous, up | |
330 | @chapter Installation and Setup | |
331 | @cindex installation | |
332 | @cindex setup | |
333 | ||
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. | |
337 | ||
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: | |
348 | ||
349 | @lisp | |
350 | (add-to-list 'load-path "my-lisp") | |
351 | @end lisp | |
352 | ||
353 | @noindent | |
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. | |
357 | ||
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 | |
363 | harm.) | |
364 | ||
365 | @heading Setup | |
366 | ||
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. | |
374 | ||
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. | |
377 | ||
378 | @menu | |
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 | |
384 | @end menu | |
385 | ||
386 | ||
387 | @node Autoloading, Search Path, Installation, Installation | |
388 | @comment node-name, next, previous, up | |
389 | @section Autoloading | |
390 | @cindex autoloading | |
391 | ||
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: | |
394 | ||
395 | @lisp | |
396 | (autoload 'woman "woman" | |
a42bec1c | 397 | "Decode and browse a Unix man page." t) |
a9212536 | 398 | (autoload 'woman-find-file "woman" |
a42bec1c | 399 | "Find, decode and browse a specific Unix man-page file." t) |
a9212536 EZ |
400 | (autoload 'woman-dired-find-file "woman" |
401 | "In dired, run the WoMan man-page browser on this file." t) | |
402 | @end lisp | |
403 | ||
404 | @noindent | |
405 | (In GNU Emacs 21 and later these autoloads are predefined.) | |
406 | ||
407 | ||
408 | @node Search Path, Auto Bindings, Autoloading, Installation | |
409 | @comment node-name, next, previous, up | |
410 | @section Search Path | |
411 | @cindex search path | |
412 | ||
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. | |
421 | ||
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. | |
429 | ||
430 | ||
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 | |
438 | ||
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: | |
443 | ||
444 | @lisp | |
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) | |
448 | ||
449 | (add-hook 'dired-mode-hook | |
450 | (lambda () | |
451 | (define-key dired-mode-map "W" 'woman-dired-find-file))) | |
452 | @end lisp | |
453 | ||
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.) | |
462 | ||
463 | ||
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 | |
469 | ||
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} | |
474 | file: | |
475 | ||
476 | @lisp | |
477 | (defgroup woman nil | |
478 | "Browse UNIX manual pages `wo (without) man'." | |
479 | :tag "WoMan" :group 'help :load "woman") | |
480 | @end lisp | |
481 | ||
482 | ||
483 | @node Command Line, , Auto Customization, Installation | |
484 | @comment node-name, next, previous, up | |
485 | @section Command Line Access | |
486 | @cindex command line access | |
487 | ||
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}: | |
492 | ||
493 | @example | |
494 | man() @{ gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; @} | |
495 | @end example | |
496 | ||
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: | |
500 | ||
501 | @example | |
502 | @@echo off | |
503 | gnudoit -q (raise-frame (selected-frame)) (woman \"%1\") | |
504 | @end example | |
505 | ||
506 | and then (e.g.@: from a command prompt or the @samp{Run...} option in the | |
507 | Windows @samp{Start} menu) just execute | |
508 | ||
509 | @example | |
510 | man man_page_name | |
511 | @end example | |
512 | ||
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}.) | |
515 | ||
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. | |
523 | ||
524 | @c =================================================================== | |
525 | ||
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 | |
535 | ||
536 | WoMan provides three user interfaces for finding and formatting man pages: | |
537 | ||
538 | @itemize @bullet | |
539 | @item | |
540 | a topic interface similar to that provided by the standard Emacs | |
541 | @code{man} command; | |
542 | ||
543 | @item | |
544 | a family of filename interfaces analogous to the standard Emacs | |
545 | @code{view-file} command; | |
546 | ||
547 | @item | |
548 | an automatic interface that detects the file type from its contents. | |
549 | (This is currently neither well tested, well supported nor recommended!) | |
550 | @end itemize | |
551 | ||
552 | The topic and filename interfaces support completion in the usual way. | |
553 | ||
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). | |
558 | ||
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). | |
562 | ||
563 | The automatic interface always requires special setup. | |
564 | ||
565 | ||
566 | @heading Case-Dependence of Filenames | |
567 | ||
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. | |
575 | ||
576 | ||
577 | @menu | |
578 | * Topic:: Topic Interface | |
579 | * Filename:: Filename Interface | |
580 | * Automatic:: Automatic Interface | |
581 | @end menu | |
582 | ||
583 | @node Topic, Filename, Finding, Finding | |
584 | @comment node-name, next, previous, up | |
585 | @section Topic Interface | |
586 | @cindex topic interface | |
587 | ||
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. | |
603 | ||
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 | |
df9d7630 | 616 | @samp{man} and beginning with @samp{conf}, e.g.@: @file{manual.configuration}. |
a9212536 EZ |
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. | |
620 | ||
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. | |
627 | ||
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. | |
636 | ||
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. | |
650 | ||
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. | |
656 | ||
657 | ||
658 | @menu | |
659 | * Cache:: The WoMan Topic Cache | |
660 | * Word at point:: Using the ``Word at Point'' as a Topic Suggestion | |
661 | @end menu | |
662 | ||
663 | @node Cache, Word at point, Topic, Topic | |
664 | @comment node-name, next, previous, up | |
665 | @subsection The WoMan Topic Cache | |
666 | @cindex topic cache | |
667 | @cindex cache, topic | |
668 | ||
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. | |
674 | ||
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. | |
687 | ||
688 | A prefix argument always causes the @code{woman} command (only) to | |
689 | rebuild its topic cache, and to re-save it to | |
256e6c04 | 690 | @code{woman-cache-filename} if this variable has a non-@code{nil} value. This |
a9212536 EZ |
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. | |
696 | ||
697 | ||
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 | |
703 | ||
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.) | |
712 | ||
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: | |
717 | ||
718 | @lisp | |
719 | (global-set-key "\C-cw" | |
720 | (lambda () | |
721 | (interactive) | |
722 | (let ((woman-topic-at-point t)) | |
723 | (woman)))) | |
724 | @end lisp | |
725 | ||
726 | ||
727 | @node Filename, Automatic, Topic, Finding | |
728 | @comment node-name, next, previous, up | |
729 | @section Filename Interface | |
730 | @cindex filename interface | |
731 | ||
732 | The commands in this family are completely independent of the topic | |
733 | interface, caching mechanism, etc. | |
734 | ||
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 | |
a42bec1c | 742 | @samp{Help->Options} submenu)---it is turned on automatically only by |
a9212536 EZ |
743 | the @code{woman} topic interface. |
744 | ||
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}. | |
756 | ||
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 | |
763 | major mode menu. | |
764 | ||
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. | |
770 | ||
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. | |
775 | ||
776 | ||
777 | @node Automatic, , Filename, Finding | |
778 | @comment node-name, next, previous, up | |
779 | @section Automatic Interface | |
780 | @cindex automatic interface | |
781 | ||
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. | |
787 | ||
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 | |
a42bec1c | 793 | the standard Unix @code{catman} facility. In the meantime, it exists |
a9212536 EZ |
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 | |
796 | user interface! | |
797 | ||
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.] | |
801 | ||
802 | @lisp | |
803 | (autoload 'woman-decode-region "woman") | |
804 | ||
805 | (add-to-list 'format-alist | |
a42bec1c | 806 | '(man "Unix man-page source format" "\\.\\(TH\\|ig\\) " |
a9212536 EZ |
807 | woman-decode-region nil nil |
808 | (lambda (arg) | |
809 | set-visited-file-name | |
810 | (file-name-sans-extension buffer-file-name)))) | |
811 | @end lisp | |
812 | ||
813 | @c =================================================================== | |
814 | ||
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 | |
821 | ||
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 | |
827 | key bindings, etc. | |
828 | ||
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. | |
836 | ||
837 | @menu | |
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 | |
844 | @end menu | |
845 | ||
846 | @node Fonts, Navigation, Browsing, Browsing | |
847 | @comment node-name, next, previous, up | |
848 | @section Fonts and Faces | |
849 | @cindex fonts | |
850 | @cindex faces | |
851 | ||
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. | |
860 | ||
861 | ||
862 | @node Navigation, References, Fonts, Browsing | |
863 | @comment node-name, next, previous, up | |
864 | @section Navigation | |
865 | @cindex navigation | |
866 | ||
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. | |
871 | ||
872 | @table @kbd | |
873 | @item @key{SPC} | |
874 | @kindex SPC | |
875 | @findex scroll-up | |
876 | Scroll the man page up the window (@code{scroll-up}). | |
877 | ||
878 | @item @key{DEL} | |
879 | @kindex DEL | |
880 | @findex scroll-down | |
881 | Scroll the man page down the window (@code{scroll-down}). | |
882 | ||
883 | @item n | |
884 | @kindex n | |
885 | @findex Man-next-section | |
a42bec1c | 886 | Move point to the Nth next section---default 1 (@code{Man-next-section}). |
a9212536 EZ |
887 | |
888 | @item p | |
889 | @kindex p | |
890 | @findex Man-previous-section | |
a42bec1c | 891 | Move point to Nth previous section---default 1 |
a9212536 EZ |
892 | (@code{Man-previous-section}). |
893 | ||
894 | @item g | |
895 | @kindex g | |
896 | @findex Man-goto-section | |
897 | Move point to the specified section (@code{Man-goto-section}). | |
898 | ||
899 | @item s | |
900 | @kindex s | |
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}. | |
905 | @end table | |
906 | ||
907 | ||
908 | @node References, Changing, Navigation, Browsing | |
909 | @comment node-name, next, previous, up | |
910 | @section Following References | |
911 | @cindex following references | |
912 | @cindex references | |
913 | ||
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 | |
df9d7630 | 919 | @kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively, |
a9212536 EZ |
920 | when point is over such a reference the key @key{RET} will follow the |
921 | reference. | |
922 | ||
923 | Any word in the buffer can be used as a reference by clicking | |
df9d7630 | 924 | @kbd{Mouse-2} over it provided the Meta key is also used (although in |
a9212536 EZ |
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. | |
928 | ||
929 | @table @kbd | |
df9d7630 RS |
930 | @item @kbd{Mouse-2} |
931 | @kindex Mouse-2 | |
a9212536 EZ |
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 | |
935 | the Meta key. | |
936 | ||
937 | @item @key{RET} | |
938 | @kindex RET | |
939 | @findex man-follow | |
940 | Get the man page for the topic under (or nearest to) point | |
941 | (@code{man-follow}). | |
942 | ||
943 | @item r | |
944 | @kindex r | |
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. | |
949 | @end table | |
950 | ||
951 | ||
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 | |
957 | ||
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. | |
966 | ||
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 | |
969 | share code). | |
970 | ||
971 | @table @kbd | |
972 | @item m | |
973 | @kindex m | |
974 | @findex man | |
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. | |
982 | ||
983 | @item w | |
984 | @kindex w | |
985 | @findex woman | |
986 | Run the command @code{woman} exactly as if the extended command or menu | |
987 | item had been used. | |
988 | ||
989 | @item q | |
990 | @kindex q | |
991 | @findex Man-quit | |
992 | Bury the buffer containing the current man page (@code{Man-quit}), | |
993 | i.e.@: move it to the bottom of the buffer stack. | |
994 | ||
995 | @item k | |
996 | @kindex k | |
997 | @findex Man-kill | |
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 | |
1000 | the page again. | |
1001 | ||
1002 | @item M-p | |
1003 | @kindex M-p | |
1004 | @findex WoMan-previous-manpage | |
1005 | Find the previous WoMan buffer (@code{WoMan-previous-manpage}). | |
1006 | ||
1007 | @item M-n | |
1008 | @kindex M-n | |
1009 | @findex WoMan-next-manpage | |
1010 | Find the next WoMan buffer (@code{WoMan-next-manpage}). | |
1011 | ||
1012 | @item R | |
1013 | @kindex R | |
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. | |
1017 | @end table | |
1018 | ||
1019 | ||
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 | |
1025 | ||
1026 | @table @kbd | |
1027 | @item - | |
1028 | @kindex - | |
1029 | @findex negative-argument | |
1030 | Begin a negative numeric argument for the next command | |
1031 | (@code{negative-argument}). | |
1032 | ||
1033 | @item 0 .. 9 | |
1034 | @kindex 0 .. 9 | |
1035 | @findex digit-argument | |
1036 | Part of the numeric argument for the next command | |
1037 | (@code{digit-argument}). | |
1038 | ||
1039 | @item < | |
1040 | @kindex < | |
1041 | @itemx . | |
1042 | @kindex . | |
1043 | @findex beginning-of-buffer | |
1044 | Move point to the beginning of the buffer; leave mark at previous | |
1045 | position (@code{beginning-of-buffer}). | |
1046 | ||
1047 | @item > | |
1048 | @kindex > | |
1049 | @findex end-of-buffer | |
1050 | Move point to the end of the buffer; leave mark at previous position | |
1051 | (@code{end-of-buffer}). | |
1052 | ||
1053 | @item ? | |
1054 | @kindex ? | |
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. | |
1059 | @end table | |
1060 | ||
1061 | ||
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 | |
1067 | ||
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}. | |
1075 | ||
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. | |
1080 | ||
1081 | @c =================================================================== | |
1082 | ||
1083 | @node Customization, Log, Browsing, Top | |
1084 | @comment node-name, next, previous, up | |
1085 | @chapter Customization | |
1086 | @cindex customization | |
1087 | ||
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. | |
1097 | ||
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. | |
1103 | ||
1104 | @vtable @code | |
1105 | @item woman-show-log | |
256e6c04 | 1106 | A boolean value that defaults to @code{nil}. If non-@code{nil} then show the |
a9212536 EZ |
1107 | @code{*WoMan-Log*} buffer if appropriate, i.e.@: if any warning messages |
1108 | are written to it. @xref{Log, , The *WoMan-Log* Buffer}. | |
1109 | ||
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}, | |
1113 | however. | |
1114 | ||
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}.) | |
1120 | @end vtable | |
1121 | ||
1122 | @heading Customization Subgroups | |
1123 | ||
1124 | @table @code | |
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. | |
1128 | ||
1129 | @item WoMan Formatting | |
1130 | These options control the layout that WoMan uses to format the man page. | |
1131 | ||
1132 | @item WoMan Faces | |
1133 | These options control the display faces that WoMan uses to format the | |
1134 | man page. | |
1135 | @end table | |
1136 | ||
1137 | @menu | |
1138 | * Interface Options:: | |
1139 | * Formatting Options:: | |
1140 | * Faces:: | |
1141 | * Special symbols:: | |
1142 | @end menu | |
1143 | ||
1144 | @node Interface Options, Formatting Options, Customization, Customization | |
1145 | @comment node-name, next, previous, up | |
1146 | @section Interface Options | |
1147 | @cindex interface options | |
1148 | ||
1149 | These options control the process of locating the appropriate file to | |
1150 | browse, and the appearance of the browsing interface. | |
1151 | ||
1152 | @vtable @code | |
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 | |
1156 | ||
1157 | @lisp | |
1158 | ("/etc" "/usr/local/lib") | |
1159 | @end lisp | |
1160 | ||
1161 | @noindent | |
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}. | |
1168 | ||
1169 | @item woman-manpath | |
a42bec1c | 1170 | A list of strings representing @emph{directory trees} to search for Unix |
a9212536 EZ |
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. | |
1175 | ||
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 | |
1184 | is | |
1185 | ||
1186 | @lisp | |
1187 | ("/usr/man" "/usr/local/man") | |
1188 | @end lisp | |
1189 | ||
a42bec1c | 1190 | Any environment variables (names of which must have the Unix-style form |
a9212536 EZ |
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.) | |
1195 | ||
1196 | On Microsoft platforms I recommend including drive letters explicitly, | |
1197 | e.g. | |
1198 | ||
1199 | @lisp | |
1200 | ("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man") | |
1201 | @end lisp | |
1202 | ||
1203 | @cindex directory separator character | |
1204 | @cindex @code{MANPATH}, directory separator | |
1205 | The @code{MANPATH} environment variable may be set using DOS | |
a42bec1c | 1206 | semi-colon-separated or Unix-style colon-separated syntax (but not |
a9212536 EZ |
1207 | mixed). |
1208 | ||
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{.}, | |
1215 | @file{..}, etc. | |
1216 | ||
1217 | @item woman-path | |
1218 | A list of strings representing @emph{specific directories} to search for | |
a42bec1c | 1219 | Unix manual files. For example |
a9212536 EZ |
1220 | |
1221 | @lisp | |
1222 | ("/emacs/etc") | |
1223 | @end lisp | |
1224 | ||
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 | |
1232 | ||
1233 | @lisp | |
1234 | ("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]") | |
1235 | @end lisp | |
1236 | ||
1237 | @noindent | |
1238 | and on other platforms is @code{nil}. | |
1239 | ||
a42bec1c | 1240 | Any environment variables (names of which must have the Unix-style form |
a9212536 EZ |
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 | |
1244 | example | |
1245 | ||
1246 | @lisp | |
1247 | ("$EMACSDATA") | |
1248 | @end lisp | |
1249 | ||
1250 | @noindent | |
1251 | or equivalently | |
1252 | ||
1253 | @lisp | |
1254 | ("$EMACS_DIR/etc") | |
1255 | @end lisp | |
1256 | ||
1257 | @noindent | |
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. | |
1261 | ||
1262 | @item woman-cache-level | |
1263 | A positive integer representing the level of topic caching: | |
1264 | ||
1265 | @enumerate | |
1266 | @item | |
1267 | cache only the topic and directory lists (uses minimal memory, but not | |
1268 | recommended); | |
1269 | @item | |
1270 | cache also the directories for each topic (faster, without using much | |
1271 | more memory); | |
1272 | @item | |
1273 | cache also the actual filenames for each topic (fastest, but uses twice | |
1274 | as much memory). | |
1275 | @end enumerate | |
1276 | ||
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.) | |
1283 | ||
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} | |
256e6c04 | 1289 | suppresses this action. The ``standard'' non-@code{nil} filename is |
a9212536 EZ |
1290 | @file{~/.wmncach.el}. Remember that a prefix argument forces the |
1291 | @code{woman} command to update and re-write the cache. | |
1292 | ||
1293 | @item woman-dired-keys | |
1294 | A list of @code{dired} mode keys to be defined to run WoMan on the | |
256e6c04 | 1295 | current file, e.g.@: @code{("w" "W")} or any non-@code{nil} atom to |
a9212536 EZ |
1296 | automatically define @kbd{w} and @kbd{W} if they are unbound, or |
1297 | @code{nil} to do nothing. Default is @code{t}. | |
1298 | ||
1299 | @item woman-imenu-generic-expression | |
1300 | Imenu support for Sections and Subsections: an alist with elements of | |
a42bec1c | 1301 | the form @code{(MENU-TITLE REGEXP INDEX)}---see the documentation for |
a9212536 EZ |
1302 | @code{imenu-generic-expression}. Default value is |
1303 | ||
1304 | @lisp | |
1305 | ((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE | |
1306 | ("*Subsections*" "^ \\([A-Z].*\\)" 1)) | |
1307 | @end lisp | |
1308 | ||
1309 | @item woman-imenu | |
256e6c04 | 1310 | A boolean value that defaults to @code{nil}. If non-@code{nil} then WoMan adds |
a9212536 EZ |
1311 | a Contents menu to the menubar by calling @code{imenu-add-to-menubar}. |
1312 | ||
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"}. | |
1316 | ||
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 | |
256e6c04 | 1320 | topic suggestion. If it is non-@code{nil} then the @code{woman} command uses |
a9212536 EZ |
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}. | |
1327 | ||
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.] | |
1335 | ||
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 | |
1340 | required]. | |
1341 | ||
1342 | @emph{Do not change this unless you are sure you know what you are doing!} | |
1343 | ||
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. | |
1347 | ||
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{\\'}. | |
1351 | ||
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. | |
1359 | ||
1360 | @emph{Do not change this unless you are sure you know what you are doing!} | |
1361 | ||
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!] | |
1366 | ||
1367 | @item woman-use-own-frame | |
256e6c04 | 1368 | If non-@code{nil} then use a dedicated frame for displaying WoMan windows. |
a9212536 EZ |
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 | |
256e6c04 | 1371 | default value is non-@code{nil}. |
a9212536 EZ |
1372 | @end vtable |
1373 | ||
1374 | ||
1375 | @node Formatting Options, Faces, Interface Options, Customization | |
1376 | @comment node-name, next, previous, up | |
1377 | @section Formatting Options | |
1378 | @cindex formatting options | |
1379 | ||
1380 | These options control the layout that WoMan uses to format the man page. | |
1381 | ||
1382 | @vtable @code | |
1383 | @item woman-fill-column | |
1384 | An integer specifying the right margin for formatted text. Default is | |
1385 | 65. | |
1386 | ||
1387 | @item woman-fill-frame | |
256e6c04 RS |
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}. | |
a9212536 EZ |
1390 | |
1391 | @item woman-default-indent | |
1392 | An integer specifying the default prevailing indent for the @code{-man} | |
256e6c04 | 1393 | macros. Default is 5. Set this variable to 7 to emulate GNU/Linux man |
a9212536 EZ |
1394 | formatting. |
1395 | ||
1396 | @item woman-bold-headings | |
256e6c04 RS |
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 | |
a9212536 EZ |
1399 | @code{man} behaviour.] |
1400 | ||
1401 | @item woman-ignore | |
256e6c04 RS |
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. | |
a9212536 EZ |
1404 | If @code{nil} then they are left in the buffer, which may aid debugging. |
1405 | ||
1406 | @item woman-preserve-ascii | |
256e6c04 | 1407 | A boolean value. If non-@code{nil} then preserve @sc{ascii} characters in the |
a9212536 EZ |
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 | |
256e6c04 | 1410 | saved to a file. Default is @code{nil}. |
a9212536 EZ |
1411 | |
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 | |
1415 | untested. | |
1416 | @end vtable | |
1417 | ||
1418 | ||
1419 | @node Faces, Special symbols, Formatting Options, Customization | |
1420 | @comment node-name, next, previous, up | |
1421 | @section Faces | |
1422 | @cindex faces | |
1423 | ||
1424 | These options control the display faces that WoMan uses to format the | |
1425 | man page. | |
1426 | ||
1427 | @vtable @code | |
1428 | @item woman-fontify | |
256e6c04 RS |
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 | |
a9212536 EZ |
1431 | either colours or different fonts. |
1432 | ||
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! | |
1439 | ||
1440 | @item woman-bold-face | |
1441 | Face for bold font in man pages. Default: bold, foreground blue. | |
1442 | ||
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!) | |
1448 | ||
1449 | @item woman-addition-face | |
1450 | Face for all additions made by WoMan to man pages. | |
1451 | Default: foreground orange. | |
1452 | @end vtable | |
1453 | ||
1454 | ||
1455 | @node Special symbols, , Faces, Customization | |
1456 | @comment node-name, next, previous, up | |
1457 | @section Special symbols | |
1458 | @cindex special symbols | |
1459 | ||
1460 | This section currently applies @emph{only} to Microsoft Windows. | |
1461 | ||
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. | |
1469 | ||
1470 | @vtable @code | |
1471 | @item woman-use-extended-font | |
256e6c04 | 1472 | A boolean value. If non-@code{nil} then WoMan may use non-@sc{ascii} characters |
a9212536 EZ |
1473 | from the default font. Default is @code{t}. |
1474 | ||
1475 | @item woman-use-symbol-font | |
256e6c04 | 1476 | A boolean value. If non-@code{nil} then WoMan may use the symbol font. |
a9212536 EZ |
1477 | Default is @code{nil}, mainly because it may change the line spacing (at |
1478 | least in NTEmacs 20). | |
1479 | ||
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 | |
1484 | ||
1485 | @lisp | |
1486 | "-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol" | |
1487 | @end lisp | |
1488 | @end vtable | |
1489 | ||
1490 | ||
1491 | @c =================================================================== | |
1492 | ||
1493 | @node Log, Technical, Customization, Top | |
1494 | @comment node-name, next, previous, up | |
1495 | @chapter The *WoMan-Log* Buffer | |
1496 | @cindex log buffer | |
1497 | @cindex buffer, log | |
1498 | ||
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 | |
256e6c04 | 1502 | @code{woman-show-log} is non-@code{nil} (by default it is @code{nil}) then |
a9212536 EZ |
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). | |
1510 | ||
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}. | |
1515 | ||
1516 | @c =================================================================== | |
1517 | ||
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 | |
1525 | @cindex resolution | |
1526 | ||
1527 | @heading Horizontal and vertical spacing and resolution | |
1528 | ||
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.) | |
1533 | ||
1534 | @heading Vertical spacing and blank lines | |
1535 | ||
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 | |
1539 | is output. | |
1540 | ||
1541 | @c =================================================================== | |
1542 | ||
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 | |
1548 | ||
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 | |
1552 | ||
1553 | @enumerate a | |
1554 | @item | |
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 | |
1557 | site}, and | |
1558 | ||
1559 | @item | |
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}. | |
1563 | @end enumerate | |
1564 | ||
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.) | |
1571 | ||
1572 | @c =================================================================== | |
1573 | ||
1574 | @node Acknowledgements, Command Index, Bugs, Top | |
1575 | @comment node-name, next, previous, up | |
1576 | @chapter Acknowledgements | |
1577 | @cindex acknowledgements | |
1578 | ||
1579 | For Heather, Kathryn and Madelyn, the women in my life (although they | |
1580 | will probably never use it)! | |
1581 | ||
1582 | I also thank the following for helpful suggestions, bug reports, code | |
1583 | fragments, general interest, etc.: | |
1584 | ||
1585 | @quotation | |
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} | |
1623 | @end quotation | |
1624 | ||
1625 | @c =================================================================== | |
1626 | ||
1627 | @comment END OF MANUAL TEXT | |
1628 | @page | |
1629 | ||
1630 | @node Command Index, Variable Index, Acknowledgements, Top | |
1631 | @comment node-name, next, previous, up | |
1632 | @unnumbered Command Index | |
1633 | ||
1634 | @printindex fn | |
1635 | ||
1636 | @node Variable Index, Keystroke Index, Command Index, Top | |
1637 | @comment node-name, next, previous, up | |
1638 | @unnumbered Variable Index | |
1639 | ||
1640 | @printindex vr | |
1641 | ||
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! | |
1645 | ||
1646 | @page | |
1647 | ||
1648 | @node Keystroke Index, Concept Index, Variable Index, Top | |
1649 | @comment node-name, next, previous, up | |
1650 | @unnumbered Keystroke Index | |
1651 | ||
1652 | @printindex ky | |
1653 | ||
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! | |
1657 | ||
1658 | @page | |
1659 | ||
1660 | @node Concept Index, , Keystroke Index, Top | |
1661 | @comment node-name, next, previous, up | |
1662 | @unnumbered Concept Index | |
1663 | ||
1664 | @printindex cp | |
1665 | ||
1666 | @bye |