(Describing Characters) <single-key-description>:

Document the new argument no-angles.
(Accessing Documentation) <documentation-property>: Document that
a non-string property is evaluated.
<documentation>: Document that the function-documentation property
is looked for.

1 files changed, 29 insertions, 8 deletions

diff --git a/lispref/help.texi b/lispref/help.texi
index eeb8d998755..a601825d053 100644
--- a/lispref/help.texi
+++ b/lispref/help.texi
@@ -111,7 +111,9 @@ 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}.)
+substitution is not done if @var{verbatim} is non-@code{nil}.)  If
+@var{property} isn't a string and doesn't refer to the documentation
+file @file{etc/DOC}, it is evaluated to obtain a string.
 
 @smallexample
 @group
@@ -127,10 +129,15 @@ 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 looks for a
+@code{function-documentation'} property of that symbol; if it has a
+non-@code{nil} value, the documentation is taken from that value (if
+the value is not a string, it is evaluated).  Alternatively,
+@code{documentation} 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
 if @var{function} has no function definition.  However, it is OK if
@@ -369,7 +376,7 @@ 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
@@ -379,8 +386,14 @@ 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.
+function key symbol appears as itsels, but inside angle brackets
+@samp{<>}.  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 print the
+brackets.
 
 @smallexample
 @group
@@ -392,7 +405,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