Mercurial > emacs
annotate doc/misc/woman.texi @ 111755:350f17da7963
Document byte-to-string in Lisp manual.
* objects.texi (Symbol Type):
* text.texi (Near Point):
* help.texi (Help Functions):
* functions.texi (Mapping Functions): Use string instead of
char-to-string in examples.
* nonascii.texi (Converting Representations): Document
byte-to-string.
* strings.texi (Creating Strings): Don't mention semi-obsolete
function char-to-string.
(String Conversion): Shorten discussion of semi-obsolete function
string-to-char. Link to Converting Representations.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Sun, 21 Nov 2010 13:07:47 -0500 |
parents | a91e94388547 |
children | 5fabe7db5188 376148b31b5e |
rev | line source |
---|---|
84325 | 1 \input texinfo @c -*-texinfo-*- |
2 @c %**start of header | |
84329
3d431f1997d8
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84325
diff
changeset
|
3 @setfilename ../../info/woman |
84325 | 4 @settitle WoMan: Browse Unix Manual Pages ``W.O. (without) Man'' |
96452
a9190e1a1d37
American English spelling fix.
Glenn Morris <rgm@gnu.org>
parents:
95937
diff
changeset
|
5 @c FIXME |
84325 | 6 @c Manual last updated: |
109274
a91e94388547
Minor doc/misc/*.texi direntry fixes.
Glenn Morris <rgm@gnu.org>
parents:
106881
diff
changeset
|
7 @set UPDATED Time-stamp: <Thu 24-Jun-2010 00:06:54 gm on grasmoor> |
84325 | 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 | |
17 @copying | |
18 This file documents WoMan: A program to browse Unix manual pages `W.O. | |
19 (without) man'. | |
20 | |
106881
f450b77810be
(Bugs): Make "Emacs repository" less specific, and the URL for same
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
21 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, |
f450b77810be
(Bugs): Make "Emacs repository" less specific, and the URL for same
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
22 2009, 2010 Free Software Foundation, Inc. |
84325 | 23 |
24 @quotation | |
25 Permission is granted to copy, distribute and/or modify this document | |
99709
6de181810d0f
Relicense all texi files under FDL 1.3 or later.
Glenn Morris <rgm@gnu.org>
parents:
96452
diff
changeset
|
26 under the terms of the GNU Free Documentation License, Version 1.3 or |
84325 | 27 any later version published by the Free Software Foundation; with no |
95937
6f0fce2c3559
Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents:
95874
diff
changeset
|
28 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' |
6f0fce2c3559
Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents:
95874
diff
changeset
|
29 and with the Back-Cover Texts as in (a) below. A copy of the license |
6f0fce2c3559
Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents:
95874
diff
changeset
|
30 is included in the section entitled ``GNU Free Documentation License.'' |
84325 | 31 |
95874
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
32 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
33 modify this GNU manual. Buying copies from the FSF supports it in |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
34 developing GNU and promoting software freedom.'' |
84325 | 35 @end quotation |
36 @end copying | |
37 | |
38 @dircategory Emacs | |
39 @direntry | |
109274
a91e94388547
Minor doc/misc/*.texi direntry fixes.
Glenn Morris <rgm@gnu.org>
parents:
106881
diff
changeset
|
40 * WoMan: (woman). Browse UN*X Manual Pages "W.O. (without) Man". |
84325 | 41 @end direntry |
42 | |
43 @finalout | |
44 | |
45 @titlepage | |
46 @title WoMan | |
47 @subtitle Browse Unix Manual Pages ``W.O. (without) Man'' | |
48 @subtitle Software Version @value{VERSION} | |
49 @author Francis J. Wright | |
50 @sp 2 | |
51 @author School of Mathematical Sciences | |
52 @author Queen Mary and Westfield College | |
53 @author (University of London) | |
54 @author Mile End Road, London E1 4NS, UK | |
55 @author @email{F.J.Wright@@qmul.ac.uk} | |
56 @author @uref{http://centaur.maths.qmw.ac.uk/} | |
57 @c He no longer maintains this manual. | |
58 @sp 2 | |
59 @author Manual Last Updated @value{UPDATED} | |
60 | |
61 @comment The following two commands start the copyright page. | |
62 @page | |
63 @vskip 0pt plus 1filll | |
64 @insertcopying | |
65 @end titlepage | |
66 | |
67 @contents | |
68 | |
69 @c =================================================================== | |
70 | |
71 @ifnottex | |
72 @node Top, Introduction, (dir), (dir) | |
73 @comment node-name, next, previous, up | |
74 @top WoMan: Browse Unix Manual Pages ``W.O. (without) Man'' | |
75 | |
76 @display | |
77 Software Version @value{VERSION} | |
78 Manual Last Updated @value{UPDATED} | |
79 | |
80 @email{F.J.Wright@@qmw.ac.uk, Francis J. Wright} | |
81 @uref{http://centaur.maths.qmw.ac.uk/, School of Mathematical Sciences} | |
82 Queen Mary and Westfield College (University of London) | |
83 Mile End Road, London E1 4NS, UK | |
84 @end display | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
85 |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
100974
diff
changeset
|
86 @insertcopying |
84325 | 87 @end ifnottex |
88 | |
89 @menu | |
90 * Introduction:: Introduction | |
91 * Background:: Background | |
92 * Finding:: Finding and Formatting Man Pages | |
93 * Browsing:: Browsing Man Pages | |
94 * Customization:: Customization | |
95 * Log:: The *WoMan-Log* Buffer | |
96 * Technical:: Technical Details | |
97 * Bugs:: Reporting Bugs | |
98 * Acknowledgements:: Acknowledgements | |
99 * GNU Free Documentation License:: The license for this documentation. | |
100 * Command Index:: Command Index | |
101 * Variable Index:: Variable Index | |
102 * Keystroke Index:: Keystroke Index | |
103 * Concept Index:: Concept Index | |
104 @end menu | |
105 | |
106 @c =================================================================== | |
107 | |
108 @node Introduction, Background, Top, Top | |
109 @comment node-name, next, previous, up | |
110 @chapter Introduction | |
111 @cindex introduction | |
112 | |
113 This version of WoMan should run with GNU Emacs 20.3 or later on any | |
114 platform. It has not been tested, and may not run, with any other | |
115 version of Emacs. It was developed primarily on various versions of | |
116 Microsoft Windows, but has also been tested on MS-DOS, and various | |
117 versions of UNIX and GNU/Linux. | |
118 | |
119 WoMan is distributed with GNU Emacs. In addition, the current source | |
120 code and documentation files are available from | |
121 @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/, the WoMan web | |
122 server}. | |
123 | |
124 WoMan implements a subset of the formatting performed by the Emacs | |
125 @code{man} (or @code{manual-entry}) command to format a Unix-style | |
126 @dfn{manual page} (usually abbreviated to @dfn{man page}) for display, | |
127 but without calling any external programs. It is intended to emulate | |
128 the whole of the @code{roff -man} macro package, plus those @code{roff} | |
129 requests (@pxref{Background, , Background}) that are most commonly used | |
130 in man pages. However, the emulation is modified to include the | |
131 reformatting done by the Emacs @code{man} command. No hyphenation is | |
132 performed. | |
133 | |
134 @table @b | |
135 @item Advantages | |
136 Much more direct, does not require any external programs. Supports | |
137 completion on man page names. | |
138 @item Disadvantages | |
139 Not a complete emulation. Currently no support for @code{eqn} or | |
140 @code{tbl}. Slightly slower for large man pages (but usually faster for | |
141 small- and medium-size pages). | |
142 @end table | |
143 | |
144 This browser works quite well on simple well-written man files. It | |
145 works less well on idiosyncratic files that ``break the rules'' or use | |
146 the more obscure @code{roff} requests directly. Current test results | |
147 are available in the file | |
148 @uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/files/woman.status, | |
149 @file{woman.status}}. | |
150 | |
151 WoMan supports the use of compressed man files via | |
152 @code{auto-compression-mode} by turning it on if necessary. But you may | |
153 need to adjust the user option @code{woman-file-compression-regexp}. | |
154 @xref{Interface Options, , Interface Options}. | |
155 | |
156 Brief help on the WoMan interactive commands and user options, all of | |
157 which begin with the prefix @code{woman-} (or occasionally | |
158 @code{WoMan-}), is available most easily by loading WoMan and then | |
159 either running the command @code{woman-mini-help} or selecting the WoMan | |
160 menu option @samp{Mini Help}. | |
161 | |
162 WoMan is (of course) still under development! Please | |
163 @email{F.J.Wright@@qmw.ac.uk, let me know} what doesn't work---I am | |
164 adding and improving functionality as testing shows that it is | |
165 necessary. Guidance on reporting bugs is given below. @xref{Bugs, , | |
166 Reporting Bugs}. | |
167 | |
168 @c =================================================================== | |
169 | |
170 @node Background, Finding, Introduction, Top | |
171 @comment node-name, next, previous, up | |
172 @chapter Background | |
173 @cindex background | |
174 | |
175 WoMan is a browser for traditional Unix-style manual page documentation. | |
176 Each such document is conventionally referred to as a @dfn{manual page}, | |
177 or @dfn{man page} for short, even though some are very much longer than | |
178 one page. A man page is a document written using the Unix ``man'' | |
179 macros, which are themselves written in the nroff/troff text processing | |
180 markup language. @code{nroff} and @code{troff} are text processors | |
181 originally written for the UNIX operating system by Joseph F. Ossanna at | |
182 Bell Laboratories, Murray Hill, New Jersey, USA@. They are closely | |
183 related, and except in the few cases where the distinction between them | |
184 is important I will refer to them both ambiguously as @code{roff}. | |
185 | |
186 @code{roff} markup consists of @dfn{requests} and @dfn{escape | |
187 sequences}. A request occupies a complete line and begins with either a | |
188 period or a single forward quote. An escape sequences is embedded | |
189 within the input text and begins (by default) with a backslash. The | |
190 original man macro package defines 20 new @code{roff} requests | |
191 implemented as macros, which were considered to be sufficient for | |
192 writing man pages. But whilst in principle man pages use only the man | |
193 macros, in practice a significant number use many other @code{roff} | |
194 requests. | |
195 | |
196 The distinction between @code{troff} and @code{nroff} is that | |
197 @code{troff} was designed to drive a phototypesetter whereas | |
198 @code{nroff} was designed to produce essentially @acronym{ASCII} output for a | |
199 character-based device similar to a teletypewriter (usually abbreviated | |
200 to ``teletype'' or ``tty''). Hence, @code{troff} supports much finer | |
201 control over output positioning than does @code{nroff} and can be seen | |
202 as a forerunner of @TeX{}. Traditionally, man pages are either | |
203 formatted by @code{troff} for typesetting or by @code{nroff} for | |
204 printing on a character printer or displaying on a screen. Of course, | |
205 over the last 25 years or so, the distinction between typeset output on | |
206 paper and characters on a screen has become blurred by the fact that | |
207 most screens now support bit-mapped displays, so that any information | |
208 that can be printed can also be rendered on screen, the only difference | |
209 being the resolution. | |
210 | |
211 Nevertheless, Unix-style manual page documentation is still normally | |
212 browsed on screen by running a program called @code{man}. This program | |
213 looks in a predefined set of directories for the man page matching a | |
214 specified topic, then either formats the source file by running | |
215 @code{nroff} or recovers a pre-formatted file, and displays it via a | |
216 pager such as @code{more}. @code{nroff} normally formats for a printer, | |
217 so it paginates the output, numbers the pages, etc., most of which is | |
218 irrelevant when the document is browsed as a continuous scrollable | |
219 document on screen. The only concession to on-screen browsing normally | |
220 implemented by the @code{man} program is to squeeze consecutive blank | |
221 lines into a single blank line. | |
222 | |
223 For some time, Emacs has offered an improved interface for browsing man | |
224 pages in the form of the Emacs @code{man} (or @code{manual-entry}) | |
225 command, see @ref{Documentation, man, Documentation Commands, emacs, GNU | |
226 Emacs Manual}. | |
227 This command runs @code{man} as described above, perhaps in | |
228 the background, and then post-processes the output to remove much of the | |
229 @code{nroff} pagination such as page headers and footers, and places the | |
230 result into an Emacs buffer. It puts this buffer into a special major | |
231 mode, which is tailored for man page browsing, and provides a number of | |
232 useful navigation commands, support for following references, etc. It | |
233 provides some support for special display faces (fonts), but no special | |
234 menu or mouse support. The Emacs man package appears to have been | |
235 developed over about 10 years, from the late 1980s to the late 1990s. | |
236 | |
237 There is considerable inefficiency in having @code{nroff} paginate a | |
238 document and then removing most of the pagination! | |
239 | |
240 WoMan is an Emacs Lisp library that provides an emulation of the | |
241 functionality of the Emacs @code{man} command, the main difference being | |
242 that WoMan does not use any external programs. The only situation in | |
243 which WoMan might use an external program is when the source file is | |
244 compressed, when WoMan will use the standard Emacs automatic | |
245 decompression facility, which does call an external program. | |
246 | |
247 I began developing WoMan in the Spring of 1997 and the first version was | |
248 released in May 1997. The original motivation for WoMan was the fact | |
249 that many GNU and Unix programs are ported to other platforms and come | |
250 with Unix-style manual page documentation. This may be difficult to | |
251 read because ports of the Unix-style @code{man} program can be a little | |
252 awkward to set up. I decided that it should not be too hard to emulate | |
253 the 20 @code{man} macros directly, without treating them as macros and | |
254 largely ignoring the underlying @code{roff} requests, given the text | |
255 processing capabilities of Emacs. This proved to be essentially true, | |
256 and it did not take a great deal of work to be able to format simple man | |
257 pages acceptably. | |
258 | |
259 One problem arose with the significant number of man pages that use | |
260 @code{roff} requests in addition to the @code{man} macros, and since | |
261 releasing the first version of WoMan I have been continually extending | |
262 it to support more @code{roff} requests. WoMan can now format a | |
263 significant proportion of the man pages that I have tested, either well | |
264 or at least readably. However, I have added capabilities partly by | |
265 making additional passes through the document, a design that is | |
266 fundamentally flawed. This can only be solved by a major re-design of | |
267 WoMan to handle the major formatting within a single recursive pass, | |
268 rather than the present multiple passes without any significant | |
269 recursion. There are some @code{roff} requests that cannot be handled | |
270 satisfactorily within the present design. Some of these are currently | |
271 handled by kludges that ``usually more or less work.'' | |
272 | |
273 The principle advantage of WoMan is that it does not require @code{man}, | |
274 and indeed the name WoMan is a contraction of ``without man.'' But it | |
275 has other advantages. It does not paginate the document, so it does not | |
276 need to un-paginate it again, thereby saving time. It could take full | |
277 advantage of the display capabilities available to it, and I hope to | |
278 develop WoMan to take advantage of developments in Emacs itself. At | |
279 present, WoMan uses several display faces to support bold and italic | |
280 text, to indicate other fonts, etc. The default faces are also | |
281 colored, but the choice of faces is customizable. WoMan provides menu | |
282 support for navigation and mouse support for following references, in | |
283 addition to the navigation facilities provided by @code{man} mode. | |
284 WoMan has (this) texinfo documentation! | |
285 | |
286 WoMan @emph{does not} replace @code{man}, although it does use a number | |
287 of the facilities implemented in the Emacs @code{man} library. WoMan | |
288 and man can happily co-exist, which is very useful for comparison and | |
289 debugging purposes. | |
290 | |
291 @code{nroff} simulates non-@acronym{ASCII} characters by using one or more | |
292 @acronym{ASCII} characters. WoMan should be able to do much better than | |
293 this. I have recently begun to add support for WoMan to use more of the | |
294 characters in its default font and to use a symbol font, and it is an | |
295 aspect that I intend to develop further in the near future. It should | |
296 be possible to move WoMan from an emulation of @code{nroff} to an | |
297 emulation of @code{troff} as GNU Emacs moves to providing bit-mapped | |
298 display facilities. | |
299 | |
300 @node Finding, Browsing, Background, Top | |
301 @comment node-name, next, previous, up | |
302 @chapter Finding and Formatting Man Pages | |
303 @cindex using, finding man pages | |
304 @cindex using, formatting man pages | |
305 @cindex finding man pages | |
306 @cindex formatting man pages | |
307 @cindex man pages, finding | |
308 @cindex man pages, formatting | |
309 | |
310 WoMan provides three user interfaces for finding and formatting man pages: | |
311 | |
312 @itemize @bullet | |
313 @item | |
314 a topic interface similar to that provided by the standard Emacs | |
315 @code{man} command; | |
316 | |
317 @item | |
318 a family of filename interfaces analogous to the standard Emacs | |
319 @code{view-file} command; | |
320 | |
321 @item | |
322 an automatic interface that detects the file type from its contents. | |
323 (This is currently neither well tested, well supported nor recommended!) | |
324 @end itemize | |
325 | |
326 The topic and filename interfaces support completion in the usual way. | |
327 | |
328 The topic interface is generally the most convenient for regular use, | |
329 although it may require some special setup, especially if your machine | |
330 does not already have a conventional @code{man} installation (which | |
331 WoMan tries to detect). | |
332 | |
333 The simplest filename interface command @code{woman-find-file} can | |
334 always be used with no setup at all (provided WoMan is installed and | |
335 loaded or set up to autoload). | |
336 | |
337 The automatic interface always requires special setup. | |
338 | |
339 | |
340 @heading Case-Dependence of Filenames | |
341 | |
342 @cindex case-sensitivity | |
343 @vindex w32-downcase-file-names | |
344 By default, WoMan ignores case in file pathnames only when it seems | |
345 appropriate. Microsoft Windows users who want complete case | |
346 independence should set the special NTEmacs variable | |
347 @code{w32-downcase-file-names} to @code{t} and use all lower case when | |
348 setting WoMan file paths. | |
349 | |
350 | |
351 @menu | |
352 * Topic:: Topic Interface | |
353 * Filename:: Filename Interface | |
354 * Automatic:: Automatic Interface | |
355 @end menu | |
356 | |
357 @node Topic, Filename, Finding, Finding | |
358 @comment node-name, next, previous, up | |
359 @section Topic Interface | |
360 @cindex topic interface | |
361 | |
362 The topic interface is accessed principally via the command | |
363 @code{woman}. The same command can be accessed via the menu item | |
364 @samp{Help->Manuals->Read Man Page (WoMan)...} once WoMan has been | |
365 loaded. The command reads a manual topic in the minibuffer, which can | |
366 be the @dfn{basename} of a man file anywhere in the man file | |
367 structure. The ``basename'' in this context means the filename | |
368 without any directory component and without any extension or suffix | |
369 components that relate to the file type. So, for example, if there is | |
370 a compressed source file in Chapter 5 of the UNIX Programmer's Manual | |
371 with the full pathname @file{/usr/local/man/man5/man.conf.5.gz} then | |
372 the topic is @code{man.conf}. Provided WoMan is configured correctly, | |
373 this topic will appear among the completions offered by @code{woman}. | |
374 If more than one file has the same topic name then WoMan will prompt | |
375 for which file to format. Completion of topics is case insensitive. | |
376 | |
377 Clearly, @code{woman} has to know where to look for man files and there | |
378 are two customizable user options that store this information: | |
379 @code{woman-manpath} and @code{woman-path}. @xref{Interface Options, , | |
380 Interface Options}. If @code{woman-manpath} is not set explicitly then | |
381 WoMan tries to pick up the information that would be used by the | |
382 @code{man} command, as follows. If the environment variable | |
383 @code{MANPATH} is set, which seems to be the standard mechanism under | |
384 UNIX, then WoMan parses that. Otherwise, if WoMan can find a | |
385 configuration file named (by default) @file{man.conf} (or something very | |
386 similar), which seems to be the standard mechanism under GNU/Linux, then | |
387 it parses that. To be precise, ``something very similar'' means | |
388 starting with @samp{man} and ending with @samp{.conf} and possibly more | |
389 lowercase letters, e.g.@: @file{manual.configuration}. | |
390 The search path and/or precise full path name for this file are set by | |
391 the value of the customizable user option @code{woman-man.conf-path}. | |
392 If all else fails, WoMan uses a plausible default man search path. | |
393 | |
394 If the above default configuration does not work correctly for any | |
395 reason then simply customize the value of @code{woman-manpath}. To | |
396 access man files that are not in a conventional man file hierarchy, | |
397 customize the value of @code{woman-path} to include the directories | |
398 containing the files. In this way, @code{woman} can access manual files | |
399 @emph{anywhere} in the entire file system. | |
400 | |
401 There are two differences between @code{woman-manpath} and | |
402 @code{woman-path}. Firstly, the elements of @code{woman-manpath} must | |
403 be directories that contain @emph{directories of} man files, whereas the | |
404 elements of @code{woman-path} must be directories that contain man files | |
405 @emph{directly}. Secondly, the last directory component of each element | |
406 of @code{woman-path} is treated as a regular (Emacs) match expression | |
407 rather than a fixed name, which allows collections of related | |
408 directories to be specified succinctly. Also, elements of | |
409 @code{woman-manpath} can be conses, indicating a mapping from | |
410 @samp{PATH} environment variable components to man directory | |
411 hierarchies. | |
412 | |
413 For topic completion to work, WoMan must build a list of all the manual | |
414 files that it can access, which can be very slow, especially if a | |
415 network is involved. For this reason, it caches various amounts of | |
416 information, after which retrieving it from the cache is very fast. If | |
417 the cache ever gets out of synchronism with reality, running the | |
418 @code{woman} command with a prefix argument (e.g.@: @kbd{C-u M-x woman}) | |
419 will force it to rebuild its cache. This is necessary only if the names | |
420 or locations of any man files change; it is not necessary if only their | |
421 contents change. It would always be necessary if such a change occurred | |
422 whilst Emacs were running and after WoMan has been loaded. It may be | |
423 necessary if such a change occurs between Emacs sessions and persistent | |
424 caching is used, although WoMan can detect some changes that invalidate | |
425 its cache and rebuild it automatically. | |
426 | |
427 Customize the variable @code{woman-cache-filename} to save the cache | |
428 between Emacs sessions. This is recommended only if the @code{woman} | |
429 command is too slow the first time it is run in an Emacs session, while | |
430 it builds its cache in main memory, which @emph{may} be @emph{very} | |
431 slow. @xref{Cache, , The WoMan Topic Cache}, for further details. | |
432 | |
433 | |
434 @menu | |
435 * Cache:: The WoMan Topic Cache | |
436 * Word at point:: Using the ``Word at Point'' as a Topic Suggestion | |
437 @end menu | |
438 | |
439 @node Cache, Word at point, Topic, Topic | |
440 @comment node-name, next, previous, up | |
441 @subsection The WoMan Topic Cache | |
442 @cindex topic cache | |
443 @cindex cache, topic | |
444 | |
445 The amount of information that WoMan caches (in main memory and, | |
446 optionally, saved to disc) is controlled by the user option | |
447 @code{woman-cache-level}. There is a trade-off between the speed with | |
448 which WoMan can find a file and the size of the cache, and the default | |
449 setting gives a reasonable compromise. | |
450 | |
451 The @code{woman} command always performs a certain amount of caching in | |
452 main memory, but it can also write its cache to the filestore as a | |
453 persistent cache under control of the user option | |
454 @code{woman-cache-filename}. If persistent caching is turned on then | |
455 WoMan re-loads its internal cache from the cache file almost | |
456 instantaneously, so that there is never any perceptible start-up delay | |
457 @emph{except} when WoMan rebuilds its cache. Persistent caching is | |
458 currently turned off by default. This is because users with persistent | |
459 caching turned on may overlook the need to force WoMan to rebuild its | |
460 cache the first time they run it after they have installed new man | |
461 files; with persistent caching turned off, WoMan automatically rebuilds | |
462 its cache every time it is run in a new Emacs session. | |
463 | |
464 A prefix argument always causes the @code{woman} command (only) to | |
465 rebuild its topic cache, and to re-save it to | |
466 @code{woman-cache-filename} if this variable has a non-@code{nil} value. This | |
467 is necessary if the @emph{names} of any of the directories or files in | |
468 the paths specified by @code{woman-manpath} or @code{woman-path} change. | |
469 If WoMan user options that affect the cache are changed then WoMan will | |
470 automatically update its cache file on disc (if one is in use) the next | |
471 time it is run in a new Emacs session. | |
472 | |
473 | |
474 @node Word at point, , Cache, Topic | |
475 @comment node-name, next, previous, up | |
476 @subsection Using the ``Word at Point'' as a Topic Suggestion | |
477 @cindex word at point | |
478 @cindex point, word at | |
479 | |
480 By default, the @code{woman} command uses the word nearest to point in | |
481 the current buffer as a suggestion for the topic to look up, if it | |
482 exists as a valid topic. The topic can be confirmed or edited in the | |
483 minibuffer. | |
484 | |
485 You can also bind the variable @code{woman-use-topic-at-point} locally | |
486 to a non-@code{nil} value (using @code{let}), in which case | |
487 @code{woman} will can use the suggested topic without confirmation if | |
488 possible. This may be useful to provide special private key bindings, | |
489 e.g.@: this key binding for @kbd{C-c w} runs WoMan on the topic at | |
490 point without seeking confirmation: | |
491 | |
492 @lisp | |
493 (global-set-key "\C-cw" | |
494 (lambda () | |
495 (interactive) | |
496 (let ((woman-use-topic-at-point t)) | |
497 (woman)))) | |
498 @end lisp | |
499 | |
500 | |
501 @node Filename, Automatic, Topic, Finding | |
502 @comment node-name, next, previous, up | |
503 @section Filename Interface | |
504 @cindex filename interface | |
505 | |
506 The commands in this family are completely independent of the topic | |
507 interface, caching mechanism, etc. | |
508 | |
509 @findex woman-find-file | |
510 The filename interface is accessed principally via the extended command | |
511 @code{woman-find-file}, which is available without any configuration at | |
512 all (provided WoMan is installed and loaded or set up to autoload). | |
513 This command can be used to browse any accessible man file, regardless | |
514 of its filename or location. If the file is compressed then automatic | |
515 file decompression must already be turned on (e.g.@: see the | |
516 @samp{Help->Options} submenu)---it is turned on automatically only by | |
517 the @code{woman} topic interface. | |
518 | |
519 @findex woman-dired-find-file | |
520 Once WoMan is loaded (or if specially set up), various additional | |
521 commands in this family are available. In a dired buffer, the command | |
522 @code{woman-dired-find-file} allows the file on the same line as point | |
523 to be formatted and browsed by WoMan. It is bound to the key @kbd{W} in | |
524 the dired mode map and added to the dired major mode menu. It may also | |
525 be bound to @kbd{w}, unless this key is bound by another library, which | |
526 it is by @code{dired-x}, for example. Because it is quite likely that | |
527 other libraries will extend the capabilities of such a commonly used | |
528 mode as dired, the precise key bindings added by WoMan to the dired mode | |
529 map are controlled by the user option @code{woman-dired-keys}. | |
530 | |
531 @findex woman-tar-extract-file | |
532 When a tar (Tape ARchive) file is visited in Emacs, it is opened in tar | |
533 mode, which parses the tar file and shows a dired-like view of its | |
534 contents. The WoMan command @code{woman-tar-extract-file} allows the | |
535 file on the same line as point to be formatted and browsed by WoMan. It | |
536 is bound to the key @kbd{w} in the tar mode map and added to the tar | |
537 major mode menu. | |
538 | |
539 The command @code{woman-reformat-last-file}, which is bound to the key | |
540 @kbd{R} in WoMan mode and available on the major mode menu, reformats | |
541 the last file formatted by WoMan. This may occasionally be useful if | |
542 formatting parameters, such as the fill column, are changed, or perhaps | |
543 if the buffer is somehow corrupted. | |
544 | |
545 @findex woman-decode-buffer | |
546 The command @code{woman-decode-buffer} can be used to decode and browse | |
547 the current buffer if it is visiting a man file, although it is | |
548 primarily used internally by WoMan. | |
549 | |
550 | |
551 @node Automatic, , Filename, Finding | |
552 @comment node-name, next, previous, up | |
553 @section Automatic Interface | |
554 @cindex automatic interface | |
555 | |
556 Emacs provides an interface to detect automatically the format of a file | |
557 and decode it when it is visited. It is used primarily by the | |
558 facilities for editing rich (i.e.@: formatted) text, as a way to store | |
559 formatting information transparently as @acronym{ASCII} markup. WoMan can in | |
560 principle use this interface, but it must be configured explicitly. | |
561 | |
562 This use of WoMan does not seem to be particularly advantageous, so it | |
563 is not really supported. It originated during early experiments on how | |
564 best to implement WoMan, before I implemented the current topic | |
565 interface, and I subsequently stopped using it. I might revive it as a | |
566 mechanism for storing pre-formatted WoMan files, somewhat analogous to | |
567 the standard Unix @code{catman} facility. In the meantime, it exists | |
568 for anyone who wants to experiment with it. Once it is set up it is | |
569 simply a question of visiting the file and there is no WoMan-specific | |
570 user interface! | |
571 | |
572 To use it, put something like this in your @file{.emacs} file. [The | |
573 call to @code{set-visited-file-name} is to avoid font-locking triggered | |
574 by automatic major mode selection.] | |
575 | |
576 @lisp | |
577 (autoload 'woman-decode-region "woman") | |
578 | |
579 (add-to-list 'format-alist | |
580 '(man "Unix man-page source format" "\\.\\(TH\\|ig\\) " | |
581 woman-decode-region nil nil | |
582 (lambda (arg) | |
583 set-visited-file-name | |
584 (file-name-sans-extension buffer-file-name)))) | |
585 @end lisp | |
586 | |
587 @c =================================================================== | |
588 | |
589 @node Browsing, Customization, Finding, Top | |
590 @comment node-name, next, previous, up | |
591 @chapter Browsing Man Pages | |
592 @cindex using, browsing man pages | |
593 @cindex browsing man pages | |
594 @cindex man pages, browsing | |
595 | |
596 Once a man page has been found and formatted, WoMan provides a browsing | |
597 interface that is essentially the same as that provided by the standard | |
598 Emacs @code{man} command (and much of the code is inherited from the | |
599 @code{man} library, which WoMan currently requires). Many WoMan | |
600 facilities can be accessed from the WoMan major mode menu as well as via | |
601 key bindings, etc. | |
602 | |
603 WoMan does not produce any page breaks or page numbers, and in fact does | |
604 not paginate the man page at all, since this is not appropriate for | |
605 continuous online browsing. It produces a document header line that is | |
606 constructed from the standard man page header and footer. Apart from | |
607 that, the appearance of the formatted man page should be almost | |
608 identical to what would be produced by @code{man}, with consecutive | |
609 blank lines squeezed to a single blank line. | |
610 | |
611 @menu | |
612 * Fonts:: Fonts and Faces | |
613 * Navigation:: Navigation | |
614 * References:: Following References | |
615 * Changing:: Changing the Current Man Page | |
616 * Convenience:: Convenience Key Bindings | |
617 * Imenu:: Imenu Support; Contents Menu | |
618 @end menu | |
619 | |
620 @node Fonts, Navigation, Browsing, Browsing | |
621 @comment node-name, next, previous, up | |
622 @section Fonts and Faces | |
623 @cindex fonts | |
624 @cindex faces | |
625 | |
626 Fonts used by @code{roff} are handled by WoMan as faces, the details of | |
627 which are customizable. @xref{Faces, , Faces}. WoMan supports both the | |
628 italic and bold fonts normally used in man pages, together with a single | |
629 face to represent all unknown fonts (which are occasionally used in | |
630 ``non-standard'' man pages, usually to represent a ``typewriter'' font) | |
631 and a face to indicate additional symbols introduced by WoMan. This | |
632 currently means the characters ^ and _ used to indicate super- and | |
633 sub-scripts, which are not displayed well by WoMan. | |
634 | |
635 | |
636 @node Navigation, References, Fonts, Browsing | |
637 @comment node-name, next, previous, up | |
638 @section Navigation | |
639 @cindex navigation | |
640 | |
641 Man (and hence WoMan) mode can be thought of as a superset of view mode. | |
642 The buffer cannot be edited, so keys that would normally self-insert are | |
643 used for navigation. The WoMan key bindings are a minor modification of | |
644 the @code{man} key bindings. | |
645 | |
646 @table @kbd | |
647 @item @key{SPC} | |
648 @kindex SPC | |
649 @findex scroll-up | |
650 Scroll the man page up the window (@code{scroll-up}). | |
651 | |
652 @item @key{DEL} | |
653 @kindex DEL | |
654 @findex scroll-down | |
655 Scroll the man page down the window (@code{scroll-down}). | |
656 | |
657 @item n | |
658 @kindex n | |
659 @findex Man-next-section | |
660 Move point to the Nth next section---default 1 (@code{Man-next-section}). | |
661 | |
662 @item p | |
663 @kindex p | |
664 @findex Man-previous-section | |
665 Move point to Nth previous section---default 1 | |
666 (@code{Man-previous-section}). | |
667 | |
668 @item g | |
669 @kindex g | |
670 @findex Man-goto-section | |
671 Move point to the specified section (@code{Man-goto-section}). | |
672 | |
673 @item s | |
674 @kindex s | |
675 @findex Man-goto-see-also-section | |
676 Move point to the ``SEE ALSO'' section | |
677 (@code{Man-goto-see-also-section}). Actually the section moved to is | |
678 described by @code{Man-see-also-regexp}. | |
679 @end table | |
680 | |
681 | |
682 @node References, Changing, Navigation, Browsing | |
683 @comment node-name, next, previous, up | |
684 @section Following References | |
685 @cindex following references | |
686 @cindex references | |
687 | |
688 Man pages usually contain a ``SEE ALSO'' section containing references | |
689 to other man pages. If these man pages are installed then WoMan can | |
690 easily be directed to follow the reference, i.e.@: to find and format the | |
691 man page. When the mouse is passed over a correctly formatted reference | |
692 it is highlighted, in which case clicking the middle button | |
693 @kbd{Mouse-2} will cause WoMan to follow the reference. Alternatively, | |
694 when point is over such a reference the key @key{RET} will follow the | |
695 reference. | |
696 | |
697 Any word in the buffer can be used as a reference by clicking | |
698 @kbd{Mouse-2} over it provided the Meta key is also used (although in | |
699 general such a ``reference'' will not lead to a man page). | |
700 Alternatively, the key @kbd{r} allows completion to be used to select a | |
701 reference to follow, based on the word at point as default. | |
702 | |
703 @table @kbd | |
704 @item @kbd{Mouse-2} | |
705 @kindex Mouse-2 | |
706 @findex woman-mouse-2 | |
707 Run WoMan with word under mouse as topic (@code{woman-mouse-2}). The | |
708 word must be mouse-highlighted unless @code{woman-mouse-2} is used with | |
709 the Meta key. | |
710 | |
711 @item @key{RET} | |
712 @kindex RET | |
713 @findex man-follow | |
714 Get the man page for the topic under (or nearest to) point | |
715 (@code{man-follow}). | |
716 | |
717 @item r | |
718 @kindex r | |
719 @findex Man-follow-manual-reference | |
720 Get one of the man pages referred to in the ``SEE ALSO'' section | |
721 (@code{Man-follow-manual-reference}). Specify which reference to use; | |
722 default is based on word at point. | |
723 @end table | |
724 | |
725 | |
726 @node Changing, Convenience, References, Browsing | |
727 @comment node-name, next, previous, up | |
728 @section Changing the Current Man Page | |
729 @cindex changing current man page | |
730 @cindex current man page, changing | |
731 | |
732 The man page currently being browsed by WoMan can be changed in several | |
733 ways. The command @code{woman} can be invoked to format another man | |
734 page, or the current WoMan buffer can be buried or killed. WoMan | |
735 maintains a ring of formatted man pages, and it is possible to move | |
736 forwards and backwards in this ring by moving to the next or previous | |
737 man page. It is sometimes useful to reformat the current page, for | |
738 example after the right margin (the wrap column) or some other | |
739 formatting parameter has been changed. | |
740 | |
741 Buffers formatted by Man and WoMan are completely unrelated, even though | |
742 some of the commands to manipulate them are superficially the same (and | |
743 share code). | |
744 | |
745 @table @kbd | |
746 @item m | |
747 @kindex m | |
748 @findex man | |
749 Run the command @code{man} to get a Un*x manual page and put it in a | |
750 buffer. This command is the top-level command in the man package. It | |
751 runs a Un*x command to retrieve and clean a man page in the background | |
752 and places the results in a Man mode (man page browsing) buffer. If a | |
753 man buffer already exists for this man page, it will display | |
754 immediately. This works exactly the same if WoMan is loaded, except | |
755 that the formatting time is displayed in the mini-buffer. | |
756 | |
757 @item w | |
758 @kindex w | |
759 @findex woman | |
760 Run the command @code{woman} exactly as if the extended command or menu | |
761 item had been used. | |
762 | |
763 @item q | |
764 @kindex q | |
765 @findex Man-quit | |
766 Bury the buffer containing the current man page (@code{Man-quit}), | |
767 i.e.@: move it to the bottom of the buffer stack. | |
768 | |
769 @item k | |
770 @kindex k | |
771 @findex Man-kill | |
772 Kill the buffer containing the current man page (@code{Man-kill}), | |
773 i.e.@: delete it completely so that it can be retrieved only by formatting | |
774 the page again. | |
775 | |
776 @item M-p | |
777 @kindex M-p | |
778 @findex WoMan-previous-manpage | |
779 Find the previous WoMan buffer (@code{WoMan-previous-manpage}). | |
780 | |
781 @item M-n | |
782 @kindex M-n | |
783 @findex WoMan-next-manpage | |
784 Find the next WoMan buffer (@code{WoMan-next-manpage}). | |
785 | |
786 @item R | |
787 @kindex R | |
788 @findex woman-reformat-last-file | |
789 Call WoMan to reformat the last man page formatted by WoMan | |
790 (@code{woman-reformat-last-file}), e.g.@: after changing the fill column. | |
791 @end table | |
792 | |
793 | |
794 @node Convenience, Imenu, Changing, Browsing | |
795 @comment node-name, next, previous, up | |
796 @section Convenience Key Bindings | |
797 @cindex convenience key bindings | |
798 @cindex key bindings, convenience | |
799 | |
800 @table @kbd | |
801 @item - | |
802 @kindex - | |
803 @findex negative-argument | |
804 Begin a negative numeric argument for the next command | |
805 (@code{negative-argument}). | |
806 | |
807 @item 0 .. 9 | |
808 @kindex 0 .. 9 | |
809 @findex digit-argument | |
810 Part of the numeric argument for the next command | |
811 (@code{digit-argument}). | |
812 | |
813 @item < | |
814 @kindex < | |
815 @itemx . | |
816 @kindex . | |
817 @findex beginning-of-buffer | |
818 Move point to the beginning of the buffer; leave mark at previous | |
819 position (@code{beginning-of-buffer}). | |
820 | |
821 @item > | |
822 @kindex > | |
823 @findex end-of-buffer | |
824 Move point to the end of the buffer; leave mark at previous position | |
825 (@code{end-of-buffer}). | |
826 | |
827 @item ? | |
828 @kindex ? | |
829 @findex describe-mode | |
830 Display documentation of current major mode and minor modes | |
831 (@code{describe-mode}). The major mode description comes first, | |
832 followed by the minor modes, each on a separate page. | |
833 @end table | |
834 | |
835 | |
836 @node Imenu, , Convenience, Browsing | |
837 @comment node-name, next, previous, up | |
838 @section Imenu Support; Contents Menu | |
839 @cindex imenu support | |
840 @cindex contents menu | |
841 | |
842 The WoMan menu provides an option to make a contents menu for the | |
843 current man page (using @code{imenu}). Alternatively, if you customize | |
844 the option @code{woman-imenu} to @code{t} then WoMan will do it | |
845 automatically for every man page. The menu title is set by the option | |
846 @code{woman-imenu-title}, which is ``CONTENTS'' by default. The menu | |
847 shows manual sections and subsections by default, but you can change | |
848 this by customizing @code{woman-imenu-generic-expression}. | |
849 | |
850 WoMan is configured not to replace spaces in an imenu | |
851 @code{*Completion*} buffer. For further documentation on the use of | |
852 imenu, such as menu sorting, see the source file @file{imenu.el}, which | |
853 is distributed with GNU Emacs. | |
854 | |
855 @c =================================================================== | |
856 | |
857 @node Customization, Log, Browsing, Top | |
858 @comment node-name, next, previous, up | |
859 @chapter Customization | |
860 @cindex customization | |
861 | |
862 All WoMan user options are customizable, and it is recommended to | |
863 change them only via the standard Emacs customization facilities. | |
864 WoMan defines a top-level customization group called @code{WoMan} | |
865 under the parent group @code{Help}. It can be accessed either via the | |
866 standard Emacs facilities, e.g.@: via the @samp{Help->Customize} | |
867 submenu, or via the WoMan major mode menu. | |
868 | |
869 The top-level WoMan group contains only a few general options and three | |
870 subgroups. The hooks are provided only for special purposes that, for | |
871 example, require code to be executed, and should be changed only via | |
872 @code{Customization} or the function @code{add-hook}. Most | |
873 customization should be possible via existing user options. | |
874 | |
875 @vtable @code | |
876 @item woman-show-log | |
877 A boolean value that defaults to @code{nil}. If non-@code{nil} then show the | |
878 @code{*WoMan-Log*} buffer if appropriate, i.e.@: if any warning messages | |
879 are written to it. @xref{Log, , The *WoMan-Log* Buffer}. | |
880 | |
881 @item woman-pre-format-hook | |
882 A hook run immediately before formatting a buffer. It might, for | |
883 example, be used for face customization. @xref{Faces, , Faces}, | |
884 however. | |
885 | |
886 @item woman-post-format-hook | |
887 A hook run immediately after formatting a buffer. It might, for | |
888 example, be used for installing a dynamic menu using @code{imenu}. | |
889 (However. in this case it is better to use the built-in WoMan | |
890 @code{imenu} support. @xref{Imenu, , Imenu Support; Contents Menu}.) | |
891 @end vtable | |
892 | |
893 @heading Customization Subgroups | |
894 | |
895 @table @code | |
896 @item WoMan Interface | |
897 These options control the process of locating the appropriate file to | |
898 browse, and the appearance of the browsing interface. | |
899 | |
900 @item WoMan Formatting | |
901 These options control the layout that WoMan uses to format the man page. | |
902 | |
903 @item WoMan Faces | |
904 These options control the display faces that WoMan uses to format the | |
905 man page. | |
906 @end table | |
907 | |
908 @menu | |
909 * Interface Options:: | |
910 * Formatting Options:: | |
911 * Faces:: | |
912 * Special symbols:: | |
913 @end menu | |
914 | |
915 @node Interface Options, Formatting Options, Customization, Customization | |
916 @comment node-name, next, previous, up | |
917 @section Interface Options | |
918 @cindex interface options | |
919 | |
920 These options control the process of locating the appropriate file to | |
921 browse, and the appearance of the browsing interface. | |
922 | |
923 @vtable @code | |
924 @item woman-man.conf-path | |
925 A list of strings representing directories to search and/or files to try | |
926 for a man configuration file. The default is | |
927 | |
928 @lisp | |
929 ("/etc" "/usr/local/lib") | |
930 @end lisp | |
931 | |
932 @noindent | |
933 [for GNU/Linux and Cygwin respectively.] A trailing separator (@file{/} | |
934 for UNIX etc.) on directories is optional and the filename matched if a | |
935 directory is specified is the first to match the regexp | |
936 @code{man.*\.conf}. If the environment variable @code{MANPATH} is not | |
937 set but a configuration file is found then it is parsed instead (or as | |
938 well) to provide a default value for @code{woman-manpath}. | |
939 | |
940 @item woman-manpath | |
941 A list of strings representing @emph{directory trees} to search for Unix | |
942 manual files. Each element should be the name of a directory that | |
943 contains subdirectories of the form @file{man?}, or more precisely | |
944 subdirectories selected by the value of @code{woman-manpath-man-regexp}. | |
945 Non-directory and unreadable files are ignored. This can also contain | |
946 conses, with the car indicating a @code{PATH} variable component mapped | |
947 to the directory tree given in the cdr. | |
948 | |
949 @cindex @code{MANPATH}, environment variable | |
950 If not set then the environment variable @code{MANPATH} is used. If no | |
951 such environment variable is found, the default list is determined by | |
952 consulting the man configuration file if found. By default this is | |
953 expected to be either @file{/etc/man.config} or | |
954 @file{/usr/local/lib/man.conf}, which is controlled by the user option | |
955 @code{woman-man.conf-path}. An empty substring of @code{MANPATH} | |
956 denotes the default list. Otherwise, the default value of this variable | |
957 is | |
958 | |
959 @lisp | |
960 ("/usr/man" "/usr/local/man") | |
961 @end lisp | |
962 | |
963 Any environment variables (names of which must have the Unix-style form | |
964 @code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR}, | |
965 regardless of platform) are evaluated first but each element must | |
966 evaluate to a @emph{single} directory name. Trailing @file{/}s are | |
967 ignored. (Specific directories in @code{woman-path} are also searched.) | |
968 | |
969 On Microsoft platforms I recommend including drive letters explicitly, | |
970 e.g. | |
971 | |
972 @lisp | |
973 ("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man") | |
974 @end lisp | |
975 | |
976 @cindex directory separator character | |
977 @cindex @code{MANPATH}, directory separator | |
978 The @code{MANPATH} environment variable may be set using DOS | |
979 semi-colon-separated or Unix-style colon-separated syntax (but not | |
980 mixed). | |
981 | |
982 @item woman-manpath-man-regexp | |
983 A regular expression to match man directories @emph{under} the | |
984 @code{woman-manpath} directories. These normally have names of the form | |
985 @file{man?}. Its default value is @code{"[Mm][Aa][Nn]"}, which is | |
986 case-insensitive mainly for the benefit of Microsoft platforms. Its | |
987 purpose is to avoid directories such as @file{cat?}, @file{.}, | |
988 @file{..}, etc. | |
989 | |
990 @item woman-path | |
991 A list of strings representing @emph{specific directories} to search for | |
992 Unix manual files. For example | |
993 | |
994 @lisp | |
995 ("/emacs/etc") | |
996 @end lisp | |
997 | |
998 These directories are searched in addition to the directory trees | |
999 specified in @code{woman-manpath}. Each element should be a directory | |
1000 string or @code{nil}, which represents the current directory when the | |
1001 path is expanded and cached. However, the last component (only) of each | |
1002 directory string is treated as a regexp (Emacs, not shell) and the | |
1003 string is expanded into a list of matching directories. Non-directory | |
1004 and unreadable files are ignored. The default value on MS-DOS is | |
1005 | |
1006 @lisp | |
1007 ("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]") | |
1008 @end lisp | |
1009 | |
1010 @noindent | |
1011 and on other platforms is @code{nil}. | |
1012 | |
1013 Any environment variables (names of which must have the Unix-style form | |
1014 @code{$NAME}, e.g.@: @code{$HOME}, @code{$EMACSDATA}, @code{$EMACS_DIR}, | |
1015 regardless of platform) are evaluated first but each element must | |
1016 evaluate to a @emph{single} directory name (regexp, see above). For | |
1017 example | |
1018 | |
1019 @lisp | |
1020 ("$EMACSDATA") | |
1021 @end lisp | |
1022 | |
1023 @noindent | |
1024 or equivalently | |
1025 | |
1026 @lisp | |
1027 ("$EMACS_DIR/etc") | |
1028 @end lisp | |
1029 | |
1030 @noindent | |
1031 Trailing @file{/}s are discarded. (The directory trees in | |
1032 @code{woman-manpath} are also searched.) On Microsoft platforms I | |
1033 recommend including drive letters explicitly. | |
1034 | |
1035 @item woman-cache-level | |
1036 A positive integer representing the level of topic caching: | |
1037 | |
1038 @enumerate | |
1039 @item | |
1040 cache only the topic and directory lists (uses minimal memory, but not | |
1041 recommended); | |
1042 @item | |
1043 cache also the directories for each topic (faster, without using much | |
1044 more memory); | |
1045 @item | |
1046 cache also the actual filenames for each topic (fastest, but uses twice | |
1047 as much memory). | |
1048 @end enumerate | |
1049 | |
1050 The default value is currently 2, a good general compromise. If the | |
1051 @code{woman} command is slow to find files then try 3, which may be | |
1052 particularly beneficial with large remote-mounted man directories. Run | |
1053 the @code{woman} command with a prefix argument or delete the cache file | |
1054 @code{woman-cache-filename} for a change to take effect. (Values < 1 | |
1055 behave like 1; values > 3 behave like 3.) | |
1056 | |
1057 @item woman-cache-filename | |
1058 Either a string representing the full pathname of the WoMan directory | |
1059 and topic cache file, or @code{nil}. It is used to save and restore the | |
1060 cache between Emacs sessions. This is especially useful with | |
1061 remote-mounted man page files! The default value of @code{nil} | |
1062 suppresses this action. The ``standard'' non-@code{nil} filename is | |
1063 @file{~/.wmncach.el}. Remember that a prefix argument forces the | |
1064 @code{woman} command to update and re-write the cache. | |
1065 | |
1066 @item woman-dired-keys | |
1067 A list of @code{dired} mode keys to be defined to run WoMan on the | |
1068 current file, e.g.@: @code{("w" "W")} or any non-@code{nil} atom to | |
1069 automatically define @kbd{w} and @kbd{W} if they are unbound, or | |
1070 @code{nil} to do nothing. Default is @code{t}. | |
1071 | |
1072 @item woman-imenu-generic-expression | |
1073 Imenu support for Sections and Subsections: an alist with elements of | |
1074 the form @code{(MENU-TITLE REGEXP INDEX)}---see the documentation for | |
1075 @code{imenu-generic-expression}. Default value is | |
1076 | |
1077 @lisp | |
1078 ((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE | |
1079 ("*Subsections*" "^ \\([A-Z].*\\)" 1)) | |
1080 @end lisp | |
1081 | |
1082 @item woman-imenu | |
1083 A boolean value that defaults to @code{nil}. If non-@code{nil} then WoMan adds | |
1084 a Contents menu to the menubar by calling @code{imenu-add-to-menubar}. | |
1085 | |
1086 @item woman-imenu-title | |
1087 A string representing the title to use if WoMan adds a Contents menu to | |
1088 the menubar. Default is @code{"CONTENTS"}. | |
1089 | |
1090 @item woman-use-topic-at-point | |
1091 A boolean value that defaults to @code{nil}. If non-@code{nil} then | |
1092 the @code{woman} command uses the word at point as the topic, | |
1093 @emph{without interactive confirmation}, if it exists as a topic. | |
1094 | |
1095 @item woman-use-topic-at-point-default | |
1096 A boolean value representing the default value for | |
1097 @code{woman-use-topic-at-point}. The default value is @code{nil}. | |
1098 [The variable @code{woman-use-topic-at-point} may be @code{let}-bound | |
1099 when @code{woman} is loaded, in which case its global value does not | |
1100 get defined. The function @code{woman-file-name} sets it to this | |
1101 value if it is unbound.] | |
1102 | |
1103 @item woman-uncompressed-file-regexp | |
1104 A regular match expression used to select man source files (ignoring any | |
1105 compression extension). The default value is | |
1106 @code{"\\.\\([0-9lmnt]\\w*\\)"} [which means a filename extension is | |
1107 required]. | |
1108 | |
1109 @emph{Do not change this unless you are sure you know what you are doing!} | |
1110 | |
1111 The SysV standard man pages use two character suffixes, and this is | |
1112 becoming more common in the GNU world. For example, the man pages in | |
1113 the @code{ncurses} package include @file{toe.1m}, @file{form.3x}, etc. | |
1114 | |
1115 @strong{Please note:} an optional compression regexp will be appended, | |
1116 so this regexp @emph{must not} end with any kind of string terminator | |
1117 such as @code{$} or @code{\\'}. | |
1118 | |
1119 @item woman-file-compression-regexp | |
1120 A regular match expression used to match compressed man file extensions | |
1121 for which decompressors are available and handled by auto-compression | |
1122 mode. It should begin with @code{\\.} and end with @code{\\'} and | |
1123 @emph{must not} be optional. The default value is | |
1124 @code{"\\.\\(g?z\\|bz2\\)\\'"}, which matches the @code{gzip} and | |
1125 @code{bzip2} compression extensions. | |
1126 | |
1127 @emph{Do not change this unless you are sure you know what you are doing!} | |
1128 | |
1129 [It should be compatible with the @code{car} of | |
1130 @code{jka-compr-file-name-handler-entry}, but that is unduly | |
1131 complicated, includes an inappropriate extension (@file{.tgz}) and is | |
1132 not loaded by default!] | |
1133 | |
1134 @item woman-use-own-frame | |
1135 If non-@code{nil} then use a dedicated frame for displaying WoMan windows. | |
1136 This is useful only when WoMan is run under a window system such as X or | |
1137 Microsoft Windows that supports real multiple frames, in which case the | |
1138 default value is non-@code{nil}. | |
1139 @end vtable | |
1140 | |
1141 | |
1142 @node Formatting Options, Faces, Interface Options, Customization | |
1143 @comment node-name, next, previous, up | |
1144 @section Formatting Options | |
1145 @cindex formatting options | |
1146 | |
1147 These options control the layout that WoMan uses to format the man page. | |
1148 | |
1149 @vtable @code | |
1150 @item woman-fill-column | |
1151 An integer specifying the right margin for formatted text. Default is | |
1152 65. | |
1153 | |
1154 @item woman-fill-frame | |
1155 A boolean value. If non-@code{nil} then most of the frame width is used, | |
1156 overriding the value of @code{woman-fill-column}. Default is @code{nil}. | |
1157 | |
1158 @item woman-default-indent | |
1159 An integer specifying the default prevailing indent for the @code{-man} | |
1160 macros. Default is 5. Set this variable to 7 to emulate GNU/Linux man | |
1161 formatting. | |
1162 | |
1163 @item woman-bold-headings | |
1164 A boolean value. If non-@code{nil} then embolden section and subsection | |
1165 headings. Default is @code{t}. [Heading emboldening is @emph{not} standard | |
1166 @code{man} behavior.] | |
1167 | |
1168 @item woman-ignore | |
96452
a9190e1a1d37
American English spelling fix.
Glenn Morris <rgm@gnu.org>
parents:
95937
diff
changeset
|
1169 A boolean value. If non-@code{nil} then unrecognized requests etc. are |
84325 | 1170 ignored. Default is @code{t}. This gives the standard @code{roff} behavior. |
1171 If @code{nil} then they are left in the buffer, which may aid debugging. | |
1172 | |
1173 @item woman-preserve-ascii | |
1174 A boolean value. If non-@code{nil} then preserve @acronym{ASCII} characters in the | |
1175 WoMan buffer. Otherwise, non-@acronym{ASCII} characters (that display as | |
1176 @acronym{ASCII}) may remain, which is irrelevant unless the buffer is to be | |
1177 saved to a file. Default is @code{nil}. | |
1178 | |
1179 @item woman-emulation | |
1180 WoMan emulation, currently either @code{nroff} or @code{troff}. Default | |
1181 is @code{nroff}. @code{troff} emulation is experimental and largely | |
1182 untested. | |
1183 @end vtable | |
1184 | |
1185 | |
1186 @node Faces, Special symbols, Formatting Options, Customization | |
1187 @comment node-name, next, previous, up | |
1188 @section Faces | |
1189 @cindex faces | |
1190 | |
1191 These options control the display faces that WoMan uses to format the | |
1192 man page. | |
1193 | |
1194 @vtable @code | |
1195 @item woman-fontify | |
1196 A boolean value. If non-@code{nil} then WoMan assumes that face support is | |
1197 available. It defaults to a non-@code{nil} value if the display supports | |
1198 either colors or different fonts. | |
1199 | |
1200 @item woman-italic-face | |
1201 Face for italic font in man pages. Default: italic, underlined, | |
1202 foreground red. This is overkill! @code{troff} uses just italic; | |
1203 @code{nroff} uses just underline. You should probably select either | |
1204 italic or underline as you prefer, but not both, although italic and | |
1205 underline work together perfectly well! | |
1206 | |
1207 @item woman-bold-face | |
1208 Face for bold font in man pages. Default: bold, foreground blue. | |
1209 | |
1210 @item woman-unknown-face | |
1211 Face for all unknown fonts in man pages. Default: foreground brown. | |
1212 Brown is a good compromise: it is distinguishable from the default but | |
1213 not enough so as to make font errors look terrible. (Files that use | |
1214 non-standard fonts seem to do so badly or in idiosyncratic ways!) | |
1215 | |
1216 @item woman-addition-face | |
1217 Face for all additions made by WoMan to man pages. | |
1218 Default: foreground orange. | |
1219 @end vtable | |
1220 | |
1221 | |
1222 @node Special symbols, , Faces, Customization | |
1223 @comment node-name, next, previous, up | |
1224 @section Special symbols | |
1225 @cindex special symbols | |
1226 | |
1227 This section currently applies @emph{only} to Microsoft Windows. | |
1228 | |
1229 WoMan provides partial experimental support for special symbols, | |
1230 initially only for MS-Windows and only for MS-Windows fonts. This | |
1231 includes both non-@acronym{ASCII} characters from the main text font and use | |
1232 of a separate symbol font. Later, support will be added for other font | |
1233 types (e.g.@: @code{bdf} fonts) and for the X Window System. In Emacs | |
1234 20.7, the current support works partially under Windows 9x but may not | |
1235 work on any other platform. | |
1236 | |
1237 @vtable @code | |
1238 @item woman-use-extended-font | |
1239 A boolean value. If non-@code{nil} then WoMan may use non-@acronym{ASCII} characters | |
1240 from the default font. Default is @code{t}. | |
1241 | |
1242 @item woman-use-symbol-font | |
1243 A boolean value. If non-@code{nil} then WoMan may use the symbol font. | |
1244 Default is @code{nil}, mainly because it may change the line spacing (at | |
1245 least in NTEmacs 20). | |
1246 | |
1247 @item woman-symbol-font | |
1248 A string describing the symbol font to use for special characters. | |
1249 It should be compatible with, and the same size as, the default text font. | |
1250 Under MS-Windows, the default is | |
1251 | |
1252 @lisp | |
1253 "-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol" | |
1254 @end lisp | |
1255 @end vtable | |
1256 | |
1257 | |
1258 @c =================================================================== | |
1259 | |
1260 @node Log, Technical, Customization, Top | |
1261 @comment node-name, next, previous, up | |
1262 @chapter The *WoMan-Log* Buffer | |
1263 @cindex log buffer | |
1264 @cindex buffer, log | |
1265 | |
1266 This is modeled on the Emacs byte-compiler. It logs all files | |
1267 formatted by WoMan and the time taken. If WoMan finds anything that it | |
1268 cannot handle then it writes a warning to this buffer. If the variable | |
1269 @code{woman-show-log} is non-@code{nil} (by default it is @code{nil}) then | |
1270 WoMan automatically displays this buffer. @xref{Interface Options, , | |
1271 Interface Options}. Many WoMan warnings can be completely ignored, | |
1272 because they are reporting the fact that WoMan has ignored requests that | |
1273 it is correct for WoMan to ignore. In some future version this level of | |
1274 paranoia may be reduced, but not until WoMan is deemed more reliable. | |
1275 At present, all warnings should be treated with some suspicion. | |
1276 Uninterpreted escape sequences are also logged (in some cases). | |
1277 | |
1278 By resetting the variable @code{woman-ignore} to @code{nil} (by default | |
1279 it is @code{t}), uninterpreted @code{roff} requests can optionally be | |
1280 left in the formatted buffer to indicate precisely where they occurred. | |
1281 @xref{Interface Options, , Interface Options}. | |
1282 | |
1283 @c =================================================================== | |
1284 | |
1285 @node Technical, Bugs, Log, Top | |
1286 @comment node-name, next, previous, up | |
1287 @chapter Technical Details | |
1288 @cindex technical details | |
1289 @cindex horizontal spacing | |
1290 @cindex spacing, horizontal and vertical | |
1291 @cindex vertical spacing | |
1292 @cindex resolution | |
1293 | |
1294 @heading Horizontal and vertical spacing and resolution | |
1295 | |
1296 WoMan currently assumes 10 characters per inch horizontally, hence a | |
1297 horizontal resolution of 24 basic units, and 5 lines per inch | |
1298 vertically, hence a vertical resolution of 48 basic units. | |
1299 (@code{nroff} uses 240 per inch.) | |
1300 | |
1301 @heading Vertical spacing and blank lines | |
1302 | |
1303 The number of consecutive blank lines in the formatted buffer should be | |
1304 either 0 or 1. A blank line should leave a space like .sp 1. | |
1305 Current policy is to output vertical space only immediately before text | |
1306 is output. | |
1307 | |
1308 @c =================================================================== | |
1309 | |
1310 @node Bugs, Acknowledgements, Technical, Top | |
1311 @comment node-name, next, previous, up | |
1312 @chapter Reporting Bugs | |
1313 @cindex reporting bugs | |
1314 @cindex bugs, reporting | |
1315 | |
1316 If WoMan fails completely, or formats a file incorrectly (i.e.@: | |
1317 obviously wrongly or significantly differently from @code{man}) or | |
1318 inelegantly, then please | |
1319 | |
1320 @enumerate | |
1321 @item | |
106881
f450b77810be
(Bugs): Make "Emacs repository" less specific, and the URL for same
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
1322 try the latest version of @file{woman.el} from the Emacs repository |
f450b77810be
(Bugs): Make "Emacs repository" less specific, and the URL for same
Glenn Morris <rgm@gnu.org>
parents:
106815
diff
changeset
|
1323 on @uref{http://savannah.gnu.org/projects/emacs/}. If it still fails, please |
84325 | 1324 |
1325 @item | |
1326 send a bug report to @email{bug-gnu-emacs@@gnu.org} and to | |
1327 @email{F.J.Wright@@qmw.ac.uk}. Please include the entry from the | |
1328 @code{*WoMan-Log*} buffer relating to the problem file, together with | |
1329 a brief description of the problem. Please indicate where you got the | |
1330 man source file from, but do not send it unless asked to send it. | |
1331 @end enumerate | |
1332 | |
1333 @c =================================================================== | |
1334 | |
1335 @node Acknowledgements, GNU Free Documentation License, Bugs, Top | |
1336 @comment node-name, next, previous, up | |
1337 @chapter Acknowledgements | |
1338 @cindex acknowledgements | |
1339 | |
1340 For Heather, Kathryn and Madelyn, the women in my life (although they | |
1341 will probably never use it)! | |
1342 | |
1343 I also thank the following for helpful suggestions, bug reports, code | |
1344 fragments, general interest, etc.: | |
1345 | |
1346 @quotation | |
1347 Jari Aalto, @email{jari.aalto@@cs.tpu.fi}@* | |
1348 Dean Andrews, @email{dean@@dra.com}@* | |
1349 Juanma Barranquero, @email{barranquero@@laley-actualidad.es}@* | |
1350 Karl Berry, @email{kb@@cs.umb.edu}@* | |
1351 Jim Chapman, @email{jchapman@@netcomuk.co.uk}@* | |
1352 Frederic Corne, @email{frederic.corne@@erli.fr}@* | |
1353 Peter Craft, @email{craft@@alacritech.com}@* | |
1354 Charles Curley, @email{ccurley@@trib.com}@* | |
1355 Jim Davidson, @email{jdavidso@@teknowledge.com}@* | |
1356 Kevin D'Elia, @email{Kevin.DElia@@mci.com}@* | |
1357 John Fitch, @email{jpff@@maths.bath.ac.uk}@* | |
1358 Hans Frosch, @email{jwfrosch@@rish.b17c.ingr.com}@* | |
1359 Guy Gascoigne-Piggford, @email{ggp@@informix.com}@* | |
1360 Brian Gorka, @email{gorkab@@sanchez.com}@* | |
1361 Nicolai Henriksen, @email{nhe@@lyngso-industri.dk}@* | |
1362 Thomas Herchenroeder, @email{the@@software-ag.de}@* | |
1363 Alexander Hinds, @email{ahinds@@thegrid.net}@* | |
1364 Stefan Hornburg, @email{sth@@hacon.de}@* | |
1365 Theodore Jump, @email{tjump@@cais.com}@* | |
1366 Paul Kinnucan, @email{paulk@@mathworks.com}@* | |
1367 Jonas Linde, @email{jonas@@init.se}@* | |
1368 Andrew McRae, @email{andrewm@@optimation.co.nz}@* | |
1369 Howard Melman, @email{howard@@silverstream.com}@* | |
1370 Dennis Pixton, @email{dennis@@math.binghamton.edu}@* | |
1371 T. V. Raman, @email{raman@@Adobe.com}@* | |
1372 Bruce Ravel, @email{bruce.ravel@@nist.gov}@* | |
1373 Benjamin Riefenstahl, @email{benny@@crocodial.de}@* | |
1374 Kevin Ruland, @email{kruland@@seistl.com}@* | |
1375 Tom Schutter, @email{tom@@platte.com}@* | |
1376 Wei-Xue Shi, @email{wxshi@@ma.neweb.ne.jp}@* | |
1377 Fabio Somenzi, @email{fabio@@joplin.colorado.edu}@* | |
1378 Karel Sprenger, @email{ks@@ic.uva.nl}@* | |
1379 Chris Szurgot, @email{szurgot@@itribe.net}@* | |
1380 Paul A. Thompson, @email{pat@@po.cwru.edu}@* | |
1381 Arrigo Triulzi, @email{arrigo@@maths.qmw.ac.uk}@* | |
1382 Geoff Voelker, @email{voelker@@cs.washington.edu}@* | |
1383 Eli Zaretskii, @email{eliz@@is.elta.co.il} | |
1384 @end quotation | |
1385 | |
1386 @c =================================================================== | |
1387 | |
1388 @comment END OF MANUAL TEXT | |
1389 @page | |
1390 | |
1391 | |
1392 @node GNU Free Documentation License, Command Index, Acknowledgements, Top | |
1393 @appendix GNU Free Documentation License | |
1394 @include doclicense.texi | |
1395 | |
1396 @node Command Index, Variable Index, GNU Free Documentation License, Top | |
1397 @comment node-name, next, previous, up | |
1398 @unnumbered Command Index | |
1399 | |
1400 @printindex fn | |
1401 | |
1402 @node Variable Index, Keystroke Index, Command Index, Top | |
1403 @comment node-name, next, previous, up | |
1404 @unnumbered Variable Index | |
1405 | |
1406 @printindex vr | |
1407 | |
1408 @c Without a page throw here, the page length seems to get reset to the | |
1409 @c depth of the index that fits on the page after the previous index. | |
1410 @c This must be a bug! | |
1411 | |
1412 @page | |
1413 | |
1414 @node Keystroke Index, Concept Index, Variable Index, Top | |
1415 @comment node-name, next, previous, up | |
1416 @unnumbered Keystroke Index | |
1417 | |
1418 @printindex ky | |
1419 | |
1420 @c Without a page throw here, the page length seems to get reset to the | |
1421 @c depth of the index that fits on the page after the previous index. | |
1422 @c This must be a bug! | |
1423 | |
1424 @page | |
1425 | |
1426 @node Concept Index, , Keystroke Index, Top | |
1427 @comment node-name, next, previous, up | |
1428 @unnumbered Concept Index | |
1429 | |
1430 @printindex cp | |
1431 | |
1432 @bye | |
1433 | |
1434 @ignore | |
1435 arch-tag: a1a6b715-396f-4378-9b94-0b2ca0aa5028 | |
1436 @end ignore |