changeset 39206:41ede3832703

(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.

--- a/lispref/help.texi	Sat Sep 08 17:49:11 2001 +0000
+++ b/lispref/help.texi	Sat Sep 08 17:50:08 2001 +0000
@@ -111,7 +111,9 @@
 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 @@
 @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 @@
 @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 @@
 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 @@
      @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