@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/help
@node Documentation, Files, Modes, Top
@chapter Documentation
@cindex documentation strings
- GNU Emacs Lisp has convenient on-line help facilities, most of which
-derive their information from the documentation strings associated with
-functions and variables. This chapter describes how to write good
-documentation strings for your Lisp programs, as well as how to write
-programs to access documentation.
+ GNU Emacs has convenient built-in help facilities, most of which
+derive their information from documentation strings associated with
+functions and variables. This chapter describes how to access
+documentation strings in Lisp programs. @xref{Documentation Tips},
+for how to write good documentation strings.
Note that the documentation strings for Emacs are not the same thing
as the Emacs manual. Manuals have their own source files, written in
topics of discussion.
For commands to display documentation strings, see @ref{Help, ,
-Help, emacs, The GNU Emacs Manual}. For the conventions for writing
-documentation strings, see @ref{Documentation Tips}.
+Help, emacs, The GNU Emacs Manual}.
@menu
-* Documentation Basics:: Good style for doc strings.
- Where to put them. How Emacs stores them.
+* Documentation Basics:: Where doc strings are defined and stored.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
documentation string follows the initial value of the variable.
When you write a documentation string, make the first line a
-complete sentence (or two complete sentences) since some commands,
-such as @code{apropos}, show only the first line of a multi-line
-documentation string. Also, you should not indent the second line of
-a documentation string, if it has one, because that looks odd when you
+complete sentence (or two complete sentences) that briefly describes
+what the function or variable does. Some commands, such as
+@code{apropos}, show only the first line of a multi-line documentation
+string. Also, you should not indent the second line of a
+documentation string, if it has one, because that looks odd when you
use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
(@code{describe-variable}) to view the documentation string. There
-are many other conventions for doc strings; see @ref{Documentation
-Tips}.
+are many other conventions for documentation strings; see
+@ref{Documentation Tips}.
Documentation strings can contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
Emacs Lisp mode fills documentation strings to the width
specified by @code{emacs-lisp-docstring-fill-column}.
- In Emacs Lisp, a documentation string is accessible through the
-function or variable that it describes:
+ Exactly where a documentation string is stored depends on how its
+function or variable was defined or loaded into memory:
@itemize @bullet
@item
@kindex function-documentation
-The documentation for a function is usually stored in the function
-definition itself (@pxref{Lambda Expressions}). The function
-@code{documentation} knows how to extract it. You can also put
-function documentation in the @code{function-documentation} property
-of the function name. That is useful with definitions such as
-keyboard macros that can't hold a documentation string.
+When you define a function (@pxref{Lambda Expressions}, and
+@pxref{Function Documentation}), the documentation string is stored in
+the function definition itself. You can also put function
+documentation in the @code{function-documentation} property of a
+function name. That is useful for function definitions which can't
+hold a documentation string, such as keyboard macros.
@item
@kindex variable-documentation
-The documentation for a variable is stored in the variable's property
-list under the property name @code{variable-documentation}. The
-function @code{documentation-property} knows how to retrieve it.
-@end itemize
+When you define a variable with a @code{defvar} or related form
+(@pxref{Defining Variables}), the documentation is stored in the
+variable's @code{variable-documentation} property.
@cindex @file{DOC-@var{version}} (documentation) file
-To save space, the documentation for preloaded functions and variables
-(including primitive functions and autoloaded functions) is stored in
-the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
-documentation strings for functions and variables loaded during the
-Emacs session from byte-compiled files are stored in those files
-(@pxref{Docs and Compilation}).
-
-The data structure inside Emacs has an integer offset into the file, or
-a list containing a file name and an integer, in place of the
-documentation string. The functions @code{documentation} and
-@code{documentation-property} use that information to fetch the
-documentation string from the appropriate file; this is transparent to
-the user.
-
-@c Wordy to prevent overfull hbox. --rjc 15mar92
- The @file{emacs/lib-src} directory contains two utilities that you can
-use to print nice-looking hardcopy for the file
-@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
-@file{digest-doc}.
+@item
+To save memory, the documentation for preloaded functions and
+variables (including primitive functions and autoloaded functions) is
+not kept in memory, but in the file
+@file{emacs/etc/DOC-@var{version}}, where @var{version} is the Emacs
+version number (@pxref{Version Info}).
+
+@item
+When a function or variable is loaded from a byte-compiled file during
+the Emacs session, its documentation string is not loaded into memory.
+Instead, Emacs looks it up in the byte-compiled file as needed.
+@xref{Docs and Compilation}.
+@end itemize
+
+@noindent
+Regardless of where the documentation string is stored, you can
+retrieve it using the @code{documentation} or
+@code{documentation-property} function, described in the next section.
@node Accessing Documentation
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
-This function returns the documentation string that is recorded in
-@var{symbol}'s property list under property @var{property}. It
-retrieves the text from a file if the value calls for that. If the
-property value isn't @code{nil}, isn't a string, and doesn't refer to
-text in a file, then it is evaluated to obtain a string.
+This function returns the documentation string recorded in
+@var{symbol}'s property list under property @var{property}. It is
+most often used to look up the documentation strings of variables, for
+which @var{property} is @code{variable-documentation}. However, it
+can also be used to look up other kinds of documentation, such as for
+customization groups (but for function documentation, use the
+@code{documentation} command, below).
+
+If the value recorded in the property list refers to a documentation
+string stored in a @file{DOC-@var{version}} file or a byte-compiled
+file, it looks up that string and returns it. If the property value
+isn't @code{nil}, isn't a string, and doesn't refer to text in a file,
+then it is evaluated as a Lisp expression to obtain a string.
The last thing this function does is pass the string through
-@code{substitute-command-keys} to substitute actual key bindings,
-unless @var{verbatim} is non-@code{nil}.
+@code{substitute-command-keys} to substitute actual key bindings
+(@pxref{Keys in Documentation}). However, it skips this step if
+@var{verbatim} is non-@code{nil}.
@smallexample
@group
@end defun
@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}.
-@code{documentation} handles macros, named keyboard macros, and
-special forms, as well as ordinary functions.
+This function returns the documentation string of @var{function}. It
+handles macros, named keyboard macros, and special forms, as well as
+ordinary functions.
If @var{function} is a symbol, this function first looks for the
@code{function-documentation} property of that symbol; if that has a
@c Wordy to prevent overfull hboxes. --rjc 15mar92
Here is an example of using the two functions, @code{documentation} and
@code{documentation-property}, to display the documentation strings for
-several symbols in a @samp{*Help*} buffer.
+several symbols in a @file{*Help*} buffer.
@anchor{describe-symbols example}
@smallexample
@group
(princ
(format "%s\t%s\n%s\n\n" s
- (if (user-variable-p s)
+ (if (custom-variable-p s)
"Option " "Variable")
@end group
@group
@group
;; @r{Display the data.}
- (with-output-to-temp-buffer "*Help*"
- (mapcar describe-func (sort sym-list 'string<))
- (print-help-return-message))))
+ (help-setup-xref (list 'describe-symbols pattern) (interactive-p))
+ (with-help-window (help-buffer)
+ (mapcar describe-func (sort sym-list 'string<)))))
@end group
@end smallexample
---------- Buffer: *Help* ----------
goal-column Option
-*Semipermanent goal column for vertical motion, as set by @dots{}
+Semipermanent goal column for vertical motion, as set by @dots{}
@end group
@c Do not blithely break or fill these lines.
@c That makes them incorrect.
@end group
@end smallexample
-The asterisk @samp{*} as the first character of a variable's doc string,
-as shown above for the @code{goal-column} variable, means that it is a
-user option; see the description of @code{defvar} in @ref{Defining
-Variables}.
-
-@defun Snarf-documentation filename
@anchor{Definition of Snarf-documentation}
-This function is used only during Emacs initialization, just before
-the runnable Emacs is dumped. It finds the file offsets of the
-documentation strings stored in the file @var{filename}, and records
-them in the in-core function definitions and variable property lists in
-place of the actual strings. @xref{Building Emacs}.
+@defun Snarf-documentation filename
+This function is used when building Emacs, just before the runnable
+Emacs is dumped. It finds the positions of the documentation strings
+stored in the file @var{filename}, and records those positions into
+memory in the function definitions and variable property lists.
+@xref{Building Emacs}.
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
@code{"DOC-@var{version}"}.
@end defun
-@c Emacs 19 feature
@defvar doc-directory
This variable holds the name of the directory which should contain the
file @code{"DOC-@var{version}"} that contains documentation strings for
In most cases, this is the same as @code{data-directory}. They may be
different when you run Emacs from the directory where you built it,
without actually installing it. @xref{Definition of data-directory}.
-
-In older Emacs versions, @code{exec-directory} was used for this.
@end defvar
@node Keys in Documentation
The function returns a list of elements that look like this:
@example
-(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
+(@var{symbol} @var{score} @var{function-doc} @var{variable-doc}
@var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
@end example
Here, @var{score} is an integer measure of how important the symbol
-seems to be as a match, and the remaining elements are documentation
-strings for @var{symbol}'s various roles (or @code{nil}).
+seems to be as a match. Each of the remaining elements is a
+documentation string, or @code{nil}, for @var{symbol} as a function,
+variable, etc.
-It also displays the symbols in a buffer named @samp{*Apropos*}, each
+It also displays the symbols in a buffer named @file{*Apropos*}, each
with a one-line description taken from the beginning of its
documentation string.
-@c Emacs 19 feature
If @var{do-all} is non-@code{nil}, or if the user option
@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
shows key bindings for the functions that are found; it also shows
@smallexample
@group
-(define-key global-map (char-to-string help-char) 'help-command)
+(define-key global-map (string help-char) 'help-command)
(fset 'help-command help-map)
@end group
@end smallexample
@end deffn
-@defun print-help-return-message &optional function
-This function builds a string that explains how to restore the previous
-state of the windows after a help command. After building the message,
-it applies @var{function} to it if @var{function} is non-@code{nil}.
-Otherwise it calls @code{message} to display it in the echo area.
-
-This function expects to be called inside a
-@code{with-output-to-temp-buffer} special form, and expects
-@code{standard-output} to have the value bound by that special form.
-For an example of its use, see the long example in @ref{Accessing
-Documentation}.
-@end defun
-
-@defvar help-char
+@defopt help-char
The value of this variable is the help character---the character that
Emacs recognizes as meaning Help. By default, its value is 8, which
stands for @kbd{C-h}. When Emacs reads this character, if
binding as a subcommand of the prefix key, it runs
@code{describe-prefix-bindings}, which displays a list of all the
subcommands of the prefix key.
-@end defvar
+@end defopt
-@defvar help-event-list
+@defopt help-event-list
The value of this variable is a list of event types that serve as
alternative ``help characters.'' These events are handled just like the
event specified by @code{help-char}.
-@end defvar
+@end defopt
@defvar help-form
If this variable is non-@code{nil}, its value is a form to evaluate
whenever the character @code{help-char} is read. If evaluating the form
produces a string, that string is displayed.
-A command that calls @code{read-event} or @code{read-char} probably
-should bind @code{help-form} to a non-@code{nil} expression while it
-does input. (The time when you should not do this is when @kbd{C-h} has
-some other meaning.) Evaluating this expression should result in a
-string that explains what the input is for and how to enter it properly.
+A command that calls @code{read-event}, @code{read-char-choice}, or
+@code{read-char} probably should bind @code{help-form} to a
+non-@code{nil} expression while it does input. (The time when you
+should not do this is when @kbd{C-h} has some other meaning.)
+Evaluating this expression should result in a string that explains
+what the input is for and how to enter it properly.
Entry to the minibuffer binds this variable to the value of
@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
options)}, and then provides assistance in finding out what the key
bindings are, and what the mode is intended for. It returns @code{nil}.
+@vindex Helper-help-map
This can be customized by changing the map @code{Helper-help-map}.
@end deffn
-@c Emacs 19 feature
@defvar data-directory
@anchor{Definition of data-directory}
This variable holds the name of the directory in which Emacs finds
-certain documentation and text files that come with Emacs. In older
-Emacs versions, @code{exec-directory} was used for this.
+certain documentation and text files that come with Emacs.
@end defvar
-@c Emacs 19 feature
+@defun help-buffer
+This function returns the name of the help buffer, which is normally
+@file{*Help*}; if such a buffer does not exist, it is first created.
+@end defun
+
+@defmac with-help-window buffer-name body@dots{}
+This macro evaluates the @var{body} forms, inserting any output they
+produce into a buffer named @var{buffer-name} like
+@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}).
+(Usually, @var{buffer-name} should be the value returned by the
+function @code{help-buffer}.) It also puts the specified buffer into
+Help mode and displays a message telling the user how to quit and
+scroll the help window.
+@end defmac
+
+@defun help-setup-xref item interactive-p
+This function updates the cross reference data in the @file{*Help*}
+buffer, which is used to regenerate the help information when the user
+clicks on the @samp{Back} or @samp{Forward} buttons. Most commands
+that use the @file{*Help*} buffer should invoke this function before
+clearing the buffer. The @var{item} argument should have the form
+@code{(@var{function} . @var{args})}, where @var{function} is a function
+to call, with argument list @var{args}, to regenerate the help buffer.
+The @var{interactive-p} argument is non-@code{nil} if the calling
+command was invoked interactively; in that case, the stack of items
+for the @file{*Help*} buffer's @samp{Back} buttons is cleared.
+@end defun
+
+@xref{describe-symbols example}, for an example of using
+@code{help-buffer}, @code{with-help-window}, and
+@code{help-setup-xref}.
+
@defmac make-help-screen fname help-line help-text help-map
This macro defines a help command named @var{fname} that acts like a
prefix key that shows a list of the subcommands it offers.
binding of @kbd{C-h C-h}.
@end defmac
-@defmac with-help-window buffer-name body@dots{}
-This macro evaluates the @var{body} forms, inserting any output they
-produce into a buffer named @var{buffer-name} like
-@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). It
-also puts that buffer in Help mode, displays a message telling the
-user how to quit and scroll the help window, and does various other
-things that make a help window work better.
-
-Don't use @code{print-help-return-message} in the body of this macro;
-it would cause bad results.
-@end defmac
-
@defopt three-step-help
If this variable is non-@code{nil}, commands defined with
@code{make-help-screen} display their @var{help-line} strings in the
if the user types the help character again.
@end defopt
-@ignore
- arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
-@end ignore
HCoop / bpt / emacs.git / blobdiff