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