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