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