Correct the explanation of glyphs and glyph table.

[bpt/emacs.git] / lispref / help.texi

diff --git a/lispref/help.texi b/lispref/help.texi
index 12beaf2..eb9dc0a 100644 (file)
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -107,11 +107,15 @@ use to print nice-looking hardcopy for the file
 @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 necessary, and runs
-@code{substitute-command-keys} to substitute actual key bindings.  (This
-substitution is not done if @var{verbatim} is non-@code{nil}.)
+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.
+
+Finally, @code{documentation-property} passes the string through
+@code{substitute-command-keys} to substitute actual key bindings,
+unless @var{verbatim} is non-@code{nil}.
 
 @smallexample
 @group
@@ -127,10 +131,19 @@ substitution is not done if @var{verbatim} is non-@code{nil}.)
 @end defun
 
 @defun documentation function &optional verbatim
-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.
+This function returns the documentation string of @var{function}.
+
+If @var{function} is a symbol, this function first looks for the
+@code{function-documentation} property of that symbol; if that has a
+non-@code{nil} value, the documentation comes from that value (if the
+value is not a string, it is evaluated).  If @var{function} is not a
+symbol, or if it has no @code{function-documentation} property, then
+@code{documentation} extracts the documentation string from the actual
+function definition, reading it from a file if called for.
+
+Finally, unless @var{verbatim} is non-@code{nil}, it calls
+@code{substitute-command-keys} so as to return a value containing the
+actual (current) key bindings.
 
 The function @code{documentation} signals a @code{void-function} error
 if @var{function} has no function definition.  However, it is OK if
@@ -241,6 +254,11 @@ When the `track-eol' feature is doing its job, the value is 9999.
 @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
 This function is used only during Emacs initialization, just before
 the runnable Emacs is dumped.  It finds the file offsets of the
@@ -364,18 +382,24 @@ about valid events.  See also the examples for
 @code{single-key-description}, below.
 @end defun
 
-@defun single-key-description event
+@defun single-key-description event &optional no-angles
 @cindex event printing
 @cindex character printing
 @cindex control character printing
 @cindex meta character printing
 This function returns a string describing @var{event} in the standard
-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, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc.  A
-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.
+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, tab, etc.@: appear as @samp{SPC},
+@samp{TAB}, etc.  A function key symbol appears inside angle brackets
+@samp{<@dots{}>}.  An event that is a list appears as the name of the
+symbol in the @sc{car} of the list, inside angle brackets.
+
+If the optional argument @var{no-angles} is non-@code{nil}, the angle
+brackets around function keys and event symbols are omitted; this is
+for compatibility with old versions of Emacs which didn't use the
+brackets.
 
 @smallexample
 @group
@@ -387,7 +411,15 @@ as the name of the symbol in the @sc{car} of the list.
      @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
 @end group
 @group
+(single-key-description 'delete)
+     @result{} "<delete>"
+@end group
+@group
 (single-key-description 'C-mouse-1)
+     @result{} "<C-mouse-1>"
+@end group
+@group
+(single-key-description 'C-mouse-1 t)
      @result{} "C-mouse-1"
 @end group
 @end smallexample