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