Clarify what constitutes an event (bug#35238)

* doc/lispref/commands.texi (Input Events): Specify that events are
non-nil and remove vestiges of bug#10190.
* doc/lispref/os.texi (Recording Input): Document optional argument
of recent-keys.
* lisp/subr.el (eventp): Check that the car of conses is non-nil.
* etc/NEWS: Announce it as an incompatible change.
* src/keyboard.c (Frecent_keys): Clarify that returned "events" are
not real events.

2 files changed, 9 insertions, 7 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index cd44c1c87ef..5ea0be2667b 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1047,12 +1047,9 @@ and meaning of input events in detail.
 This function returns non-@code{nil} if @var{object} is an input event
 or event type.
 
-Note that any symbol might be used as an event or an event type.
-@code{eventp} cannot distinguish whether a symbol is intended by Lisp
-code to be used as an event.  Instead, it distinguishes whether the
-symbol has actually been used in an event that has been read as input in
-the current Emacs session.  If a symbol has not yet been so used,
-@code{eventp} returns @code{nil}.
+Note that any non-@code{nil} symbol might be used as an event or an
+event type; @code{eventp} cannot distinguish whether a symbol is
+intended by Lisp code to be used as an event.
 @end defun
 
 @menu
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 59cd5a8fe8a..fef954eb7a3 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2197,7 +2197,7 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
 @subsection Recording Input
 @cindex recording input
 
-@defun recent-keys
+@defun recent-keys &optional include-cmds
 This function returns a vector containing the last 300 input events from
 the keyboard or mouse.  All input events are included, whether or not
 they were used as parts of key sequences.  Thus, you always get the last
@@ -2205,6 +2205,11 @@ they were used as parts of key sequences.  Thus, you always get the last
 (These are excluded because they are less interesting for debugging; it
 should be enough to see the events that invoked the macros.)
 
+If @var{include-cmds} is non-@code{nil}, complete key sequences in the
+result vector are interleaved with pseudo-events of the form
+@code{(nil . @var{COMMAND})}, where @var{COMMAND} is the binding of
+the key sequence (@pxref{Command Overview}).
+
 A call to @code{clear-this-command-keys} (@pxref{Command Loop Info})
 causes this function to return an empty vector immediately afterward.
 @end defun