Input events and (interactive "e")

[Eli Zaretskii <eliz@gnu.org>]

Am I the only one, or do we indeed fail to document that
(interactive "e") is not just for mouse events?

The ELisp manual consistently talks about mouse events only, when it
discusses how to access non-keyboard input events and how to define
functions that are run by these events.  By just reading the manual,
you might think that only mouse events have meaningful parameters in
the event list, and only commands bound to mouse events can access
them using the event-* functions But in fact, it looks like _any_
event generated by the command loop can be bound to a command, and
that command can access the event parameters by treating its argument
as a list, using (interactive "e") to get that argument.  For example,
on Windows I can do this:

 (defun my-lang-change (event)
     ""
   (interactive "e")
   (message "%S" event))
 (global-set-key [language-change] 'my-lang-change)

and the pressing Alt-Shift to switch keyboard layout will show in the
echo area the contents of the event list produced for the
language-change event.

Also, the way to bind such events to commands is not documented at
all, AFAICS.

Is all of this omitted from the documentation on purpose, or should we
add that?

And btw, what is the story behind special-event-map, and why should
events be put on that map?  E.g., is it bad that language-change event
is not on that map?