6381
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
64889
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
|
|
4 @c 2004, 2005 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
|
63540
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
50 When you write a documentation string, make the first line a
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
51 complete sentence (or two complete sentences) since some commands,
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
52 such as @code{apropos}, show only the first line of a multi-line
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
53 documentation string. Also, you should not indent the second line of
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
54 a documentation string, if it has one, because that looks odd when you
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
55 use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
56 (@code{describe-variable}) to view the documentation string. There
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
57 are many other conventions for doc strings; see @ref{Documentation
|
f69f062368dd
(Documentation Basics): Explain the xref to Documentation Tips.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
58 Tips}.
|
6381
|
59
|
21682
|
60 Documentation strings can contain several special substrings, which
|
6381
|
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
|
56213
|
64 rearranges the key bindings. (@xref{Keys in Documentation}.)
|
6381
|
65
|
21007
|
66 In Emacs Lisp, a documentation string is accessible through the
|
6381
|
67 function or variable that it describes:
|
|
68
|
|
69 @itemize @bullet
|
|
70 @item
|
60265
|
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.
|
6381
|
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
|
21007
|
83 function @code{documentation-property} knows how to retrieve it.
|
6381
|
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
|
7254
|
90 (including primitive functions and autoloaded functions) is stored in
|
21007
|
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}).
|
12098
|
95
|
|
96 The data structure inside Emacs has an integer offset into the file, or
|
21007
|
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.
|
6381
|
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
|
6708
|
107 The @file{emacs/lib-src} directory contains two utilities that you can
|
|
108 use to print nice-looking hardcopy for the file
|
22252
|
109 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
|
|
110 @file{digest-doc}.
|
6381
|
111
|
|
112 @node Accessing Documentation
|
|
113 @section Access to Documentation Strings
|
|
114
|
|
115 @defun documentation-property symbol property &optional verbatim
|
39221
|
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
|
63583
|
122 The last thing this function does is pass the string through
|
39221
|
123 @code{substitute-command-keys} to substitute actual key bindings,
|
|
124 unless @var{verbatim} is non-@code{nil}.
|
6381
|
125
|
|
126 @smallexample
|
|
127 @group
|
|
128 (documentation-property 'command-line-processed
|
|
129 'variable-documentation)
|
22252
|
130 @result{} "Non-nil once command line has been processed"
|
6381
|
131 @end group
|
|
132 @group
|
|
133 (symbol-plist 'command-line-processed)
|
|
134 @result{} (variable-documentation 188902)
|
|
135 @end group
|
67700
|
136 @group
|
|
137 (documentation-property 'emacs 'group-documentation)
|
|
138 @result{} "Customization of the One True Editor."
|
|
139 @end group
|
6381
|
140 @end smallexample
|
|
141 @end defun
|
|
142
|
|
143 @defun documentation function &optional verbatim
|
39221
|
144 This function returns the documentation string of @var{function}.
|
67700
|
145 @code{documentation} handles macros, named keyboard macros, and
|
|
146 special forms, as well as ordinary functions.
|
39221
|
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
|
39206
|
158 actual (current) key bindings.
|
6381
|
159
|
|
160 The function @code{documentation} signals a @code{void-function} error
|
21682
|
161 if @var{function} has no function definition. However, it is OK if
|
6381
|
162 the function definition has no documentation string. In that case,
|
|
163 @code{documentation} returns @code{nil}.
|
|
164 @end defun
|
|
165
|
67700
|
166 @defun face-documentation face
|
|
167 This function returns the documentation string of @var{face} as a
|
|
168 face.
|
|
169 @end defun
|
|
170
|
6381
|
171 @c Wordy to prevent overfull hboxes. --rjc 15mar92
|
7254
|
172 Here is an example of using the two functions, @code{documentation} and
|
6381
|
173 @code{documentation-property}, to display the documentation strings for
|
|
174 several symbols in a @samp{*Help*} buffer.
|
|
175
|
53481
|
176 @anchor{describe-symbols example}
|
6381
|
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
|
49600
|
185 (function
|
6381
|
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
|
49600
|
193 (if (commandp s)
|
6381
|
194 (let ((keys (where-is-internal s)))
|
|
195 (if keys
|
|
196 (concat
|
|
197 "Keys: "
|
49600
|
198 (mapconcat 'key-description
|
6381
|
199 keys " "))
|
|
200 "Keys: none"))
|
|
201 "Function")
|
|
202 @end group
|
|
203 @group
|
49600
|
204 (or (documentation s)
|
6381
|
205 "not documented"))))
|
49600
|
206
|
6381
|
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
|
49600
|
212 (if (user-variable-p s)
|
6381
|
213 "Option " "Variable")
|
|
214 @end group
|
|
215 @group
|
49600
|
216 (or (documentation-property
|
6381
|
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.}
|
49600
|
224 (mapatoms (function
|
6381
|
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* ----------
|
49600
|
246 goal-column Option
|
16736
|
247 *Semipermanent goal column for vertical motion, as set by @dots{}
|
6381
|
248 @end group
|
|
249 @c Do not blithely break or fill these lines.
|
|
250 @c That makes them incorrect.
|
|
251
|
|
252 @group
|
22252
|
253 set-goal-column Keys: C-x C-n
|
6381
|
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
|
31130
|
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
|
56213
|
280 @defun Snarf-documentation filename
|
53298
|
281 @anchor{Definition of Snarf-documentation}
|
21007
|
282 This function is used only during Emacs initialization, just before
|
6381
|
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
|
21007
|
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
|
6381
|
291 @code{"DOC-@var{version}"}.
|
|
292 @end defun
|
|
293
|
|
294 @c Emacs 19 feature
|
|
295 @defvar doc-directory
|
21682
|
296 This variable holds the name of the directory which should contain the
|
6381
|
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,
|
56213
|
302 without actually installing it. @xref{Definition of data-directory}.
|
6381
|
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
|
7254
|
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.
|
6381
|
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
|
49600
|
327 @item \@{@var{mapvar}@}
|
21682
|
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}.
|
6381
|
330
|
49600
|
331 @item \<@var{mapvar}>
|
21007
|
332 stands for no text itself. It is used only for a side effect: it
|
21682
|
333 specifies @var{mapvar}'s value as the keymap for any following
|
21007
|
334 @samp{\[@var{command}]} sequences in this documentation string.
|
13349
|
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.
|
6381
|
340 @end table
|
|
341
|
7254
|
342 @strong{Please note:} Each @samp{\} must be doubled when written in a
|
6381
|
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
|
7254
|
349 user's own customized key bindings.
|
6381
|
350 @end defun
|
|
351
|
|
352 Here are examples of the special sequences:
|
|
353
|
|
354 @smallexample
|
|
355 @group
|
49600
|
356 (substitute-command-keys
|
6381
|
357 "To abort recursive edit, type: \\[abort-recursive-edit]")
|
|
358 @result{} "To abort recursive edit, type: C-]"
|
|
359 @end group
|
|
360
|
|
361 @group
|
49600
|
362 (substitute-command-keys
|
6381
|
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
|
21682
|
371 C-j minibuffer-complete-and-exit
|
6381
|
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
|
21007
|
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
|
6381
|
391 characters. The description of a non-whitespace printing character is
|
|
392 the character itself.
|
|
393
|
56213
|
394 @defun key-description sequence &optional prefix
|
6381
|
395 @cindex Emacs event standard notation
|
|
396 This function returns a string containing the Emacs standard notation
|
56213
|
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.
|
6381
|
415 @end defun
|
|
416
|
39206
|
417 @defun single-key-description event &optional no-angles
|
6381
|
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
|
39221
|
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.
|
39206
|
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
|
39221
|
433 for compatibility with old versions of Emacs which didn't use the
|
39206
|
434 brackets.
|
6381
|
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")
|
21682
|
443 @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
|
6381
|
444 @end group
|
|
445 @group
|
39206
|
446 (single-key-description 'delete)
|
|
447 @result{} "<delete>"
|
|
448 @end group
|
|
449 @group
|
6381
|
450 (single-key-description 'C-mouse-1)
|
39206
|
451 @result{} "<C-mouse-1>"
|
|
452 @end group
|
|
453 @group
|
|
454 (single-key-description 'C-mouse-1 t)
|
6381
|
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
|
56213
|
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.
|
6381
|
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)
|
54032
dbcba6606213
(Describing Characters): Fix text-char-description example output.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
477 @result{} "\xed"
|
6381
|
478 @end group
|
|
479 @group
|
|
480 (text-char-description ?\C-\M-m)
|
54032
dbcba6606213
(Describing Characters): Fix text-char-description example output.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
481 @result{} "\x8d"
|
6381
|
482 @end group
|
56213
|
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
|
6381
|
491 @end smallexample
|
|
492 @end defun
|
|
493
|
56213
|
494 @defun read-kbd-macro string &optional need-vector
|
22138
|
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
|
56213
|
500 events you use; @pxref{Keymap Terminology}.) If @var{need-vector} is
|
|
501 non-@code{nil}, the return value is always a vector.
|
22138
|
502 @end defun
|
|
503
|
6381
|
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
|
67700
|
512 @deffn Command apropos pattern &optional do-all
|
56213
|
513 This function finds all ``meaningful'' symbols whose names contain a
|
67700
|
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
|
|
518 definition as a function, variable, or face, or has properties.
|
|
519
|
|
520 The function returns a list of elements that look like this:
|
|
521
|
|
522 @example
|
67736
|
523 (@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
|
|
524 @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
|
67700
|
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
|
56213
|
532 with a one-line description taken from the beginning of its
|
67700
|
533 documentation string.
|
6381
|
534
|
|
535 @c Emacs 19 feature
|
56213
|
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).
|
6381
|
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
|
21007
|
549 This symbol is not a function; its function definition cell holds the
|
6381
|
550 keymap known as @code{help-map}. It is defined in @file{help.el} as
|
|
551 follows:
|
|
552
|
|
553 @smallexample
|
|
554 @group
|
56213
|
555 (define-key global-map (char-to-string help-char) 'help-command)
|
6381
|
556 (fset 'help-command help-map)
|
|
557 @end group
|
|
558 @end smallexample
|
|
559 @end deffn
|
|
560
|
|
561 @defun print-help-return-message &optional function
|
7254
|
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.
|
6381
|
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
|
22138
|
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.
|
6381
|
580
|
22252
|
581 Usually the value of @code{help-form} is @code{nil}. Then the
|
6381
|
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
|
22138
|
593 @defvar help-event-list
|
21682
|
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
|
6381
|
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
|
21682
|
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.
|
6381
|
609
|
|
610 Entry to the minibuffer binds this variable to the value of
|
56213
|
611 @code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
|
6381
|
612 @end defvar
|
|
613
|
|
614 @defvar prefix-help-command
|
21682
|
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}.
|
6381
|
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
|
7254
|
625 sequence. (The last event is, presumably, the help character.)
|
6381
|
626 @end defun
|
|
627
|
22138
|
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.
|
6381
|
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
|
56213
|
650 @anchor{Definition of data-directory}
|
6381
|
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
|
49600
|
658 This macro defines a help command named @var{fname} that acts like a
|
7254
|
659 prefix key that shows a list of the subcommands it offers.
|
6381
|
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
|
7254
|
663 string @var{help-text} should describe the bindings available in
|
6381
|
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
|
7254
|
669 event. When it reads an event that is not one of those few, and which
|
6381
|
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}.
|
21007
|
677
|
|
678 This macro is used in the command @code{help-for-help} which is the
|
|
679 binding of @kbd{C-h C-h}.
|
6381
|
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
|
52401
|
688
|
|
689 @ignore
|
|
690 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
|
|
691 @end ignore
|