X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/5e8db0c61e9bcb0d0d34bdeda19f88cfb90b20fe..004f057a42eeb76021b2de3f5f8b1fd07d0421f4:/lispref/help.texi diff --git a/lispref/help.texi b/lispref/help.texi index 68fb6330f9..d551a1968b 100644 --- a/lispref/help.texi +++ b/lispref/help.texi @@ -60,7 +60,7 @@ documentation is displayed. This allows documentation strings to refer 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 @@ -80,22 +80,25 @@ function @code{documentation-property} knows how to extract it. @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}. @c Wordy to prevent overfull hbox. --rjc 15mar92 - The @file{emacs/etc} directory contains two utilities that you can use -to print nice-looking hardcopy for the file + 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.c} and @file{digest-doc.c}. @@ -105,10 +108,10 @@ to print nice-looking hardcopy for the file @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 @@ -124,23 +127,19 @@ non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.) @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. @@ -275,12 +274,12 @@ In older Emacs versions, @code{exec-directory} was used for this. @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: @@ -297,16 +296,21 @@ keymap. The summary is made by @code{describe-bindings}. 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: @@ -370,7 +374,7 @@ Emacs notation for keyboard input. A normal printing character appears 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 @@ -421,21 +425,21 @@ about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here 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.) @@ -466,7 +470,7 @@ execute-extended-command ESC x @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: @@ -479,10 +483,10 @@ 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 @@ -504,11 +508,10 @@ follows: @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 @@ -562,7 +565,7 @@ The variable's default value is @code{describe-prefix-bindings}. 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}. @@ -595,18 +598,18 @@ Emacs versions, @code{exec-directory} was used for this. @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.