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