Commit | Line | Data |
---|---|---|
5e8db0c6 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 | @c See the file elisp.texi for copying conditions. | |
5 | @setfilename ../info/help | |
6 | @node Documentation, Files, Modes, Top | |
7 | @chapter Documentation | |
8 | @cindex documentation strings | |
9 | ||
10 | GNU Emacs Lisp has convenient on-line help facilities, most of which | |
11 | derive their information from the documentation strings associated with | |
12 | functions and variables. This chapter describes how to write good | |
13 | documentation strings for your Lisp programs, as well as how to write | |
14 | programs to access documentation. | |
15 | ||
16 | Note that the documentation strings for Emacs are not the same thing | |
17 | as the Emacs manual. Manuals have their own source files, written in | |
18 | the Texinfo language; documentation strings are specified in the | |
19 | definitions of the functions and variables they apply to. A collection | |
20 | of documentation strings is not sufficient as a manual because a good | |
21 | manual is not organized in that fashion; it is organized in terms of | |
22 | topics of discussion. | |
23 | ||
24 | @menu | |
25 | * Documentation Basics:: Good style for doc strings. | |
26 | Where to put them. How Emacs stores them. | |
27 | * Accessing Documentation:: How Lisp programs can access doc strings. | |
28 | * Keys in Documentation:: Substituting current key bindings. | |
29 | * Describing Characters:: Making printable descriptions of | |
30 | non-printing characters and key sequences. | |
31 | * Help Functions:: Subroutines used by Emacs help facilities. | |
32 | @end menu | |
33 | ||
34 | @node Documentation Basics | |
35 | @comment node-name, next, previous, up | |
36 | @section Documentation Basics | |
37 | @cindex documentation conventions | |
38 | @cindex writing a documentation string | |
39 | @cindex string, writing a doc string | |
40 | ||
41 | A documentation string is written using the Lisp syntax for strings, | |
42 | with double-quote characters surrounding the text of the string. This | |
43 | is because it really is a Lisp string object. The string serves as | |
44 | documentation when it is written in the proper place in the definition | |
45 | of a function or variable. In a function definition, the documentation | |
46 | string follows the argument list. In a variable definition, the | |
47 | documentation string follows the initial value of the variable. | |
48 | ||
49 | When you write a documentation string, make the first line a complete | |
50 | sentence (or two complete sentences) since some commands, such as | |
51 | @code{apropos}, show only the first line of a multi-line documentation | |
52 | string. Also, you should not indent the second line of a documentation | |
53 | string, if you have one, because that looks odd when you use @kbd{C-h f} | |
54 | (@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}). | |
55 | @xref{Documentation Tips}. | |
56 | ||
57 | Documentation strings may contain several special substrings, which | |
58 | stand for key bindings to be looked up in the current keymaps when the | |
59 | documentation is displayed. This allows documentation strings to refer | |
60 | to the keys for related commands and be accurate even when a user | |
61 | rearranges the key bindings. (@xref{Accessing Documentation}.) | |
62 | ||
63 | Within the Lisp world, a documentation string is kept with the | |
64 | function or variable that it describes: | |
65 | ||
66 | @itemize @bullet | |
67 | @item | |
68 | The documentation for a function is stored in the function definition | |
69 | itself (@pxref{Lambda Expressions}). The function | |
70 | @code{documentation} knows how to extract it. | |
71 | ||
72 | @item | |
73 | @kindex variable-documentation | |
74 | The documentation for a variable is stored in the variable's property | |
75 | list under the property name @code{variable-documentation}. The | |
76 | function @code{documentation-property} knows how to extract it. | |
77 | @end itemize | |
78 | ||
79 | @cindex @file{DOC} (documentation) file | |
80 | @cindex @file{emacs/etc/DOC-@var{version}} | |
81 | @cindex @file{etc/DOC-@var{version}} | |
82 | To save space, the documentation for preloaded functions and variables | |
83 | (including primitive functions and autoloaded functions) are stored in | |
84 | the file @file{emacs/etc/DOC-@var{version}}. The data structure inside | |
85 | Emacs has an integer offset into the file, where the documentation | |
86 | string ought to be. The functions @code{documentation} the | |
87 | @code{documentation-property} read the documentation from the file | |
88 | @file{emacs/etc/DOC-@var{version}} when they notice the integer there; | |
89 | this is transparent to the user. Keeping the documentation strings out | |
90 | of the Emacs core image saves a significant amount of space. | |
91 | @xref{Building Emacs}. | |
92 | ||
93 | For information on the uses of documentation strings, see @ref{Help, , | |
94 | Help, emacs, The GNU Emacs Manual}. | |
95 | ||
96 | @c Wordy to prevent overfull hbox. --rjc 15mar92 | |
97 | The @file{emacs/etc} directory contains two utilities that you can use | |
98 | to print nice-looking hardcopy for the file | |
99 | @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and | |
100 | @file{digest-doc.c}. | |
101 | ||
102 | @node Accessing Documentation | |
103 | @section Access to Documentation Strings | |
104 | ||
105 | @defun documentation-property symbol property &optional verbatim | |
106 | This function returns the documentation string that is recorded | |
107 | @var{symbol}'s property list under property @var{property}. It | |
108 | retrieves the text from the file @file{emacs/etc/DOC-@var{version}} if | |
109 | necessary, and runs @code{substitute-command-keys} to substitute actual | |
110 | key bindings. (This substitution is not done if @var{verbatim} is | |
111 | non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.) | |
112 | ||
113 | @smallexample | |
114 | @group | |
115 | (documentation-property 'command-line-processed | |
116 | 'variable-documentation) | |
117 | @result{} "t once command line has been processed" | |
118 | @end group | |
119 | @group | |
120 | (symbol-plist 'command-line-processed) | |
121 | @result{} (variable-documentation 188902) | |
122 | @end group | |
123 | @end smallexample | |
124 | @end defun | |
125 | ||
126 | @defun documentation function &optional verbatim | |
127 | This function returns the documentation string of @var{function}. | |
128 | This function will access the documentation string if it is stored in | |
129 | the @file{emacs/etc/DOC-@var{version}} file. | |
130 | ||
131 | In addition, @code{documentation} runs @code{substitute-command-keys} | |
132 | on the resulting string, so the value contains the actual (current) key | |
133 | bindings. (This is not done if @var{verbatim} is non-@code{nil}; the | |
134 | @var{verbatim} argument exists only as of Emacs 19.) | |
135 | ||
136 | The function @code{documentation} signals a @code{void-function} error | |
137 | unless @var{function} has a function definition. However, it is ok if | |
138 | the function definition has no documentation string. In that case, | |
139 | @code{documentation} returns @code{nil}. | |
140 | @end defun | |
141 | ||
142 | @c Wordy to prevent overfull hboxes. --rjc 15mar92 | |
143 | Here is an example of using the two functions, @code{documentation} and | |
144 | @code{documentation-property}, to display the documentation strings for | |
145 | several symbols in a @samp{*Help*} buffer. | |
146 | ||
147 | @smallexample | |
148 | @group | |
149 | (defun describe-symbols (pattern) | |
150 | "Describe the Emacs Lisp symbols matching PATTERN. | |
151 | All symbols that have PATTERN in their name are described | |
152 | in the `*Help*' buffer." | |
153 | (interactive "sDescribe symbols matching: ") | |
154 | (let ((describe-func | |
155 | (function | |
156 | (lambda (s) | |
157 | @end group | |
158 | @group | |
159 | ;; @r{Print description of symbol.} | |
160 | (if (fboundp s) ; @r{It is a function.} | |
161 | (princ | |
162 | (format "%s\t%s\n%s\n\n" s | |
163 | (if (commandp s) | |
164 | (let ((keys (where-is-internal s))) | |
165 | (if keys | |
166 | (concat | |
167 | "Keys: " | |
168 | (mapconcat 'key-description | |
169 | keys " ")) | |
170 | "Keys: none")) | |
171 | "Function") | |
172 | @end group | |
173 | @group | |
174 | (or (documentation s) | |
175 | "not documented")))) | |
176 | ||
177 | (if (boundp s) ; @r{It is a variable.} | |
178 | @end group | |
179 | @group | |
180 | (princ | |
181 | (format "%s\t%s\n%s\n\n" s | |
182 | (if (user-variable-p s) | |
183 | "Option " "Variable") | |
184 | @end group | |
185 | @group | |
186 | (or (documentation-property | |
187 | s 'variable-documentation) | |
188 | "not documented"))))))) | |
189 | sym-list) | |
190 | @end group | |
191 | ||
192 | @group | |
193 | ;; @r{Build a list of symbols that match pattern.} | |
194 | (mapatoms (function | |
195 | (lambda (sym) | |
196 | (if (string-match pattern (symbol-name sym)) | |
197 | (setq sym-list (cons sym sym-list)))))) | |
198 | @end group | |
199 | ||
200 | @group | |
201 | ;; @r{Display the data.} | |
202 | (with-output-to-temp-buffer "*Help*" | |
203 | (mapcar describe-func (sort sym-list 'string<)) | |
204 | (print-help-return-message)))) | |
205 | @end group | |
206 | @end smallexample | |
207 | ||
208 | The @code{describe-symbols} function works like @code{apropos}, | |
209 | but provides more information. | |
210 | ||
211 | @smallexample | |
212 | @group | |
213 | (describe-symbols "goal") | |
214 | ||
215 | ---------- Buffer: *Help* ---------- | |
216 | goal-column Option | |
217 | *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil. | |
218 | @end group | |
219 | @c Do not blithely break or fill these lines. | |
220 | @c That makes them incorrect. | |
221 | ||
222 | @group | |
223 | set-goal-column Command: C-x C-n | |
224 | Set the current horizontal position as a goal for C-n and C-p. | |
225 | @end group | |
226 | @c DO NOT put a blank line here! That is factually inaccurate! | |
227 | @group | |
228 | Those commands will move to this position in the line moved to | |
229 | rather than trying to keep the same horizontal position. | |
230 | With a non-nil argument, clears out the goal column | |
231 | so that C-n and C-p resume vertical motion. | |
232 | The goal column is stored in the variable `goal-column'. | |
233 | @end group | |
234 | ||
235 | @group | |
236 | temporary-goal-column Variable | |
237 | Current goal column for vertical motion. | |
238 | It is the column where point was | |
239 | at the start of current run of vertical motion commands. | |
240 | When the `track-eol' feature is doing its job, the value is 9999. | |
241 | ---------- Buffer: *Help* ---------- | |
242 | @end group | |
243 | @end smallexample | |
244 | ||
245 | @defun Snarf-documentation filename | |
246 | This function is used only during Emacs initialization, just before | |
247 | the runnable Emacs is dumped. It finds the file offsets of the | |
248 | documentation strings stored in the file @var{filename}, and records | |
249 | them in the in-core function definitions and variable property lists in | |
250 | place of the actual strings. @xref{Building Emacs}. | |
251 | ||
252 | Emacs finds the file @var{filename} in the @file{emacs/etc} directory. | |
253 | When the dumped Emacs is later executed, the same file is found in the | |
254 | directory @code{doc-directory}. Usually @var{filename} is | |
255 | @code{"DOC-@var{version}"}. | |
256 | @end defun | |
257 | ||
258 | @c Emacs 19 feature | |
259 | @defvar doc-directory | |
260 | This variable holds the name of the directory which should contion the | |
261 | file @code{"DOC-@var{version}"} that contains documentation strings for | |
262 | built-in and preloaded functions and variables. | |
263 | ||
264 | In most cases, this is the same as @code{data-directory}. They may be | |
265 | different when you run Emacs from the directory where you built it, | |
266 | without actually installing it. See @code{data-directory} in @ref{Help | |
267 | Functions}. | |
268 | ||
269 | In older Emacs versions, @code{exec-directory} was used for this. | |
270 | @end defvar | |
271 | ||
272 | @node Keys in Documentation | |
273 | @section Substituting Key Bindings in Documentation | |
274 | @cindex documentation, keys in | |
275 | @cindex keys in documentation strings | |
276 | @cindex substituting keys in documentation | |
277 | ||
278 | When documentation strings refer to key sequences, they should do so | |
279 | based on the current, actual key bindings. They can do so using certain | |
280 | special text sequences described below. Accessing documentation strings | |
281 | in the usual way substitutes current key binding information for these | |
282 | special sequences. This works by calling @code{substitute-command-keys}. | |
283 | You can also call that function yourself. | |
284 | ||
285 | Here is a list of the special sequences and what they mean: | |
286 | ||
287 | @table @code | |
288 | @item \[@var{command}] | |
289 | stands for a key sequence that will invoke @var{command}, or @samp{M-x | |
290 | @var{command}} if @var{command} has no key bindings. | |
291 | ||
292 | @item \@{@var{mapvar}@} | |
293 | stands for a summary of the value of @var{mapvar}, which should be a | |
294 | keymap. The summary is made by @code{describe-bindings}. | |
295 | ||
296 | @item \<@var{mapvar}> | |
297 | stands for no text itself. It is used for a side effect: it specifies | |
298 | @var{mapvar} as the keymap for any following @samp{\[@var{command}]} | |
299 | sequences in this documentation string. | |
300 | @end table | |
301 | ||
302 | @strong{Please note:} each @samp{\} must be doubled when written in a | |
303 | string in Emacs Lisp. | |
304 | ||
305 | @defun substitute-command-keys string | |
306 | This function scans @var{string} for the above special sequences and | |
307 | replaces them by what they stand for, returning the result as a string. | |
308 | This permits display of documentation that refers accurately to the | |
309 | users's own customized key bindings. | |
310 | @end defun | |
311 | ||
312 | Here are examples of the special sequences: | |
313 | ||
314 | @smallexample | |
315 | @group | |
316 | (substitute-command-keys | |
317 | "To abort recursive edit, type: \\[abort-recursive-edit]") | |
318 | @result{} "To abort recursive edit, type: C-]" | |
319 | @end group | |
320 | ||
321 | @group | |
322 | (substitute-command-keys | |
323 | "The keys that are defined for the minibuffer here are: | |
324 | \\@{minibuffer-local-must-match-map@}") | |
325 | @result{} "The keys that are defined for the minibuffer here are: | |
326 | @end group | |
327 | ||
328 | ? minibuffer-completion-help | |
329 | SPC minibuffer-complete-word | |
330 | TAB minibuffer-complete | |
331 | LFD minibuffer-complete-and-exit | |
332 | RET minibuffer-complete-and-exit | |
333 | C-g abort-recursive-edit | |
334 | " | |
335 | ||
336 | @group | |
337 | (substitute-command-keys | |
338 | "To abort a recursive edit from the minibuffer, type\ | |
339 | \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") | |
340 | @result{} "To abort a recursive edit from the minibuffer, type C-g." | |
341 | @end group | |
342 | @end smallexample | |
343 | ||
344 | @node Describing Characters | |
345 | @section Describing Characters for Help Messages | |
346 | ||
347 | These functions convert events, key sequences or characters to textual | |
348 | descriptions. These descriptions are useful for including arbitrary | |
349 | text characters or key sequences in messages, because they convert | |
350 | non-printing and whitespace characters to sequences of printing | |
351 | characters. The description of a non-whitespace printing character is | |
352 | the character itself. | |
353 | ||
354 | @defun key-description sequence | |
355 | @cindex Emacs event standard notation | |
356 | This function returns a string containing the Emacs standard notation | |
357 | for the input events in @var{sequence}. The argument @var{sequence} may | |
358 | be a string, vector or list. @xref{Input Events}, for more information | |
359 | about valid events. See also the examples for | |
360 | @code{single-key-description}, below. | |
361 | @end defun | |
362 | ||
363 | @defun single-key-description event | |
364 | @cindex event printing | |
365 | @cindex character printing | |
366 | @cindex control character printing | |
367 | @cindex meta character printing | |
368 | This function returns a string describing @var{event} in the standard | |
369 | Emacs notation for keyboard input. A normal printing character appears | |
370 | as itself, but a control character turns into a string starting with | |
371 | @samp{C-}, a meta character turns into a string starting with @samp{M-}, | |
372 | and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A | |
373 | function key symbol appears as itself. An event which is a list appears | |
374 | as the name of the symbol in the @sc{car} of the list. | |
375 | ||
376 | @smallexample | |
377 | @group | |
378 | (single-key-description ?\C-x) | |
379 | @result{} "C-x" | |
380 | @end group | |
381 | @group | |
382 | (key-description "\C-x \M-y \n \t \r \f123") | |
383 | @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3" | |
384 | @end group | |
385 | @group | |
386 | (single-key-description 'C-mouse-1) | |
387 | @result{} "C-mouse-1" | |
388 | @end group | |
389 | @end smallexample | |
390 | @end defun | |
391 | ||
392 | @defun text-char-description character | |
393 | This function returns a string describing @var{character} in the | |
394 | standard Emacs notation for characters that appear in text---like | |
395 | @code{single-key-description}, except that control characters are | |
396 | represented with a leading caret (which is how control characters in | |
397 | Emacs buffers are usually displayed). | |
398 | ||
399 | @smallexample | |
400 | @group | |
401 | (text-char-description ?\C-c) | |
402 | @result{} "^C" | |
403 | @end group | |
404 | @group | |
405 | (text-char-description ?\M-m) | |
406 | @result{} "M-m" | |
407 | @end group | |
408 | @group | |
409 | (text-char-description ?\C-\M-m) | |
410 | @result{} "M-^M" | |
411 | @end group | |
412 | @end smallexample | |
413 | @end defun | |
414 | ||
415 | @node Help Functions | |
416 | @section Help Functions | |
417 | ||
418 | Emacs provides a variety of on-line help functions, all accessible to | |
419 | the user as subcommands of the prefix @kbd{C-h}. For more information | |
420 | about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here | |
421 | we describe some program-level interfaces to the same information. | |
422 | ||
423 | @deffn Command apropos regexp &optional do-all predicate | |
424 | This function finds all symbols whose names contain a match for the | |
425 | regular expression @var{regexp}, and returns a list of them. | |
426 | It also displays the symbols in a buffer named @samp{*Help*}, each with a | |
427 | one-line description. | |
428 | ||
429 | @c Emacs 19 feature | |
430 | If @var{do-all} is non-@code{nil}, then @code{apropos} also shows | |
431 | key bindings for the functions that are found. | |
432 | ||
433 | If @var{predicate} is non-@code{nil}, it should be a function to be | |
434 | called on each symbol that has matched @var{regexp}. Only symbols for | |
435 | which @var{predicate} returns a non-@code{nil} value are listed or | |
436 | displayed. | |
437 | ||
438 | In the first of the following examples, @code{apropos} finds all the | |
439 | symbols with names containing @samp{exec}. In the second example, it | |
440 | finds and returns only those symbols that are also commands. | |
441 | (We don't show the output that results in the @samp{*Help*} buffer.) | |
442 | ||
443 | @smallexample | |
444 | @group | |
445 | (apropos "exec") | |
446 | @result{} (Buffer-menu-execute command-execute exec-directory | |
447 | exec-path execute-extended-command execute-kbd-macro | |
448 | executing-kbd-macro executing-macro) | |
449 | @end group | |
450 | ||
451 | @group | |
452 | (apropos "exec" nil 'commandp) | |
453 | @result{} (Buffer-menu-execute execute-extended-command) | |
454 | @end group | |
455 | @ignore | |
456 | @group | |
457 | ---------- Buffer: *Help* ---------- | |
458 | Buffer-menu-execute | |
459 | Function: Save and/or delete buffers marked with | |
460 | M-x Buffer-menu-save or M-x Buffer-menu-delete commands. | |
461 | execute-extended-command ESC x | |
462 | Function: Read function name, then read its | |
463 | arguments and call it. | |
464 | ---------- Buffer: *Help* ---------- | |
465 | @end group | |
466 | @end ignore | |
467 | @end smallexample | |
468 | ||
469 | The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos}, | |
470 | but specifies a @var{predicate} to restrict the output to symbols that | |
471 | are commands. The call to @code{apropos} looks like this: | |
472 | ||
473 | @smallexample | |
474 | (apropos string t 'commandp) | |
475 | @end smallexample | |
476 | @end deffn | |
477 | ||
478 | @c Emacs 19 feature | |
479 | @deffn Command super-apropos regexp &optional do-all | |
480 | This function differs from @code{apropos} in that it searches | |
481 | documentation strings as well as symbol names for matches for | |
482 | @var{regexp}. By default, it searches only the documentation strings, | |
483 | and only those of functions and variables that are included in Emacs | |
484 | when it is dumped. If @var{do-all} is non-@code{nil}, it scans the | |
485 | names and documentation strings of all functions and variables. | |
486 | @end deffn | |
487 | ||
488 | @defvar help-map | |
489 | The value of this variable is a local keymap for characters following the | |
490 | Help key, @kbd{C-h}. | |
491 | @end defvar | |
492 | ||
493 | @deffn {Prefix Command} help-command | |
494 | This symbol is not a function; its function definition is actually the | |
495 | keymap known as @code{help-map}. It is defined in @file{help.el} as | |
496 | follows: | |
497 | ||
498 | @smallexample | |
499 | @group | |
500 | (define-key global-map "\C-h" 'help-command) | |
501 | (fset 'help-command help-map) | |
502 | @end group | |
503 | @end smallexample | |
504 | @end deffn | |
505 | ||
506 | @defun print-help-return-message &optional function | |
507 | This function builds a string which is a message explaining how to | |
508 | restore the previous state of the windows after a help command. After | |
509 | building the message, it applies @var{function} to it if @var{function} | |
510 | is non-@code{nil}. Otherwise it calls @code{message} to display it in | |
511 | the echo area. | |
512 | ||
513 | This function expects to be called inside a | |
514 | @code{with-output-to-temp-buffer} special form, and expects | |
515 | @code{standard-output} to have the value bound by that special form. | |
516 | For an example of its use, see the long example in @ref{Accessing | |
517 | Documentation}. | |
518 | @end defun | |
519 | ||
520 | @defvar help-char | |
521 | The value of this variable is the help character---the character that | |
522 | Emacs recognizes as meaning Help. By default, it is 8, which is | |
523 | @kbd{C-h}. When Emacs reads this character, if @code{help-form} is | |
524 | non-@code{nil} Lisp expression, it evaluates that expression, and | |
525 | displays the result in a window if it is a string. | |
526 | ||
527 | Usually the value of @code{help-form}'s value is @code{nil}. Then the | |
528 | help character has no special meaning at the level of command input, and | |
529 | it becomes part of a key sequence in the normal way. The standard key | |
530 | binding of @kbd{C-h} is a prefix key for several general-purpose help | |
531 | features. | |
532 | ||
533 | The help character is special after prefix keys, too. If it has no | |
534 | binding as a subcommand of the prefix key, it runs | |
535 | @code{describe-prefix-bindings}, which displays a list of all the | |
536 | subcommands of the prefix key. | |
537 | @end defvar | |
538 | ||
539 | @defvar help-form | |
540 | If this variable is non-@code{nil}, its value is a form to evaluate | |
541 | whenever the character @code{help-char} is read. If evaluating the form | |
542 | produces a string, that string is displayed. | |
543 | ||
544 | A command that calls @code{read-event} or @code{read-char} probably | |
545 | should bind @code{help-form} to a non-@code{nil} expression while it | |
546 | does input. (The exception is when @kbd{C-h} is meaningful input.) | |
547 | Evaluating this expression should result in a string that explains what | |
548 | the input is for and how to enter it properly. | |
549 | ||
550 | Entry to the minibuffer binds this variable to the value of | |
551 | @code{minibuffer-help-form} (@pxref{Minibuffer Misc}). | |
552 | @end defvar | |
553 | ||
554 | @defvar prefix-help-command | |
555 | This variable holds a function to print help for a prefix character. | |
556 | The function is called when the user types a prefix key followed by the | |
557 | help character, and the help character has no binding after that prefix. | |
558 | The variable's default value is @code{describe-prefix-bindings}. | |
559 | @end defvar | |
560 | ||
561 | @defun describe-prefix-bindings | |
562 | This function calls @code{describe-bindings} to display a list of all | |
563 | the subcommands of the prefix key of the most recent key sequence. The | |
564 | prefix described consists of all but the last event of that key | |
565 | sequence. | |
566 | @end defun | |
567 | ||
568 | The following two functions are found in the library @file{helper}. | |
569 | They are for modes that want to provide help without relinquishing | |
570 | control, such as the ``electric'' modes. You must load that library | |
571 | with @code{(require 'helper)} in order to use them. Their names begin | |
572 | with @samp{Helper} to distinguish them from the ordinary help functions. | |
573 | ||
574 | @deffn Command Helper-describe-bindings | |
575 | This command pops up a window displaying a help buffer containing a | |
576 | listing of all of the key bindings from both the local and global keymaps. | |
577 | It works by calling @code{describe-bindings}. | |
578 | @end deffn | |
579 | ||
580 | @deffn Command Helper-help | |
581 | This command provides help for the current mode. It prompts the user | |
582 | in the minibuffer with the message @samp{Help (Type ? for further | |
583 | options)}, and then provides assistance in finding out what the key | |
584 | bindings are, and what the mode is intended for. It returns @code{nil}. | |
585 | ||
586 | This can be customized by changing the map @code{Helper-help-map}. | |
587 | @end deffn | |
588 | ||
589 | @c Emacs 19 feature | |
590 | @defvar data-directory | |
591 | This variable holds the name of the directory in which Emacs finds | |
592 | certain documentation and text files that come with Emacs. In older | |
593 | Emacs versions, @code{exec-directory} was used for this. | |
594 | @end defvar | |
595 | ||
596 | @c Emacs 19 feature | |
597 | @defmac make-help-screen fname help-line help-text help-map | |
598 | This macro defines a help command named @var{fname} which acts like a | |
599 | prefix key which shows a list of the subcommands it offers. | |
600 | ||
601 | When invoked, @var{fname} displays @var{help-text} in a window, then | |
602 | reads and executes a key sequence according to @var{help-map}. The | |
603 | string @var{help-text} should describe of the bindings available in | |
604 | @var{help-map}. | |
605 | ||
606 | The command @var{fname} is defined to handle a few events itself, by | |
607 | scrolling the display of @var{help-text}. When @var{fname} reads one of | |
608 | those special events, it does the scrolling and then reads another | |
609 | event. When it reads an event which is not one of those few, and which | |
610 | has a binding in @var{help-map}, it executes that key's binding and | |
611 | then returns. | |
612 | ||
613 | The argument @var{help-line} should be a single-line summary of the | |
614 | alternatives in @var{help-map}. In the current version of Emacs, this | |
615 | argument is used only if you set the option @code{three-step-help} to | |
616 | @code{t}. | |
617 | @end defmac | |
618 | ||
619 | @defopt three-step-help | |
620 | If this variable is non-@code{nil}, commands defined with | |
621 | @code{make-help-screen} display their @var{help-line} strings in the | |
622 | echo area at first, and display the longer @var{help-text} strings only | |
623 | if the user types the help character again. | |
624 | @end defopt |