Mention what effect nil has as the prompt for read-event/char/etc

* doc/lispref/commands.texi (Reading One Event): Mention that ""
has the same effect as nil as a prompt.

* src/lread.c (Fread_event, Fread_char_exclusive, Fread_char):
Mention what happens when PROMPT is nil/"" in the doc string
(bug#15012).

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index c0df944f9ce5cb04799f54556e544919687ccad5..1fd56d028412310344348038981abc55f3637da4 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2504,12 +2504,12 @@ The returned event may come directly from the user, or from a keyboard
 macro.  It is not decoded by the keyboard's input coding system
 (@pxref{Terminal I/O Encoding}).
 
-If the optional argument @var{prompt} is non-@code{nil}, it should be a
-string to display in the echo area as a prompt.  Otherwise,
-@code{read-event} does not display any message to indicate it is waiting
-for input; instead, it prompts by echoing: it displays descriptions of
-the events that led to or were read by the current command.  @xref{The
-Echo Area}.
+If the optional argument @var{prompt} is non-@code{nil}, it should be
+a string to display in the echo area as a prompt.  If @var{prompt} is
+@code{nil} or the string @samp{""}, @code{read-event} does not display
+any message to indicate it is waiting for input; instead, it prompts
+by echoing: it displays descriptions of the events that led to or were
+read by the current command.  @xref{The Echo Area}.
 
 If @var{inherit-input-method} is non-@code{nil}, then the current input
 method (if any) is employed to make it possible to enter a

diff --git a/src/lread.c b/src/lread.c
index eec88760d4278236332e54e90621bb10adebfcfb..1bfbf5aa865e26ba13af3eac590caf9668ccf785 100644 (file)
--- a/src/lread.c
+++ b/src/lread.c
@@ -762,9 +762,13 @@ If you want to read non-character events, or ignore them, call
 `read-event' or `read-char-exclusive' instead.
 
 If the optional argument PROMPT is non-nil, display that as a prompt.
+If PROMPT is nil or the string \"\", the key sequence/events that led
+to the current command is used as the prompt.
+
 If the optional argument INHERIT-INPUT-METHOD is non-nil and some
 input method is turned on in the current buffer, that input method
 is used for reading a character.
+
 If the optional argument SECONDS is non-nil, it should be a number
 specifying the maximum number of seconds to wait for input.  If no
 input arrives in that time, return nil.  SECONDS may be a
@@ -784,9 +788,13 @@ floating-point value.  */)
 DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
        doc: /* Read an event object from the input stream.
 If the optional argument PROMPT is non-nil, display that as a prompt.
+If PROMPT is nil or the string \"\", the key sequence/events that led
+to the current command is used as the prompt.
+
 If the optional argument INHERIT-INPUT-METHOD is non-nil and some
 input method is turned on in the current buffer, that input method
 is used for reading a character.
+
 If the optional argument SECONDS is non-nil, it should be a number
 specifying the maximum number of seconds to wait for input.  If no
 input arrives in that time, return nil.  SECONDS may be a
@@ -809,9 +817,13 @@ character code: it will fail the `characterp' test.  Use `event-basic-type'
 to recover the character code with the modifiers removed.
 
 If the optional argument PROMPT is non-nil, display that as a prompt.
+If PROMPT is nil or the string \"\", the key sequence/events that led
+to the current command is used as the prompt.
+
 If the optional argument INHERIT-INPUT-METHOD is non-nil and some
 input method is turned on in the current buffer, that input method
 is used for reading a character.
+
 If the optional argument SECONDS is non-nil, it should be a number
 specifying the maximum number of seconds to wait for input.  If no
 input arrives in that time, return nil.  SECONDS may be a