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