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

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

Re: Improve input handling documentation

[Chong Yidong]

Ryan Johnson <ryanjohn@ece.cmu.edu> writes:

> What format should the diagram take? I don't think I've ever seen
> ascii art, let alone an image, in the emacs docs...

Info can handle images nowadays, even though we don't currently use it
in the Emacs manuals (see the "Box Diagrams" node in the Lisp manual for
an example of ascii art).  So if you want to take a stab at making a
diagram, png is fine.  It would be good to provide ascii art as a
fallback, though.

Re: Improve input handling documentation

[Ryan Johnson]

  Chong Yidong writes:
> Ryan Johnson writes:
>
>> What format should the diagram take? I don't think I've ever seen
>> ascii art, let alone an image, in the emacs docs...
> Info can handle images nowadays, even though we don't currently use it
> in the Emacs manuals (see the "Box Diagrams" node in the Lisp manual for
> an example of ascii art).  So if you want to take a stab at making a
> diagram, png is fine.  It would be good to provide ascii art as a
> fallback, though.
OK, but let's get the information correct and complete first...

Ryan

Re: Improve input handling documentation

[Stefan Monnier]

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

That looks pretty good and would be a good addition.
One error: key-translation-map comes after [local-]function-key-map.

BTW: is there a good reason why C-x 8 is on key-translation-map rather
than in input-decode-map, function-key-map, or even global-map?

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

input-decode-map doesn't decode coding-systems but things like
escape sequences.


        Stefan "who wants to obsolete key-translation-map"