(frame-initialize): Don't count MSDOS neither as

[gnu-emacs] / lispref / help.texi

diff --git a/lispref/help.texi b/lispref/help.texi
index 68fb6330f94bdced216dc46c13209c508ecc8173..d551a1968bd45d18f4d721cfaecc7debc0e7637e 100644 (file)
--- 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}.)
 
 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
 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
 @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
 
   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}.
 
 @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
 @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
 
 @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
 @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
 
 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
 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.
 
 @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
 
 @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:
 
 
   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.
 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
 
 @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
 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:
 @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
 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
 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
 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
 
 @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.
 
 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.
 
 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.)
 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
 
 @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:
 
 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
 @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
 
 @defvar help-map


@@ -504,11 +508,10 @@ follows:
 @end deffn
 
 @defun print-help-return-message &optional function
 @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 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
 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}.
 @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
 
 @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
 
 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
 @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.
 
 has a binding in @var{help-map}, it executes that key's binding and
 then returns.