Improve input handling documentation (was Re: Best way to intercept terminal escape sequences?)

[Ryan Johnson]

 On Sat, 04 Sep 2010 15:01:28 +0200 stepnem wrote:
> > >  It would be really nice to have, somewhere in the emacs docs, a diagram
> > >  showing what processing happens to keyboard input, starting from raw bytes 
> > and
> > >  UI events, and tracing them (or their translations) through coding systems,
> > >  input methods, command loop, various keymaps, etc. and showing where in that
> > >  process the different read-* functions intercept that data (and where the
> > >  various unread-*-events reinsert things). A similar diagram for reading and
> > >  writing files would probably also be useful.
> Sounds great indeed!
>
> [...]
> > >  Unfortunately, even after spending so long on this problem I don't think I
> > >  know enough to generate that diagram...
> But perhaps you could come up with some initial version that others
> could continue improving upon?
What format should the diagram take? I don't think I've ever seen ascii 
art, let alone an image, in the emacs docs...

Meanwhile, here's what I have inferred, roughly, about input handling. 
Hopefully those familiar with emacs' guts can correct and improve it:

<-------- keyboard input
keyboard-coding-system
<-------- unread-input-method-events
[Input Method (optional, printable ascii chars only)]
<-------- unread-post-input-method-events
???
<-------- non-keyboard (e.g. mouse) events
<-------- unread-command-events (and unread-command-char)
--------> read-char, read-event
input-decode-map
key-translation-map
[local-]function-key-map
--------> read-key
assorted keymaps (global, local, minor mode, emulation, char/text 
properties, overriding)
--------> read-key-sequence
???
read-number, read-string, etc. (???)

(I have no idea where read-passwd fits in this hierarchy, nor how the 
command loop lines up with things).

NOTE: the description of read-key and input-decode-map makes it sound 
like read-event comes before coding systems, but empirically this is not 
true.

Regards,
Ryan