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