to the keys for related commands and be accurate even when a user
rearranges the key bindings. (@xref{Accessing Documentation}.)
- Within the Lisp world, a documentation string is kept with the
+ Within the Lisp world, a documentation string accessible through the
function or variable that it describes:
@itemize @bullet
@cindex @file{emacs/etc/DOC-@var{version}}
@cindex @file{etc/DOC-@var{version}}
To save space, the documentation for preloaded functions and variables
-(including primitive functions and autoloaded functions) are stored in
-the file @file{emacs/etc/DOC-@var{version}}. The data structure inside
-Emacs has an integer offset into the file, where the documentation
-string ought to be. The functions @code{documentation} the
-@code{documentation-property} read the documentation from the file
-@file{emacs/etc/DOC-@var{version}} when they notice the integer there;
-this is transparent to the user. Keeping the documentation strings out
-of the Emacs core image saves a significant amount of space.
-@xref{Building Emacs}.
+(including primitive functions and autoloaded functions) is stored in
+the file @file{emacs/etc/DOC-@var{version}}. The documentation for
+functions and variables loaded during the Emacs session from
+byte-compiled files is 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 string and an integer, in place of the documentation
+string. The functions @code{documentation} and
+@code{documentation-property} use that information to read the
+documentation from the appropriate file; this is transparent to the
+user.
For information on the uses of documentation strings, see @ref{Help, ,
Help, emacs, The GNU Emacs Manual}.
@defun documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded
@var{symbol}'s property list under property @var{property}. It
-retrieves the text from the file @file{emacs/etc/DOC-@var{version}} if
-necessary, and runs @code{substitute-command-keys} to substitute actual
-key bindings. (This substitution is not done if @var{verbatim} is
-non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.)
+retrieves the text from a file if necessary, and runs
+@code{substitute-command-keys} to substitute actual key bindings. (This
+substitution is not done if @var{verbatim} is non-@code{nil}; the
+@var{verbatim} argument exists only as of Emacs 19.)
@smallexample
@group
@end defun
@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}.
-This function will access the documentation string if it is stored in
-the @file{emacs/etc/DOC-@var{version}} file.
-
-In addition, @code{documentation} runs @code{substitute-command-keys}
-on the resulting string, so the value contains the actual (current) key
-bindings. (This is not done if @var{verbatim} is non-@code{nil}; the
-@var{verbatim} argument exists only as of Emacs 19.)
+This function returns the documentation string of @var{function}. It
+reads the text from a file if necessary. Then (unless @var{verbatim} is
+non-@code{nil}) it calls @code{substitute-command-keys}, to return a
+value containing the actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
-unless @var{function} has a function definition. However, it is ok if
+if @var{function} has no function definition. However, it is ok if
the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
@end defun
@c Wordy to prevent overfull hboxes. --rjc 15mar92
- Here is an example of using the two functions, @code{documentation} and
+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.
---------- Buffer: *Help* ----------
goal-column Option
-*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
+*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.
@cindex keys in documentation strings
@cindex substituting keys in documentation
- When documentation strings refer to key sequences, they should do so
-based on the current, actual key bindings. They can do so using certain
-special text sequences described below. Accessing documentation strings
-in the usual way substitutes current key binding information for these
-special sequences. This works by calling @code{substitute-command-keys}.
-You can also call that function yourself.
+ When documentation strings refer to key sequences, they should use the
+current, actual key bindings. They can do so using certain special text
+sequences described below. Accessing documentation strings in the usual
+way substitutes current key binding information for these special
+sequences. This works by calling @code{substitute-command-keys}. You
+can also call that function yourself.
Here is a list of the special sequences and what they mean:
stands for no text itself. It is used for a side effect: it specifies
@var{mapvar} as the keymap for any following @samp{\[@var{command}]}
sequences in this documentation string.
+
+@item \=
+quotes the following character and is discarded; thus, @samp{\=\[} puts
+@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
+output.
@end table
-@strong{Please note:} each @samp{\} must be doubled when written in a
+@strong{Please note:} Each @samp{\} must be doubled when written in a
string in Emacs Lisp.
@defun substitute-command-keys string
This function scans @var{string} for the above special sequences and
replaces them by what they stand for, returning the result as a string.
This permits display of documentation that refers accurately to the
-users's own customized key bindings.
+user's own customized key bindings.
@end defun
Here are examples of the special sequences:
as itself, but a control character turns into a string starting with
@samp{C-}, a meta character turns into a string starting with @samp{M-},
and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A
-function key symbol appears as itself. An event which is a list appears
+function key symbol appears as itself. An event that is a list appears
as the name of the symbol in the @sc{car} of the list.
@smallexample
we describe some program-level interfaces to the same information.
@deffn Command apropos regexp &optional do-all predicate
- This function finds all symbols whose names contain a match for the
-regular expression @var{regexp}, and returns a list of them.
-It also displays the symbols in a buffer named @samp{*Help*}, each with a
-one-line description.
+This function finds all symbols whose names contain a match for the
+regular expression @var{regexp}, and returns a list of them
+(@pxref{Regular Expressions}). It also displays the symbols in a buffer
+named @samp{*Help*}, each with a one-line description.
@c Emacs 19 feature
- If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
+If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
key bindings for the functions that are found.
- If @var{predicate} is non-@code{nil}, it should be a function to be
+If @var{predicate} is non-@code{nil}, it should be a function to be
called on each symbol that has matched @var{regexp}. Only symbols for
which @var{predicate} returns a non-@code{nil} value are listed or
displayed.
- In the first of the following examples, @code{apropos} finds all the
+In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. In the second example, it
finds and returns only those symbols that are also commands.
(We don't show the output that results in the @samp{*Help*} buffer.)
@end ignore
@end smallexample
- The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
+The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
but specifies a @var{predicate} to restrict the output to symbols that
are commands. The call to @code{apropos} looks like this:
@deffn Command super-apropos regexp &optional do-all
This function differs from @code{apropos} in that it searches
documentation strings as well as symbol names for matches for
-@var{regexp}. By default, it searches only the documentation strings,
-and only those of functions and variables that are included in Emacs
-when it is dumped. If @var{do-all} is non-@code{nil}, it scans the
-names and documentation strings of all functions and variables.
+@var{regexp}. By default, it searches the documentation strings only
+for preloaded functions and variables. If @var{do-all} is
+non-@code{nil}, it scans the names and documentation strings of all
+functions and variables.
@end deffn
@defvar help-map
@end deffn
@defun print-help-return-message &optional function
-This function builds a string which is a message explaining 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 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
This function calls @code{describe-bindings} to display a list of all
the subcommands of the prefix key of the most recent key sequence. The
prefix described consists of all but the last event of that key
-sequence.
+sequence. (The last event is, presumably, the help character.)
@end defun
The following two functions are found in the library @file{helper}.
@c Emacs 19 feature
@defmac make-help-screen fname help-line help-text help-map
-This macro defines a help command named @var{fname} which acts like a
-prefix key which shows a list of the subcommands it offers.
+This macro defines a help command named @var{fname} that acts like a
+prefix key that shows a list of the subcommands it offers.
When invoked, @var{fname} displays @var{help-text} in a window, then
reads and executes a key sequence according to @var{help-map}. The
-string @var{help-text} should describe of the bindings available in
+string @var{help-text} should describe the bindings available in
@var{help-map}.
The command @var{fname} is defined to handle a few events itself, by
scrolling the display of @var{help-text}. When @var{fname} reads one of
those special events, it does the scrolling and then reads another
-event. When it reads an event which is not one of those few, and which
+event. When it reads an event that is not one of those few, and which
has a binding in @var{help-map}, it executes that key's binding and
then returns.
HCoop / bpt / emacs.git / blobdiff