Mercurial > emacs
annotate doc/lispref/help.texi @ 98383:fb8c41cd17c4
*** empty log message ***
author | Martin Rudalics <rudalics@gmx.at> |
---|---|
date | Sun, 28 Sep 2008 08:43:50 +0000 |
parents | 107ccd98fa12 |
children | ffd856998075 |
rev | line source |
---|---|
84073 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, | |
87649 | 4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84073 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84073
diff
changeset
|
6 @setfilename ../../info/help |
84073 | 7 @node Documentation, Files, Modes, Top |
8 @chapter Documentation | |
9 @cindex documentation strings | |
10 | |
11 GNU Emacs Lisp has convenient on-line help facilities, most of which | |
12 derive their information from the documentation strings associated with | |
13 functions and variables. This chapter describes how to write good | |
14 documentation strings for your Lisp programs, as well as how to write | |
15 programs to access documentation. | |
16 | |
17 Note that the documentation strings for Emacs are not the same thing | |
18 as the Emacs manual. Manuals have their own source files, written in | |
19 the Texinfo language; documentation strings are specified in the | |
20 definitions of the functions and variables they apply to. A collection | |
21 of documentation strings is not sufficient as a manual because a good | |
22 manual is not organized in that fashion; it is organized in terms of | |
23 topics of discussion. | |
24 | |
25 For commands to display documentation strings, see @ref{Help, , | |
26 Help, emacs, The GNU Emacs Manual}. For the conventions for writing | |
27 documentation strings, see @ref{Documentation Tips}. | |
28 | |
29 @menu | |
30 * Documentation Basics:: Good style for doc strings. | |
31 Where to put them. How Emacs stores them. | |
32 * Accessing Documentation:: How Lisp programs can access doc strings. | |
33 * Keys in Documentation:: Substituting current key bindings. | |
34 * Describing Characters:: Making printable descriptions of | |
35 non-printing characters and key sequences. | |
36 * Help Functions:: Subroutines used by Emacs help facilities. | |
37 @end menu | |
38 | |
39 @node Documentation Basics | |
40 @comment node-name, next, previous, up | |
41 @section Documentation Basics | |
42 @cindex documentation conventions | |
43 @cindex writing a documentation string | |
44 @cindex string, writing a doc string | |
45 | |
46 A documentation string is written using the Lisp syntax for strings, | |
47 with double-quote characters surrounding the text of the string. This | |
48 is because it really is a Lisp string object. The string serves as | |
49 documentation when it is written in the proper place in the definition | |
50 of a function or variable. In a function definition, the documentation | |
51 string follows the argument list. In a variable definition, the | |
52 documentation string follows the initial value of the variable. | |
53 | |
54 When you write a documentation string, make the first line a | |
55 complete sentence (or two complete sentences) since some commands, | |
56 such as @code{apropos}, show only the first line of a multi-line | |
57 documentation string. Also, you should not indent the second line of | |
58 a documentation string, if it has one, because that looks odd when you | |
59 use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} | |
60 (@code{describe-variable}) to view the documentation string. There | |
61 are many other conventions for doc strings; see @ref{Documentation | |
62 Tips}. | |
63 | |
64 Documentation strings can contain several special substrings, which | |
65 stand for key bindings to be looked up in the current keymaps when the | |
66 documentation is displayed. This allows documentation strings to refer | |
67 to the keys for related commands and be accurate even when a user | |
68 rearranges the key bindings. (@xref{Keys in Documentation}.) | |
69 | |
70 @vindex emacs-lisp-docstring-fill-column | |
71 Emacs Lisp mode fills documentation strings to the width | |
72 specified by @code{emacs-lisp-docstring-fill-column}. | |
73 | |
74 In Emacs Lisp, a documentation string is accessible through the | |
75 function or variable that it describes: | |
76 | |
77 @itemize @bullet | |
78 @item | |
79 @kindex function-documentation | |
80 The documentation for a function is usually stored in the function | |
81 definition itself (@pxref{Lambda Expressions}). The function | |
82 @code{documentation} knows how to extract it. You can also put | |
83 function documentation in the @code{function-documentation} property | |
84 of the function name. That is useful with definitions such as | |
85 keyboard macros that can't hold a documentation string. | |
86 | |
87 @item | |
88 @kindex variable-documentation | |
89 The documentation for a variable is stored in the variable's property | |
90 list under the property name @code{variable-documentation}. The | |
91 function @code{documentation-property} knows how to retrieve it. | |
92 @end itemize | |
93 | |
94 @cindex @file{DOC-@var{version}} (documentation) file | |
95 To save space, the documentation for preloaded functions and variables | |
96 (including primitive functions and autoloaded functions) is stored in | |
97 the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The | |
98 documentation strings for functions and variables loaded during the | |
99 Emacs session from byte-compiled files are stored in those files | |
100 (@pxref{Docs and Compilation}). | |
101 | |
102 The data structure inside Emacs has an integer offset into the file, or | |
103 a list containing a file name and an integer, in place of the | |
104 documentation string. The functions @code{documentation} and | |
105 @code{documentation-property} use that information to fetch the | |
106 documentation string from the appropriate file; this is transparent to | |
107 the user. | |
108 | |
109 @c Wordy to prevent overfull hbox. --rjc 15mar92 | |
110 The @file{emacs/lib-src} directory contains two utilities that you can | |
111 use to print nice-looking hardcopy for the file | |
112 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and | |
113 @file{digest-doc}. | |
114 | |
115 @node Accessing Documentation | |
116 @section Access to Documentation Strings | |
117 | |
118 @defun documentation-property symbol property &optional verbatim | |
119 This function returns the documentation string that is recorded in | |
120 @var{symbol}'s property list under property @var{property}. It | |
121 retrieves the text from a file if the value calls for that. If the | |
122 property value isn't @code{nil}, isn't a string, and doesn't refer to | |
123 text in a file, then it is evaluated to obtain a string. | |
124 | |
125 The last thing this function does is pass the string through | |
126 @code{substitute-command-keys} to substitute actual key bindings, | |
127 unless @var{verbatim} is non-@code{nil}. | |
128 | |
129 @smallexample | |
130 @group | |
131 (documentation-property 'command-line-processed | |
132 'variable-documentation) | |
133 @result{} "Non-nil once command line has been processed" | |
134 @end group | |
135 @group | |
136 (symbol-plist 'command-line-processed) | |
137 @result{} (variable-documentation 188902) | |
138 @end group | |
139 @group | |
140 (documentation-property 'emacs 'group-documentation) | |
141 @result{} "Customization of the One True Editor." | |
142 @end group | |
143 @end smallexample | |
144 @end defun | |
145 | |
146 @defun documentation function &optional verbatim | |
147 This function returns the documentation string of @var{function}. | |
148 @code{documentation} handles macros, named keyboard macros, and | |
149 special forms, as well as ordinary functions. | |
150 | |
151 If @var{function} is a symbol, this function first looks for the | |
152 @code{function-documentation} property of that symbol; if that has a | |
153 non-@code{nil} value, the documentation comes from that value (if the | |
154 value is not a string, it is evaluated). If @var{function} is not a | |
155 symbol, or if it has no @code{function-documentation} property, then | |
156 @code{documentation} extracts the documentation string from the actual | |
157 function definition, reading it from a file if called for. | |
158 | |
159 Finally, unless @var{verbatim} is non-@code{nil}, it calls | |
160 @code{substitute-command-keys} so as to return a value containing the | |
161 actual (current) key bindings. | |
162 | |
163 The function @code{documentation} signals a @code{void-function} error | |
164 if @var{function} has no function definition. However, it is OK if | |
165 the function definition has no documentation string. In that case, | |
166 @code{documentation} returns @code{nil}. | |
167 @end defun | |
168 | |
169 @defun face-documentation face | |
170 This function returns the documentation string of @var{face} as a | |
171 face. | |
172 @end defun | |
173 | |
174 @c Wordy to prevent overfull hboxes. --rjc 15mar92 | |
175 Here is an example of using the two functions, @code{documentation} and | |
176 @code{documentation-property}, to display the documentation strings for | |
177 several symbols in a @samp{*Help*} buffer. | |
178 | |
179 @anchor{describe-symbols example} | |
180 @smallexample | |
181 @group | |
182 (defun describe-symbols (pattern) | |
183 "Describe the Emacs Lisp symbols matching PATTERN. | |
184 All symbols that have PATTERN in their name are described | |
185 in the `*Help*' buffer." | |
186 (interactive "sDescribe symbols matching: ") | |
187 (let ((describe-func | |
188 (function | |
189 (lambda (s) | |
190 @end group | |
191 @group | |
192 ;; @r{Print description of symbol.} | |
193 (if (fboundp s) ; @r{It is a function.} | |
194 (princ | |
195 (format "%s\t%s\n%s\n\n" s | |
196 (if (commandp s) | |
197 (let ((keys (where-is-internal s))) | |
198 (if keys | |
199 (concat | |
200 "Keys: " | |
201 (mapconcat 'key-description | |
202 keys " ")) | |
203 "Keys: none")) | |
204 "Function") | |
205 @end group | |
206 @group | |
207 (or (documentation s) | |
208 "not documented")))) | |
209 | |
210 (if (boundp s) ; @r{It is a variable.} | |
211 @end group | |
212 @group | |
213 (princ | |
214 (format "%s\t%s\n%s\n\n" s | |
215 (if (user-variable-p s) | |
216 "Option " "Variable") | |
217 @end group | |
218 @group | |
219 (or (documentation-property | |
220 s 'variable-documentation) | |
221 "not documented"))))))) | |
222 sym-list) | |
223 @end group | |
224 | |
225 @group | |
226 ;; @r{Build a list of symbols that match pattern.} | |
227 (mapatoms (function | |
228 (lambda (sym) | |
229 (if (string-match pattern (symbol-name sym)) | |
230 (setq sym-list (cons sym sym-list)))))) | |
231 @end group | |
232 | |
233 @group | |
234 ;; @r{Display the data.} | |
235 (with-output-to-temp-buffer "*Help*" | |
236 (mapcar describe-func (sort sym-list 'string<)) | |
237 (print-help-return-message)))) | |
238 @end group | |
239 @end smallexample | |
240 | |
241 The @code{describe-symbols} function works like @code{apropos}, | |
242 but provides more information. | |
243 | |
244 @smallexample | |
245 @group | |
246 (describe-symbols "goal") | |
247 | |
248 ---------- Buffer: *Help* ---------- | |
249 goal-column Option | |
250 *Semipermanent goal column for vertical motion, as set by @dots{} | |
251 @end group | |
252 @c Do not blithely break or fill these lines. | |
253 @c That makes them incorrect. | |
254 | |
255 @group | |
256 set-goal-column Keys: C-x C-n | |
257 Set the current horizontal position as a goal for C-n and C-p. | |
258 @end group | |
259 @c DO NOT put a blank line here! That is factually inaccurate! | |
260 @group | |
261 Those commands will move to this position in the line moved to | |
262 rather than trying to keep the same horizontal position. | |
263 With a non-nil argument, clears out the goal column | |
264 so that C-n and C-p resume vertical motion. | |
265 The goal column is stored in the variable `goal-column'. | |
266 @end group | |
267 | |
268 @group | |
269 temporary-goal-column Variable | |
270 Current goal column for vertical motion. | |
271 It is the column where point was | |
272 at the start of current run of vertical motion commands. | |
273 When the `track-eol' feature is doing its job, the value is 9999. | |
274 ---------- Buffer: *Help* ---------- | |
275 @end group | |
276 @end smallexample | |
277 | |
278 The asterisk @samp{*} as the first character of a variable's doc string, | |
279 as shown above for the @code{goal-column} variable, means that it is a | |
280 user option; see the description of @code{defvar} in @ref{Defining | |
281 Variables}. | |
282 | |
283 @defun Snarf-documentation filename | |
284 @anchor{Definition of Snarf-documentation} | |
285 This function is used only during Emacs initialization, just before | |
286 the runnable Emacs is dumped. It finds the file offsets of the | |
287 documentation strings stored in the file @var{filename}, and records | |
288 them in the in-core function definitions and variable property lists in | |
289 place of the actual strings. @xref{Building Emacs}. | |
290 | |
291 Emacs reads the file @var{filename} from the @file{emacs/etc} directory. | |
292 When the dumped Emacs is later executed, the same file will be looked | |
293 for in the directory @code{doc-directory}. Usually @var{filename} is | |
294 @code{"DOC-@var{version}"}. | |
295 @end defun | |
296 | |
297 @c Emacs 19 feature | |
298 @defvar doc-directory | |
299 This variable holds the name of the directory which should contain the | |
300 file @code{"DOC-@var{version}"} that contains documentation strings for | |
301 built-in and preloaded functions and variables. | |
302 | |
303 In most cases, this is the same as @code{data-directory}. They may be | |
304 different when you run Emacs from the directory where you built it, | |
305 without actually installing it. @xref{Definition of data-directory}. | |
306 | |
307 In older Emacs versions, @code{exec-directory} was used for this. | |
308 @end defvar | |
309 | |
310 @node Keys in Documentation | |
311 @section Substituting Key Bindings in Documentation | |
312 @cindex documentation, keys in | |
313 @cindex keys in documentation strings | |
314 @cindex substituting keys in documentation | |
315 | |
316 When documentation strings refer to key sequences, they should use the | |
317 current, actual key bindings. They can do so using certain special text | |
318 sequences described below. Accessing documentation strings in the usual | |
319 way substitutes current key binding information for these special | |
320 sequences. This works by calling @code{substitute-command-keys}. You | |
321 can also call that function yourself. | |
322 | |
323 Here is a list of the special sequences and what they mean: | |
324 | |
325 @table @code | |
326 @item \[@var{command}] | |
327 stands for a key sequence that will invoke @var{command}, or @samp{M-x | |
328 @var{command}} if @var{command} has no key bindings. | |
329 | |
330 @item \@{@var{mapvar}@} | |
331 stands for a summary of the keymap which is the value of the variable | |
332 @var{mapvar}. The summary is made using @code{describe-bindings}. | |
333 | |
334 @item \<@var{mapvar}> | |
335 stands for no text itself. It is used only for a side effect: it | |
336 specifies @var{mapvar}'s value as the keymap for any following | |
337 @samp{\[@var{command}]} sequences in this documentation string. | |
338 | |
339 @item \= | |
340 quotes the following character and is discarded; thus, @samp{\=\[} puts | |
341 @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the | |
342 output. | |
343 @end table | |
344 | |
345 @strong{Please note:} Each @samp{\} must be doubled when written in a | |
346 string in Emacs Lisp. | |
347 | |
348 @defun substitute-command-keys string | |
349 This function scans @var{string} for the above special sequences and | |
350 replaces them by what they stand for, returning the result as a string. | |
351 This permits display of documentation that refers accurately to the | |
352 user's own customized key bindings. | |
353 @end defun | |
354 | |
355 Here are examples of the special sequences: | |
356 | |
357 @smallexample | |
358 @group | |
359 (substitute-command-keys | |
360 "To abort recursive edit, type: \\[abort-recursive-edit]") | |
361 @result{} "To abort recursive edit, type: C-]" | |
362 @end group | |
363 | |
364 @group | |
365 (substitute-command-keys | |
366 "The keys that are defined for the minibuffer here are: | |
367 \\@{minibuffer-local-must-match-map@}") | |
368 @result{} "The keys that are defined for the minibuffer here are: | |
369 @end group | |
370 | |
371 ? minibuffer-completion-help | |
372 SPC minibuffer-complete-word | |
373 TAB minibuffer-complete | |
374 C-j minibuffer-complete-and-exit | |
375 RET minibuffer-complete-and-exit | |
376 C-g abort-recursive-edit | |
377 " | |
378 | |
379 @group | |
380 (substitute-command-keys | |
381 "To abort a recursive edit from the minibuffer, type\ | |
382 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") | |
383 @result{} "To abort a recursive edit from the minibuffer, type C-g." | |
384 @end group | |
385 @end smallexample | |
386 | |
387 There are other special conventions for the text in documentation | |
388 strings---for instance, you can refer to functions, variables, and | |
389 sections of this manual. @xref{Documentation Tips}, for details. | |
390 | |
391 @node Describing Characters | |
392 @section Describing Characters for Help Messages | |
393 @cindex describe characters and events | |
394 | |
395 These functions convert events, key sequences, or characters to | |
396 textual descriptions. These descriptions are useful for including | |
397 arbitrary text characters or key sequences in messages, because they | |
398 convert non-printing and whitespace characters to sequences of printing | |
399 characters. The description of a non-whitespace printing character is | |
400 the character itself. | |
401 | |
402 @defun key-description sequence &optional prefix | |
403 @cindex Emacs event standard notation | |
404 This function returns a string containing the Emacs standard notation | |
405 for the input events in @var{sequence}. If @var{prefix} is | |
406 non-@code{nil}, it is a sequence of input events leading up to | |
407 @var{sequence} and is included in the return value. Both arguments | |
408 may be strings, vectors or lists. @xref{Input Events}, for more | |
409 information about valid events. | |
410 | |
411 @smallexample | |
412 @group | |
413 (key-description [?\M-3 delete]) | |
414 @result{} "M-3 <delete>" | |
415 @end group | |
416 @group | |
417 (key-description [delete] "\M-3") | |
418 @result{} "M-3 <delete>" | |
419 @end group | |
420 @end smallexample | |
421 | |
422 See also the examples for @code{single-key-description}, below. | |
423 @end defun | |
424 | |
425 @defun single-key-description event &optional no-angles | |
426 @cindex event printing | |
427 @cindex character printing | |
428 @cindex control character printing | |
429 @cindex meta character printing | |
430 This function returns a string describing @var{event} in the standard | |
431 Emacs notation for keyboard input. A normal printing character | |
432 appears as itself, but a control character turns into a string | |
433 starting with @samp{C-}, a meta character turns into a string starting | |
434 with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC}, | |
435 @samp{TAB}, etc. A function key symbol appears inside angle brackets | |
436 @samp{<@dots{}>}. An event that is a list appears as the name of the | |
437 symbol in the @sc{car} of the list, inside angle brackets. | |
438 | |
439 If the optional argument @var{no-angles} is non-@code{nil}, the angle | |
440 brackets around function keys and event symbols are omitted; this is | |
441 for compatibility with old versions of Emacs which didn't use the | |
442 brackets. | |
443 | |
444 @smallexample | |
445 @group | |
446 (single-key-description ?\C-x) | |
447 @result{} "C-x" | |
448 @end group | |
449 @group | |
450 (key-description "\C-x \M-y \n \t \r \f123") | |
451 @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" | |
452 @end group | |
453 @group | |
454 (single-key-description 'delete) | |
455 @result{} "<delete>" | |
456 @end group | |
457 @group | |
458 (single-key-description 'C-mouse-1) | |
459 @result{} "<C-mouse-1>" | |
460 @end group | |
461 @group | |
462 (single-key-description 'C-mouse-1 t) | |
463 @result{} "C-mouse-1" | |
464 @end group | |
465 @end smallexample | |
466 @end defun | |
467 | |
468 @defun text-char-description character | |
469 This function returns a string describing @var{character} in the | |
470 standard Emacs notation for characters that appear in text---like | |
471 @code{single-key-description}, except that control characters are | |
472 represented with a leading caret (which is how control characters in | |
473 Emacs buffers are usually displayed). Another difference is that | |
474 @code{text-char-description} recognizes the 2**7 bit as the Meta | |
475 character, whereas @code{single-key-description} uses the 2**27 bit | |
476 for Meta. | |
477 | |
478 @smallexample | |
479 @group | |
480 (text-char-description ?\C-c) | |
481 @result{} "^C" | |
482 @end group | |
483 @group | |
484 (text-char-description ?\M-m) | |
485 @result{} "\xed" | |
486 @end group | |
487 @group | |
488 (text-char-description ?\C-\M-m) | |
489 @result{} "\x8d" | |
490 @end group | |
491 @group | |
492 (text-char-description (+ 128 ?m)) | |
493 @result{} "M-m" | |
494 @end group | |
495 @group | |
496 (text-char-description (+ 128 ?\C-m)) | |
497 @result{} "M-^M" | |
498 @end group | |
499 @end smallexample | |
500 @end defun | |
501 | |
502 @defun read-kbd-macro string &optional need-vector | |
503 This function is used mainly for operating on keyboard macros, but it | |
504 can also be used as a rough inverse for @code{key-description}. You | |
505 call it with a string containing key descriptions, separated by spaces; | |
506 it returns a string or vector containing the corresponding events. | |
507 (This may or may not be a single valid key sequence, depending on what | |
508 events you use; @pxref{Key Sequences}.) If @var{need-vector} is | |
509 non-@code{nil}, the return value is always a vector. | |
510 @end defun | |
511 | |
512 @node Help Functions | |
513 @section Help Functions | |
514 | |
515 Emacs provides a variety of on-line help functions, all accessible to | |
516 the user as subcommands of the prefix @kbd{C-h}. For more information | |
517 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here | |
518 we describe some program-level interfaces to the same information. | |
519 | |
520 @deffn Command apropos pattern &optional do-all | |
521 This function finds all ``meaningful'' symbols whose names contain a | |
522 match for the apropos pattern @var{pattern}. An apropos pattern is | |
523 either a word to match, a space-separated list of words of which at | |
524 least two must match, or a regular expression (if any special regular | |
525 expression characters occur). A symbol is ``meaningful'' if it has a | |
526 definition as a function, variable, or face, or has properties. | |
527 | |
528 The function returns a list of elements that look like this: | |
529 | |
530 @example | |
531 (@var{symbol} @var{score} @var{fn-doc} @var{var-doc} | |
532 @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) | |
533 @end example | |
534 | |
535 Here, @var{score} is an integer measure of how important the symbol | |
536 seems to be as a match, and the remaining elements are documentation | |
537 strings for @var{symbol}'s various roles (or @code{nil}). | |
538 | |
539 It also displays the symbols in a buffer named @samp{*Apropos*}, each | |
540 with a one-line description taken from the beginning of its | |
541 documentation string. | |
542 | |
543 @c Emacs 19 feature | |
544 If @var{do-all} is non-@code{nil}, or if the user option | |
545 @code{apropos-do-all} is non-@code{nil}, then @code{apropos} also | |
546 shows key bindings for the functions that are found; it also shows | |
547 @emph{all} interned symbols, not just meaningful ones (and it lists | |
548 them in the return value as well). | |
549 @end deffn | |
550 | |
551 @defvar help-map | |
552 The value of this variable is a local keymap for characters following the | |
553 Help key, @kbd{C-h}. | |
554 @end defvar | |
555 | |
556 @deffn {Prefix Command} help-command | |
557 This symbol is not a function; its function definition cell holds the | |
558 keymap known as @code{help-map}. It is defined in @file{help.el} as | |
559 follows: | |
560 | |
561 @smallexample | |
562 @group | |
563 (define-key global-map (char-to-string help-char) 'help-command) | |
564 (fset 'help-command help-map) | |
565 @end group | |
566 @end smallexample | |
567 @end deffn | |
568 | |
569 @defun print-help-return-message &optional function | |
570 This function builds a string that explains how to restore the previous | |
571 state of the windows after a help command. After building the message, | |
572 it applies @var{function} to it if @var{function} is non-@code{nil}. | |
573 Otherwise it calls @code{message} to display it in the echo area. | |
574 | |
575 This function expects to be called inside a | |
576 @code{with-output-to-temp-buffer} special form, and expects | |
577 @code{standard-output} to have the value bound by that special form. | |
578 For an example of its use, see the long example in @ref{Accessing | |
579 Documentation}. | |
580 @end defun | |
581 | |
582 @defvar help-char | |
583 The value of this variable is the help character---the character that | |
584 Emacs recognizes as meaning Help. By default, its value is 8, which | |
585 stands for @kbd{C-h}. When Emacs reads this character, if | |
586 @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that | |
587 expression, and displays the result in a window if it is a string. | |
588 | |
589 Usually the value of @code{help-form} is @code{nil}. Then the | |
590 help character has no special meaning at the level of command input, and | |
591 it becomes part of a key sequence in the normal way. The standard key | |
592 binding of @kbd{C-h} is a prefix key for several general-purpose help | |
593 features. | |
594 | |
595 The help character is special after prefix keys, too. If it has no | |
596 binding as a subcommand of the prefix key, it runs | |
597 @code{describe-prefix-bindings}, which displays a list of all the | |
598 subcommands of the prefix key. | |
599 @end defvar | |
600 | |
601 @defvar help-event-list | |
602 The value of this variable is a list of event types that serve as | |
603 alternative ``help characters.'' These events are handled just like the | |
604 event specified by @code{help-char}. | |
605 @end defvar | |
606 | |
607 @defvar help-form | |
608 If this variable is non-@code{nil}, its value is a form to evaluate | |
609 whenever the character @code{help-char} is read. If evaluating the form | |
610 produces a string, that string is displayed. | |
611 | |
612 A command that calls @code{read-event} or @code{read-char} probably | |
613 should bind @code{help-form} to a non-@code{nil} expression while it | |
614 does input. (The time when you should not do this is when @kbd{C-h} has | |
615 some other meaning.) Evaluating this expression should result in a | |
616 string that explains what the input is for and how to enter it properly. | |
617 | |
618 Entry to the minibuffer binds this variable to the value of | |
619 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). | |
620 @end defvar | |
621 | |
622 @defvar prefix-help-command | |
623 This variable holds a function to print help for a prefix key. The | |
624 function is called when the user types a prefix key followed by the help | |
625 character, and the help character has no binding after that prefix. The | |
626 variable's default value is @code{describe-prefix-bindings}. | |
627 @end defvar | |
628 | |
629 @defun describe-prefix-bindings | |
630 This function calls @code{describe-bindings} to display a list of all | |
631 the subcommands of the prefix key of the most recent key sequence. The | |
632 prefix described consists of all but the last event of that key | |
633 sequence. (The last event is, presumably, the help character.) | |
634 @end defun | |
635 | |
636 The following two functions are meant for modes that want to provide | |
637 help without relinquishing control, such as the ``electric'' modes. | |
638 Their names begin with @samp{Helper} to distinguish them from the | |
639 ordinary help functions. | |
640 | |
641 @deffn Command Helper-describe-bindings | |
642 This command pops up a window displaying a help buffer containing a | |
643 listing of all of the key bindings from both the local and global keymaps. | |
644 It works by calling @code{describe-bindings}. | |
645 @end deffn | |
646 | |
647 @deffn Command Helper-help | |
648 This command provides help for the current mode. It prompts the user | |
649 in the minibuffer with the message @samp{Help (Type ? for further | |
650 options)}, and then provides assistance in finding out what the key | |
651 bindings are, and what the mode is intended for. It returns @code{nil}. | |
652 | |
653 This can be customized by changing the map @code{Helper-help-map}. | |
654 @end deffn | |
655 | |
656 @c Emacs 19 feature | |
657 @defvar data-directory | |
658 @anchor{Definition of data-directory} | |
659 This variable holds the name of the directory in which Emacs finds | |
660 certain documentation and text files that come with Emacs. In older | |
661 Emacs versions, @code{exec-directory} was used for this. | |
662 @end defvar | |
663 | |
664 @c Emacs 19 feature | |
665 @defmac make-help-screen fname help-line help-text help-map | |
666 This macro defines a help command named @var{fname} that acts like a | |
667 prefix key that shows a list of the subcommands it offers. | |
668 | |
669 When invoked, @var{fname} displays @var{help-text} in a window, then | |
670 reads and executes a key sequence according to @var{help-map}. The | |
671 string @var{help-text} should describe the bindings available in | |
672 @var{help-map}. | |
673 | |
674 The command @var{fname} is defined to handle a few events itself, by | |
675 scrolling the display of @var{help-text}. When @var{fname} reads one of | |
676 those special events, it does the scrolling and then reads another | |
677 event. When it reads an event that is not one of those few, and which | |
678 has a binding in @var{help-map}, it executes that key's binding and | |
679 then returns. | |
680 | |
681 The argument @var{help-line} should be a single-line summary of the | |
682 alternatives in @var{help-map}. In the current version of Emacs, this | |
683 argument is used only if you set the option @code{three-step-help} to | |
684 @code{t}. | |
685 | |
686 This macro is used in the command @code{help-for-help} which is the | |
687 binding of @kbd{C-h C-h}. | |
688 @end defmac | |
689 | |
86051
8872c78278fa
(Help Functions): Document new macro `with-help-window'.
Martin Rudalics <rudalics@gmx.at>
parents:
84116
diff
changeset
|
690 @defmac with-help-window buffer-name body@dots{} |
86438
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
691 This macro evaluates the @var{body} forms, inserting any output they |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
692 produce into a buffer named @var{buffer-name} like |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
693 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). It |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
694 also puts that buffer in Help mode, displays a message telling the |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
695 user how to quit and scroll the help window, and does various other |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
696 things that make a help window work better. |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
697 |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
698 Don't use @code{print-help-return-message} in the body of this macro; |
194e0eca9ec2
(Help Functions): Clean up last change.
Richard M. Stallman <rms@gnu.org>
parents:
86051
diff
changeset
|
699 it would cause bad results. |
86051
8872c78278fa
(Help Functions): Document new macro `with-help-window'.
Martin Rudalics <rudalics@gmx.at>
parents:
84116
diff
changeset
|
700 @end defmac |
8872c78278fa
(Help Functions): Document new macro `with-help-window'.
Martin Rudalics <rudalics@gmx.at>
parents:
84116
diff
changeset
|
701 |
84073 | 702 @defopt three-step-help |
703 If this variable is non-@code{nil}, commands defined with | |
704 @code{make-help-screen} display their @var{help-line} strings in the | |
705 echo area at first, and display the longer @var{help-text} strings only | |
706 if the user types the help character again. | |
707 @end defopt | |
708 | |
709 @ignore | |
710 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815 | |
711 @end ignore |