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