Mercurial > hg > xemacs-beta
annotate man/lispref/help.texi @ 5384:3889ef128488
Fix misspelled words, and some grammar, across the entire source tree.
See xemacs-patches message with ID
<AANLkTi=edkEKtK3pZ60ytsG5pTJQy2TjAEVCZCLOa-oA@mail.gmail.com>.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Thu, 24 Mar 2011 11:00:11 -0600 |
| parents | 755ae5b97edb |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 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 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2444
diff
changeset
|
558 @code{with-output-to-temp-buffer} form, and expects |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2444
diff
changeset
|
559 @code{standard-output} to have the value bound by that special operator. |
| 428 | 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}. |