2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
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
9 @cindex documentation strings
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.
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
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.
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
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.
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}.
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{Accessing Documentation}.)
64 In Emacs Lisp, a documentation string is accessible through the
65 function or variable that it describes:
69 The documentation for a function is stored in the function definition
70 itself (@pxref{Lambda Expressions}). The function @code{documentation}
71 knows how to extract it.
74 @kindex variable-documentation
75 The documentation for a variable is stored in the variable's property
76 list under the property name @code{variable-documentation}. The
77 function @code{documentation-property} knows how to retrieve it.
80 @cindex @file{DOC} (documentation) file
81 @cindex @file{emacs/etc/DOC-@var{version}}
82 @cindex @file{etc/DOC-@var{version}}
83 To save space, the documentation for preloaded functions and variables
84 (including primitive functions and autoloaded functions) is stored in
85 the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
86 documentation strings for functions and variables loaded during the
87 Emacs session from byte-compiled files are stored in those files
88 (@pxref{Docs and Compilation}).
90 The data structure inside Emacs has an integer offset into the file, or
91 a list containing a file name and an integer, in place of the
92 documentation string. The functions @code{documentation} and
93 @code{documentation-property} use that information to fetch the
94 documentation string from the appropriate file; this is transparent to
97 For information on the uses of documentation strings, see @ref{Help, ,
98 Help, emacs, The GNU Emacs Manual}.
100 @c Wordy to prevent overfull hbox. --rjc 15mar92
101 The @file{emacs/lib-src} directory contains two utilities that you can
102 use to print nice-looking hardcopy for the file
103 @file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
106 @node Accessing Documentation
107 @section Access to Documentation Strings
109 @defun documentation-property symbol property &optional verbatim
110 This function returns the documentation string that is recorded in
111 @var{symbol}'s property list under property @var{property}. It
112 retrieves the text from a file if the value calls for that. If the
113 property value isn't @code{nil}, isn't a string, and doesn't refer to
114 text in a file, then it is evaluated to obtain a string.
116 Finally, @code{documentation-property} passes the string through
117 @code{substitute-command-keys} to substitute actual key bindings,
118 unless @var{verbatim} is non-@code{nil}.
122 (documentation-property 'command-line-processed
123 'variable-documentation)
124 @result{} "Non-nil once command line has been processed"
127 (symbol-plist 'command-line-processed)
128 @result{} (variable-documentation 188902)
133 @defun documentation function &optional verbatim
134 This function returns the documentation string of @var{function}.
136 If @var{function} is a symbol, this function first looks for the
137 @code{function-documentation} property of that symbol; if that has a
138 non-@code{nil} value, the documentation comes from that value (if the
139 value is not a string, it is evaluated). If @var{function} is not a
140 symbol, or if it has no @code{function-documentation} property, then
141 @code{documentation} extracts the documentation string from the actual
142 function definition, reading it from a file if called for.
144 Finally, unless @var{verbatim} is non-@code{nil}, it calls
145 @code{substitute-command-keys} so as to return a value containing the
146 actual (current) key bindings.
148 The function @code{documentation} signals a @code{void-function} error
149 if @var{function} has no function definition. However, it is OK if
150 the function definition has no documentation string. In that case,
151 @code{documentation} returns @code{nil}.
154 @c Wordy to prevent overfull hboxes. --rjc 15mar92
155 Here is an example of using the two functions, @code{documentation} and
156 @code{documentation-property}, to display the documentation strings for
157 several symbols in a @samp{*Help*} buffer.
159 @anchor{describe-symbols example}
162 (defun describe-symbols (pattern)
163 "Describe the Emacs Lisp symbols matching PATTERN.
164 All symbols that have PATTERN in their name are described
165 in the `*Help*' buffer."
166 (interactive "sDescribe symbols matching: ")
172 ;; @r{Print description of symbol.}
173 (if (fboundp s) ; @r{It is a function.}
175 (format "%s\t%s\n%s\n\n" s
177 (let ((keys (where-is-internal s)))
181 (mapconcat 'key-description
187 (or (documentation s)
190 (if (boundp s) ; @r{It is a variable.}
194 (format "%s\t%s\n%s\n\n" s
195 (if (user-variable-p s)
196 "Option " "Variable")
199 (or (documentation-property
200 s 'variable-documentation)
201 "not documented")))))))
206 ;; @r{Build a list of symbols that match pattern.}
209 (if (string-match pattern (symbol-name sym))
210 (setq sym-list (cons sym sym-list))))))
214 ;; @r{Display the data.}
215 (with-output-to-temp-buffer "*Help*"
216 (mapcar describe-func (sort sym-list 'string<))
217 (print-help-return-message))))
221 The @code{describe-symbols} function works like @code{apropos},
222 but provides more information.
226 (describe-symbols "goal")
228 ---------- Buffer: *Help* ----------
230 *Semipermanent goal column for vertical motion, as set by @dots{}
232 @c Do not blithely break or fill these lines.
233 @c That makes them incorrect.
236 set-goal-column Keys: C-x C-n
237 Set the current horizontal position as a goal for C-n and C-p.
239 @c DO NOT put a blank line here! That is factually inaccurate!
241 Those commands will move to this position in the line moved to
242 rather than trying to keep the same horizontal position.
243 With a non-nil argument, clears out the goal column
244 so that C-n and C-p resume vertical motion.
245 The goal column is stored in the variable `goal-column'.
249 temporary-goal-column Variable
250 Current goal column for vertical motion.
251 It is the column where point was
252 at the start of current run of vertical motion commands.
253 When the `track-eol' feature is doing its job, the value is 9999.
254 ---------- Buffer: *Help* ----------
258 The asterisk @samp{*} as the first character of a variable's doc string,
259 as shown above for the @code{goal-column} variable, means that it is a
260 user option; see the description of @code{defvar} in @ref{Defining
263 @anchor{Definition of Snarf-documentation}
264 @defun Snarf-documentation filename
265 This function is used only during Emacs initialization, just before
266 the runnable Emacs is dumped. It finds the file offsets of the
267 documentation strings stored in the file @var{filename}, and records
268 them in the in-core function definitions and variable property lists in
269 place of the actual strings. @xref{Building Emacs}.
271 Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
272 When the dumped Emacs is later executed, the same file will be looked
273 for in the directory @code{doc-directory}. Usually @var{filename} is
274 @code{"DOC-@var{version}"}.
278 @defvar doc-directory
279 This variable holds the name of the directory which should contain the
280 file @code{"DOC-@var{version}"} that contains documentation strings for
281 built-in and preloaded functions and variables.
283 In most cases, this is the same as @code{data-directory}. They may be
284 different when you run Emacs from the directory where you built it,
285 without actually installing it. See @code{data-directory} in @ref{Help
288 In older Emacs versions, @code{exec-directory} was used for this.
291 @node Keys in Documentation
292 @section Substituting Key Bindings in Documentation
293 @cindex documentation, keys in
294 @cindex keys in documentation strings
295 @cindex substituting keys in documentation
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.
304 Here is a list of the special sequences and what they mean:
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.
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}.
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.
321 quotes the following character and is discarded; thus, @samp{\=\[} puts
322 @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
326 @strong{Please note:} Each @samp{\} must be doubled when written in a
327 string in Emacs Lisp.
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.
336 Here are examples of the special sequences:
340 (substitute-command-keys
341 "To abort recursive edit, type: \\[abort-recursive-edit]")
342 @result{} "To abort recursive edit, type: C-]"
346 (substitute-command-keys
347 "The keys that are defined for the minibuffer here are:
348 \\@{minibuffer-local-must-match-map@}")
349 @result{} "The keys that are defined for the minibuffer here are:
352 ? minibuffer-completion-help
353 SPC minibuffer-complete-word
354 TAB minibuffer-complete
355 C-j minibuffer-complete-and-exit
356 RET minibuffer-complete-and-exit
357 C-g abort-recursive-edit
361 (substitute-command-keys
362 "To abort a recursive edit from the minibuffer, type\
363 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
364 @result{} "To abort a recursive edit from the minibuffer, type C-g."
368 @node Describing Characters
369 @section Describing Characters for Help Messages
371 These functions convert events, key sequences, or characters to
372 textual descriptions. These descriptions are useful for including
373 arbitrary text characters or key sequences in messages, because they
374 convert non-printing and whitespace characters to sequences of printing
375 characters. The description of a non-whitespace printing character is
376 the character itself.
378 @defun key-description sequence
379 @cindex Emacs event standard notation
380 This function returns a string containing the Emacs standard notation
381 for the input events in @var{sequence}. The argument @var{sequence} may
382 be a string, vector or list. @xref{Input Events}, for more information
383 about valid events. See also the examples for
384 @code{single-key-description}, below.
387 @defun single-key-description event &optional no-angles
388 @cindex event printing
389 @cindex character printing
390 @cindex control character printing
391 @cindex meta character printing
392 This function returns a string describing @var{event} in the standard
393 Emacs notation for keyboard input. A normal printing character
394 appears as itself, but a control character turns into a string
395 starting with @samp{C-}, a meta character turns into a string starting
396 with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
397 @samp{TAB}, etc. A function key symbol appears inside angle brackets
398 @samp{<@dots{}>}. An event that is a list appears as the name of the
399 symbol in the @sc{car} of the list, inside angle brackets.
401 If the optional argument @var{no-angles} is non-@code{nil}, the angle
402 brackets around function keys and event symbols are omitted; this is
403 for compatibility with old versions of Emacs which didn't use the
408 (single-key-description ?\C-x)
412 (key-description "\C-x \M-y \n \t \r \f123")
413 @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
416 (single-key-description 'delete)
420 (single-key-description 'C-mouse-1)
421 @result{} "<C-mouse-1>"
424 (single-key-description 'C-mouse-1 t)
425 @result{} "C-mouse-1"
430 @defun text-char-description character
431 This function returns a string describing @var{character} in the
432 standard Emacs 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 Emacs buffers are usually displayed).
439 (text-char-description ?\C-c)
443 (text-char-description ?\M-m)
447 (text-char-description ?\C-\M-m)
453 @defun read-kbd-macro string
454 This function is used mainly for operating on keyboard macros, but it
455 can also be used as a rough inverse for @code{key-description}. You
456 call it with a string containing key descriptions, separated by spaces;
457 it returns a string or vector containing the corresponding events.
458 (This may or may not be a single valid key sequence, depending on what
459 events you use; @pxref{Keymap Terminology}.)
463 @section Help Functions
465 Emacs provides a variety of on-line help functions, all accessible to
466 the user as subcommands of the prefix @kbd{C-h}. For more information
467 about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
468 we describe some program-level interfaces to the same information.
470 @deffn Command apropos regexp &optional do-all
471 This function finds all symbols whose names contain a match for the
472 regular expression @var{regexp}, and returns a list of them
473 (@pxref{Regular Expressions}). It also displays the symbols in a buffer
474 named @samp{*Help*}, each with a one-line description taken from the
475 beginning of its documentation string.
478 If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
479 bindings for the functions that are found; it also shows all symbols,
480 even those that are neither functions nor variables.
482 In the first of the following examples, @code{apropos} finds all the
483 symbols with names containing @samp{exec}. (We don't show here the
484 output that results in the @samp{*Help*} buffer.)
489 @result{} (Buffer-menu-execute command-execute exec-directory
490 exec-path execute-extended-command execute-kbd-macro
491 executing-kbd-macro executing-macro)
497 The value of this variable is a local keymap for characters following the
501 @deffn {Prefix Command} help-command
502 This symbol is not a function; its function definition cell holds the
503 keymap known as @code{help-map}. It is defined in @file{help.el} as
508 (define-key global-map "\C-h" 'help-command)
509 (fset 'help-command help-map)
514 @defun print-help-return-message &optional function
515 This function builds a string that explains how to restore the previous
516 state of the windows after a help command. After building the message,
517 it applies @var{function} to it if @var{function} is non-@code{nil}.
518 Otherwise it calls @code{message} to display it in the echo area.
520 This function expects to be called inside a
521 @code{with-output-to-temp-buffer} special form, and expects
522 @code{standard-output} to have the value bound by that special form.
523 For an example of its use, see the long example in @ref{Accessing
528 The value of this variable is the help character---the character that
529 Emacs recognizes as meaning Help. By default, its value is 8, which
530 stands for @kbd{C-h}. When Emacs reads this character, if
531 @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
532 expression, and displays the result in a window if it is a string.
534 Usually the value of @code{help-form} is @code{nil}. Then the
535 help character has no special meaning at the level of command input, and
536 it becomes part of a key sequence in the normal way. The standard key
537 binding of @kbd{C-h} is a prefix key for several general-purpose help
540 The help character is special after prefix keys, too. If it has no
541 binding as a subcommand of the prefix key, it runs
542 @code{describe-prefix-bindings}, which displays a list of all the
543 subcommands of the prefix key.
546 @defvar help-event-list
547 The value of this variable is a list of event types that serve as
548 alternative ``help characters.'' These events are handled just like the
549 event specified by @code{help-char}.
553 If this variable is non-@code{nil}, its value is a form to evaluate
554 whenever the character @code{help-char} is read. If evaluating the form
555 produces a string, that string is displayed.
557 A command that calls @code{read-event} or @code{read-char} probably
558 should bind @code{help-form} to a non-@code{nil} expression while it
559 does input. (The time when you should not do this is when @kbd{C-h} has
560 some other meaning.) Evaluating this expression should result in a
561 string that explains what the input is for and how to enter it properly.
563 Entry to the minibuffer binds this variable to the value of
564 @code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
567 @defvar prefix-help-command
568 This variable holds a function to print help for a prefix key. The
569 function is called when the user types a prefix key followed by the help
570 character, and the help character has no binding after that prefix. The
571 variable's default value is @code{describe-prefix-bindings}.
574 @defun describe-prefix-bindings
575 This function calls @code{describe-bindings} to display a list of all
576 the subcommands of the prefix key of the most recent key sequence. The
577 prefix described consists of all but the last event of that key
578 sequence. (The last event is, presumably, the help character.)
581 The following two functions are meant for modes that want to provide
582 help without relinquishing control, such as the ``electric'' modes.
583 Their names begin with @samp{Helper} to distinguish them from the
584 ordinary help functions.
586 @deffn Command Helper-describe-bindings
587 This command pops up a window displaying a help buffer containing a
588 listing of all of the key bindings from both the local and global keymaps.
589 It works by calling @code{describe-bindings}.
592 @deffn Command Helper-help
593 This command provides help for the current mode. It prompts the user
594 in the minibuffer with the message @samp{Help (Type ? for further
595 options)}, and then provides assistance in finding out what the key
596 bindings are, and what the mode is intended for. It returns @code{nil}.
598 This can be customized by changing the map @code{Helper-help-map}.
602 @defvar data-directory
603 This variable holds the name of the directory in which Emacs finds
604 certain documentation and text files that come with Emacs. In older
605 Emacs versions, @code{exec-directory} was used for this.
609 @defmac make-help-screen fname help-line help-text help-map
610 This macro defines a help command named @var{fname} that acts like a
611 prefix key that shows a list of the subcommands it offers.
613 When invoked, @var{fname} displays @var{help-text} in a window, then
614 reads and executes a key sequence according to @var{help-map}. The
615 string @var{help-text} should describe the bindings available in
618 The command @var{fname} is defined to handle a few events itself, by
619 scrolling the display of @var{help-text}. When @var{fname} reads one of
620 those special events, it does the scrolling and then reads another
621 event. When it reads an event that is not one of those few, and which
622 has a binding in @var{help-map}, it executes that key's binding and
625 The argument @var{help-line} should be a single-line summary of the
626 alternatives in @var{help-map}. In the current version of Emacs, this
627 argument is used only if you set the option @code{three-step-help} to
630 This macro is used in the command @code{help-for-help} which is the
631 binding of @kbd{C-h C-h}.
634 @defopt three-step-help
635 If this variable is non-@code{nil}, commands defined with
636 @code{make-help-screen} display their @var{help-line} strings in the
637 echo area at first, and display the longer @var{help-text} strings only
638 if the user types the help character again.
642 arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815