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