Function for deleting a key binding in a sparse keymap

Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

It would be good to have a function like this in Emacs:

(defun delete-key-in-sparse-map(sparse-map key)
  "In the sparse keymap SPARSE-MAP remove KEY.
In a sparse keymap if a key is bound to nil that means that
invoking that key find no binding in that map.  If instead there
is no binding at all then the default value if any in that keymap
is used.  This function removes any binding of KEY in the sparse
keymap SPARSE-MAP so that the default value will be used.

If SPARSE-MAP is not a sparse keymap an error is raised."

   ...
  )

However I do not know how to implement this for different formats for 
specifying the key.

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    It would be good to have a function like this in Emacs:

    (defun delete-key-in-sparse-map(sparse-map key)

This function makes sense; I see how it could be used.  Do we really
need it now?

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

>    It would be good to have a function like this in Emacs:
>
>    (defun delete-key-in-sparse-map(sparse-map key)
>
>This function makes sense; I see how it could be used.  Do we really
>need it now?
>  
>
I just wanted to use it ;-)

It is not absolutely necessary, but useful. However if it is simple to 
write for someone knowing the internals I do believe it should be 
written since it might clear some misconceptions and make it more easy 
to understand the meaning of default values in sparse keymaps.

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> It would be good to have a function like this in Emacs:

> (defun delete-key-in-sparse-map(sparse-map key)
>   "In the sparse keymap SPARSE-MAP remove KEY.
> In a sparse keymap if a key is bound to nil that means that
> invoking that key find no binding in that map.  If instead there
> is no binding at all then the default value if any in that keymap
> is used.  This function removes any binding of KEY in the sparse
> keymap SPARSE-MAP so that the default value will be used.

> If SPARSE-MAP is not a sparse keymap an error is raised."

>    ...
>   )

> However I do not know how to implement this for different formats for
> specifying the key.

There is no reason to limit this to sparse keymaps.  AFAIK the problem that
a sparse keymap had all keys bound to nil has been solved.  It seems that
I forgot to update the corresponding documentation.  I've just installed the
patch below.


        Stefan


--- keymaps.texi	22 aoû 2005 10:23:52 -0400	1.68
+++ keymaps.texi	05 déc 2005 14:38:12 -0500	
@@ -158,17 +158,6 @@
 bindings.  A keymap with such a char-table is called a @dfn{full
 keymap}.  Other keymaps are called @dfn{sparse keymaps}.
 
-When a keymap contains a char-table vector, it always defines a
-binding for each character without modifiers.  However, if the binding
-is @code{nil}, it doesn't constitute a definition.  @code{nil} takes
-precedence over a default binding or a binding in the parent keymap.
-So in a full keymap, default bindings are not meaningful for
-characters without modifiers.  They can still apply to characters with
-modifier bits and to non-character events.  A binding of @code{nil}
-does @emph{not} override lower-precedence keymaps; thus, if the local
-map gives a binding of @code{nil}, Emacs uses the binding from the
-global map.
-
 @item @var{string}
 @cindex keymap prompt string
 @cindex overall prompt string
@@ -178,6 +167,13 @@
 use the keymap as a menu.  @xref{Defining Menus}.
 @end table
 
+When the binding is @code{nil}, it doesn't constitute a definition
+but it does take precedence over a default binding or a binding in the
+parent keymap.  On the other hand, a binding of @code{nil} does
+@emph{not} override lower-precedence keymaps; thus, if the local map
+gives a binding of @code{nil}, Emacs uses the binding from the
+global map.
+
 @cindex meta characters lookup
   Keymaps do not directly record bindings for the meta characters.
 Instead, meta characters are regarded for purposes of key lookup as

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    >This function makes sense; I see how it could be used.  Do we really
    >need it now?
    >  
    >
    I just wanted to use it ;-)

Why did you want to use it?

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

>    >This function makes sense; I see how it could be used.  Do we really
>    >need it now?
>    >  
>    >
>    I just wanted to use it ;-)
>
>Why did you want to use it?
>
When starting a minor mode I read some key definitions outside that 
mode. If they have a certain value I define new values for those keys in 
that minor mode.

The next time I enter that minor mode the key definitions outside may 
however be different so I want to remove the key bindings I added when 
exiting the minor mode.

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

>> >This function makes sense; I see how it could be used.  Do we really
>> >need it now?
>> I just wanted to use it ;-)
>> Why did you want to use it?
> When starting a minor mode I read some key definitions outside that mode. If
> they have a certain value I define new values for those keys in that
> minor mode.

> The next time I enter that minor mode the key definitions outside may
> however be different so I want to remove the key bindings I added when
> exiting the minor mode.

Why not set them to nil?


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>
>>The next time I enter that minor mode the key definitions outside may
>>however be different so I want to remove the key bindings I added when
>>exiting the minor mode.
>>    
>>
>
>Why not set them to nil?
>  
>
They should have the default value in those cases. A workaround is of 
course to set them to the default value.

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

>>> The next time I enter that minor mode the key definitions outside may
>>> however be different so I want to remove the key bindings I added when
>>> exiting the minor mode.
>> Why not set them to nil?
> They should have the default value in those cases.  A workaround is of
> course to set them to the default value.

What default value?  Please, make your concrete example concrete.


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>>>>The next time I enter that minor mode the key definitions outside may
>>>>however be different so I want to remove the key bindings I added when
>>>>exiting the minor mode.
>>>>        
>>>>
>>>Why not set them to nil?
>>>      
>>>
>>They should have the default value in those cases.  A workaround is of
>>course to set them to the default value.
>>    
>>
>
>What default value?  Please, make your concrete example concrete.
>
>
>  
>
I feel a bit stupid because this example is not terribly important. 
However this is what I do. There is a minor mode where I use this, 
bw-window-resize-mode. When entering this mode I do:

        (mapc (lambda(key)
                (define-key bw-keymap (vector key) nil))
              help-event-list)

I set the "help keys" to nil so that the help is still available during 
resizing. Those are the keys I want to remove afterwards. The default 
value in the sparse keymap bw-keymap is:

       (define-key bw-keymap [t]  'bw-exit-resize-mode)

Since Richard just decided that this part of the window resizing is new 
and therefore should not go with our next release it is of less 
importance now. However I do believe that it still would be good to add 
that function (see subject line) now.

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> I feel a bit stupid because this example is not terribly important. However
> this is what I do. There is a minor mode where I use this,
> bw-window-resize-mode. When entering this mode I do:

>         (mapc (lambda(key)
>                 (define-key bw-keymap (vector key) nil))
>               help-event-list)

> I set the "help keys" to nil so that the help is still available during
> resizing. Those are the keys I want to remove afterwards. The default value
> in the sparse keymap bw-keymap is:

>        (define-key bw-keymap [t]  'bw-exit-resize-mode)

I see.  Coming from a functional programming background, I'd use anoter
approach based on the idea of reusing the original value rather than using
side-effects to try and coerce it back to the same shape it had originally:

       (defvar bw-keymap
           (let ((map (make-sparse-keymap)))
             (define-key map [t]  'bw-exit-resize-mode)
             map))

then when adding help-event-list bindings:

       (setq bw-keymap (let ((map (make-sparse-keymap)))
                         (set-keymap-parent map bw-keymap)
                         map))
       ;; dolist is more efficient than mapc.
       (dolist (key help-event-list)
         (define-key bw-keymap (vector key) nil))

and when you want to remove those keys, just do

       (setq bw-keymap (keymap-parent bw-keymap))

Of course, you can use variants of it, e.g. introduce a "bw-basic-map"
variable to keep the original map, rather than rely on (keymap-parent
bw-keymap) holding that original map.


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>>I set the "help keys" to nil so that the help is still available during
>>resizing. Those are the keys I want to remove afterwards. The default value
>>in the sparse keymap bw-keymap is:
>>    
>>
>
>  
>
>>       (define-key bw-keymap [t]  'bw-exit-resize-mode)
>>    
>>
>
>I see.  Coming from a functional programming background, I'd use anoter
>approach based on the idea of reusing the original value rather than using
>side-effects to try and coerce it back to the same shape it had originally:
>  
>
Thanks for the idea. That seems much more easy.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>>I set the "help keys" to nil so that the help is still available during
>>resizing. Those are the keys I want to remove afterwards. The default value
>>in the sparse keymap bw-keymap is:
>>    
>>
>
>  
>
>>       (define-key bw-keymap [t]  'bw-exit-resize-mode)
>>    
>>
>
>I see.  Coming from a functional programming background, I'd use anoter
>approach based on the idea of reusing the original value rather than using
>side-effects to try and coerce it back to the same shape it had originally:
>
>       (defvar bw-keymap
>           (let ((map (make-sparse-keymap)))
>             (define-key map [t]  'bw-exit-resize-mode)
>             map))
>
>then when adding help-event-list bindings:
>
>       (setq bw-keymap (let ((map (make-sparse-keymap)))
>                         (set-keymap-parent map bw-keymap)
>                         map))
>       ;; dolist is more efficient than mapc.
>       (dolist (key help-event-list)
>         (define-key bw-keymap (vector key) nil))
>
>and when you want to remove those keys, just do
>
>       (setq bw-keymap (keymap-parent bw-keymap))
>
>Of course, you can use variants of it, e.g. introduce a "bw-basic-map"
>variable to keep the original map, rather than rely on (keymap-parent
>bw-keymap) holding that original map.
>  
>
I wrote to early. For some reason this does not work. It seems like the 
help keys just runs the default function (ie 'bw-exit-resize-mode). Here 
is the output from (describe-variable 'bw-keymap (get-buffer-create 
"*Help*")):

bw-keymap is a variable defined in `c:/emacs-lisp/test/bwcvs.el'.
Its value is shown below.

Documentation:
Keymap used by `bw-window-resize-mode'.

Value:
(keymap
 (f1)
 (help)
 keymap
 (right . bw-mode-resize-right)
 (left . bw-mode-resize-left)
 (down . bw-mode-resize-down)
 (up . bw-mode-resize-up)
 (102 . bw-shrink-windows-horizontally)
 (46 . bw-balance-siblings)
 (43 . bw-balance)
 (t . bw-exit-resize-mode)
 (menu-bar keymap
           (bw "&Resize" keymap
               (balance "Balance Windows" . bw-balance)
               (siblings "Balance Window Siblings" . bw-balance-siblings)
               (shrink "Shrink to Buffers" . bw-shrink-windows-horizontally)
               "second"))
 "Window Resizing")

[back]

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Lennart Borgman wrote:

> Stefan Monnier wrote:
>
>>> I set the "help keys" to nil so that the help is still available during
>>> resizing. Those are the keys I want to remove afterwards. The 
>>> default value
>>> in the sparse keymap bw-keymap is:
>>>   
>>
>>
>>  
>>
>>>       (define-key bw-keymap [t]  'bw-exit-resize-mode)
>>>   
>>
>>
>> I see.  Coming from a functional programming background, I'd use anoter
>> approach based on the idea of reusing the original value rather than 
>> using
>> side-effects to try and coerce it back to the same shape it had 
>> originally:
>>
>>       (defvar bw-keymap
>>           (let ((map (make-sparse-keymap)))
>>             (define-key map [t]  'bw-exit-resize-mode)
>>             map))
>>
>> then when adding help-event-list bindings:
>>
>>       (setq bw-keymap (let ((map (make-sparse-keymap)))
>>                         (set-keymap-parent map bw-keymap)
>>                         map))
>>       ;; dolist is more efficient than mapc.
>>       (dolist (key help-event-list)
>>         (define-key bw-keymap (vector key) nil))
>>
>> and when you want to remove those keys, just do
>>
>>       (setq bw-keymap (keymap-parent bw-keymap))
>>
>> Of course, you can use variants of it, e.g. introduce a "bw-basic-map"
>> variable to keep the original map, rather than rely on (keymap-parent
>> bw-keymap) holding that original map.
>>  
>>
> I wrote too early. For some reason this does not work. It seems like 
> the help keys just runs the default function (ie 
> 'bw-exit-resize-mode). Here is the output from (describe-variable 
> 'bw-keymap (get-buffer-create "*Help*")):

I wrote too early once again. I was adding the old bw-keymap to 
emulation-mode-map-alist, not the new one. When I changed this the above 
procedures work nicely.

Sorry for the unnecessary noise.

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    When starting a minor mode I read some key definitions outside that 
    mode. If they have a certain value I define new values for those keys in 
    that minor mode.

Do you mean that you set them in the minor mode keymap?

    The next time I enter that minor mode the key definitions outside may 
    however be different so I want to remove the key bindings I added when 
    exiting the minor mode.

Why not just construct a new minor mode keymap each time?
You could have a base keymap for the minor mode, which does not change,
and each time you enter the mode you could construct a new keymap
which has that base as its parent.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

>Why not just construct a new minor mode keymap each time?
>You could have a base keymap for the minor mode, which does not change,
>and each time you enter the mode you could construct a new keymap
>which has that base as its parent.
>  
>
Thanks, yes that is what I have done now. Stephan gave essentially the 
same advice.

Re: Function for deleting a key binding in a sparse keymap

[Kim F. Storm]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> I wrote too early once again. I was adding the old bw-keymap to
> emulation-mode-map-alist, not the new one. When I changed this the
> above procedures work nicely.

Why do you use emulation-mode-map-alist ?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Function for deleting a key binding in a sparse keymap

[LENNART BORGMAN]

From: storm@cua.dk (Kim F. Storm)

> Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
> 
> > I wrote too early once again. I was adding the old bw-keymap to
> > emulation-mode-map-alist, not the new one. When I changed this the
> > above procedures work nicely.
> 
> Why do you use emulation-mode-map-alist ?

Because in this case it is a temporary minor mode that exists just during a few keystrokes. I actually put the keymap first in emulation-mode-map-alists to avoid any problem. Nearly all keys except those for using the mode are bound to a function that exits the temporary mode.

Re: Function for deleting a key binding in a sparse keymap

[Kim F. Storm]

LENNART BORGMAN <lennart.borgman.073@student.lu.se> writes:

>> Why do you use emulation-mode-map-alist ?
>
> Because in this case it is a temporary minor mode that exists just
> during a few keystrokes. I actually put the keymap first in
> emulation-mode-map-alists to avoid any problem. Nearly all keys
> except those for using the mode are bound to a function that exits
> the temporary mode.

That is NOT the purpose of emulation-mode-map-alists, and there must
be other ways to accomplish what you want to do.  E.g. (not tested):

  (let (done)
   (while (not done)
     (let* ((ev (read-event))
            (cmd (lookup-key your-keymap ev)))
       (if cmd
           (call-interactively cmd)  ; or just funcall
         (setq done t)
	 (clear-this-command-keys t)
         (setq unread-command-events (cons ev unread-command-events)))))


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Kim F. Storm wrote:

>LENNART BORGMAN <lennart.borgman.073@student.lu.se> writes:
>
>  
>
>>>Why do you use emulation-mode-map-alist ?
>>>      
>>>
>>Because in this case it is a temporary minor mode that exists just
>>during a few keystrokes. I actually put the keymap first in
>>emulation-mode-map-alists to avoid any problem. Nearly all keys
>>except those for using the mode are bound to a function that exits
>>the temporary mode.
>>    
>>
>
>That is NOT the purpose of emulation-mode-map-alists, and there must
>be other ways to accomplish what you want to do.  E.g. (not tested):
>
>  (let (done)
>   (while (not done)
>     (let* ((ev (read-event))
>            (cmd (lookup-key your-keymap ev)))
>       (if cmd
>           (call-interactively cmd)  ; or just funcall
>         (setq done t)
>	 (clear-this-command-keys t)
>         (setq unread-command-events (cons ev unread-command-events)))))
>
It seems more complicated to me, but I might be wrong just because I did 
not think of doing it this way.

I am temporary using the emulation-mode-map-alists just for the purpose 
of putting my keymap first among the keymaps. This was not the reason 
for which emulation-mode-map-alist was invented, but it works for this 
purpose too I believe. I restore emulation-mode-map-alists when the 
temporary mode is exited.

The temporary mode is a mode for resizing windows interactively (see 
http://ourcomments.org/Emacs/DL/elisp/bw-interactive.el). The user will 
do a few keystroke in this mode and then exit it. No keyboard commands 
except those for the mode are allowed. In post-command-hook I also do 
some checks to see if I should exit the temporary mode. (Maybe I should 
do more.)

I am trying to understand what you are saying. Can you please explain 
what problems you see with what I am doing? I do not think that what I 
am doing here can possibly disturb the normal use of 
emulation-mode-map-alists, or can it? If it was not just before the 
release I might propose a new variable holding a temporary keymap like 
in my case, but this is not the time for it. Maybe what I am doing is 
unnecessary complicated?

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

>> > I wrote too early once again. I was adding the old bw-keymap to
>> > emulation-mode-map-alist, not the new one. When I changed this the
>> > above procedures work nicely.
>> 
>> Why do you use emulation-mode-map-alist ?

> Because in this case it is a temporary minor mode that exists just during
> a few keystrokes. I actually put the keymap first in
> emulation-mode-map-alists to avoid any problem.  Nearly all keys except
> those for using the mode are bound to a function that exits the
> temporary mode.

Any reason not to use overriding-(terminal-)local-map like isearch does?


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>>Because in this case it is a temporary minor mode that exists just during
>>a few keystrokes. I actually put the keymap first in
>>emulation-mode-map-alists to avoid any problem.  Nearly all keys except
>>those for using the mode are bound to a function that exits the
>>temporary mode.
>>    
>>
>
>Any reason not to use overriding-(terminal-)local-map like isearch does?
>
>
>        Stefan
>
Me. I did not know about it. Seems like what I want to use.

I found it a bit difficult to remember this. Would not a table like the 
one below be helpful? Is it correct?

*****************************************************************************
How to find the keymap for a given key sequence in a buffer
===========================================================

Go through the list below step by step. As soon as a it (see KeyLookup) 
is found in any keymap you are ready.

*) Look in `special-event-map'.

*) If overriding-terminal-local-map look in this. Then go to GLOBAL.

*) If overriding-local-map look in this. Then go to GLOBAL.

*) Is there a "keymap" property of the text or overlay at point?

*) Look for minor mode keymaps in `emulation-mode-map-alists'.

*) Look for minor mode keymaps in `minor-mode-map-alist'.

*) Is there a `local-map' property of the text or overlay at point?

*) Is there a "local keymap" (those are for major modes)?

GLOBAL) Look in the "global keymap".

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> Go through the list below step by step. As soon as a it (see KeyLookup) is
> found in any keymap you are ready.

That would probably be a good idea.  E.g. you forgot to include
key-translation-map, function-key-map, keyboard-translate-table,
translation-table-for-input, maybe more?


        Stefan

Re: Function for deleting a key binding in a sparse keymap - bug in menus?

[Lennart Borgman]

Lennart Borgman wrote:

> Stefan Monnier wrote:
>
>>> Because in this case it is a temporary minor mode that exists just 
>>> during
>>> a few keystrokes. I actually put the keymap first in
>>> emulation-mode-map-alists to avoid any problem.  Nearly all keys except
>>> those for using the mode are bound to a function that exits the
>>> temporary mode.
>>>   
>>
>>
>> Any reason not to use overriding-(terminal-)local-map like isearch does?
>>
>>
>>        Stefan
>>
> Me. I did not know about it. Seems like what I want to use.

I did change to use `overriding-terminal-local-map'. However there are 
some side effects of this and maybe a bug.

Since the minor and major mode maps are overriden they disappear from 
the menus too. That is rather ok. But the keyboard bindings in 
overriding-terminal-local-map is not reflected in the menu that is set 
up by the keymap. That looks like a bug to me.

More precisely: The menu setup by the keymap looks ok except that the 
keyboard bindings are not mentioned in the menus as they use to be.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>>Go through the list below step by step. As soon as a it (see KeyLookup) is
>>found in any keymap you are ready.
>>    
>>
>
>That would probably be a good idea.  E.g. you forgot to include
>key-translation-map, function-key-map, keyboard-translate-table,
>translation-table-for-input, maybe more?
>
>
>        Stefan
>  
>
This was rather hairy. Is the table below correct?


*****************************************************************************
How to find the keymap for a given key sequence in a buffer
===========================================================

Go through the list below step by step. As soon as a hit is found in
any keymap (see KeyLookup) you are ready.

*) First apply `extra-keyboard-modifiers' mask to each keyboard
   character read.

*) Each character read from the keyboard may be translated according
   to `keyboard-translate-table'.

*) Characters that are self-inserting are translated according to
   `translation-table-for-input'. If a character is self-inserting then
   you are ready.


FIRST-MAP) Look in `special-event-map'.

*) If overriding-terminal-local-map look in this. Then go to GLOBAL.

*) If overriding-local-map look in this. Then go to GLOBAL.

*) Is there a "keymap" property of the text or overlay at point?

*) Look for minor mode keymaps in `emulation-mode-map-alists'.

*) Look for minor mode keymaps in `minor-mode-map-alist'.

*) Is there a `local-map' property of the text or overlay at point?

*) Is there a "local keymap" (those are for major modes)?

GLOBAL) Look in the "global keymap".

*) If it is an ASCII function key sequences then look in
   function-key-map. This map transforms to Emacs key sequences.

*) The possibly transformed sequence after applying `function-key-map'
   is now handled to `key-translation-map' which works the same way.

*) If any transformation was made by `function-key-map' or
   `key-translation-map' then take the new sequence and go back to
   FIRST-MAP.

Re: Function for deleting a key binding in a sparse keymap

[Kim F. Storm]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> This was rather hairy. Is the table below correct?

There are additional keymaps used in the minibuffer... 
Notably, minibuffer-local-map.

Also notice value of meta-prefix-char.

There is also minor-mode-overriding-map-alist, consulted between
emulation-mode-map-alists and minor-mode-map-alist.  Note that if a
variable has an entry in Vminor_mode_overriding_map_alist, and also an
entry in Vminor_mode_map_alist, ignore the latter.

You should mention that the "current global map" may not be the
`global-map', since function "use-global-map" can change the current
global map.

You may also want to mention function current-active-maps.

Finally, you could mention that if the result of the first pass
through these keymaps is a symbol, a second pass is made to find a
possible command remapping (looking for a binding [remap SYMBOL].

Likewise, if the result of the mapping is a string, that string is
used as a keyboard macro, i.e. each character in the string is again
passed through the keymaps.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    *****************************************************************************
    How to find the keymap for a given key sequence in a buffer
    ===========================================================

It would be good to put this list into the Active Keymaps node
in lispref/keymaps.texi.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

>    *****************************************************************************
>    How to find the keymap for a given key sequence in a buffer
>    ===========================================================
>
>It would be good to put this list into the Active Keymaps node
>in lispref/keymaps.texi.
>  
>
I am glad you appreciate it. However there was a bit more to add. I got 
some tips from Kim and made a new version. There is a question in this 
about when the keymap entry is a keymap.

*********************************************************************************

*****************************************************************************
How to find the keymap for a given key sequence in a buffer
===========================================================

Go through the list below step by step. As soon as a hit is found in
any keymap (see KeyLookup) you normally are ready. However if the
keymap entry is a variable symbol or a string then you must restart
with the variable symbol value or the string from FIRST-MAP.

The keymap entry could also be a keymap. In that case the next event
is looked up in that keymap. (But what happens if there is no hit
there, I can not find any documentation on this???)

Note: When you finally find a function symbol through this process you
   must also check for command remapping. This just replaces the
   function symbol with another. It is not recursive.

*) First apply `extra-keyboard-modifiers' mask to each keyboard
   character read.

*) Each character read from the keyboard may be translated according
   to `keyboard-translate-table'.

*) Characters that are self-inserting are translated according to
   `translation-table-for-input'. If a character is self-inserting then
   you are ready.

*) Translate meta characters according to `meta-prefix-char' to a two
   character sequence.

FIRST-MAP) Look in `special-event-map'.

*) If using `read-from-minibuffer' (directly or indirectly) then look
   in the keymap given as parameter then look in this. Otherwise look
   in `minibuffer-local-map'.

*) If using `read-no-blanks-input' to read from minibuffer then look
   in `minibuffer-local-ns-map' first and then `minibuffer-local-map'.

*) If overriding-terminal-local-map look in this. Then go to GLOBAL.

*) If overriding-local-map look in this. Then go to GLOBAL.

*) Is there a "keymap" property of the text or overlay at point?

*) Look for minor mode keymaps in `emulation-mode-map-alists'.

*) Look for minor mode keymaps in `minor-mode-overriding-map-alist'

*) Look for minor mode keymaps in `minor-mode-map-alist'.

*) Is there a `local-map' property of the text or overlay at point?

*) Is there a "local keymap" (those are for major modes)?

GLOBAL) Look in the "current global keymap". (This is returned by
   `current-global-map' and may be different from `global-map', see
   `use-global-map'.)

*) If it is an ASCII function key sequences then look in
   function-key-map. This map transforms to Emacs key sequences.

*) The possibly transformed sequence after applying `function-key-map'
   is now handled to `key-translation-map' which works the same way.

*) If any transformation was made by `function-key-map' or
   `key-translation-map' then take the new sequence and go back to
   FIRST-MAP.

Note: You may also find the function `current-active-maps' useful.

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    Go through the list below step by step. As soon as a hit is found in
    any keymap (see KeyLookup) you normally are ready.

Saying "you" is a peculiar way to word it--it is Enacs that does these
things.  Could you rewrite this in terms of what Emacs does?

Also, could you (or someone) turn it into Texinfo?

Re: Function for deleting a key binding in a sparse keymap

[Kim F. Storm]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> I am glad you appreciate it. However there was a bit more to add. I
> got some tips from Kim and made a new version. There is a question in
> this about when the keymap entry is a keymap.

This seems to be quite accurate now... but there is one thing I
don't understand...

> *) Characters that are self-inserting are translated according to
>    `translation-table-for-input'. If a character is self-inserting then
>    you are ready.

How do you know that a character is self-inserting at this stage?
You only find that out by looking it up in the keymaps, and you
haven't got to that yet at this stage (unless this somehow is
the second pass?)



May I suggest that you add an example of which part of emacs currently
uses each of these methods, e.g.
>
> *) Translate meta characters according to `meta-prefix-char' to a two
>    character sequence.

For example, this maps M-x into ESC x.

> FIRST-MAP) Look in `special-event-map'.

For example, this is where the delete-frame event is handled.

> *) If overriding-terminal-local-map look in this. Then go to GLOBAL.

For example, this is how the C-u prefix is handled.

> *) Look for minor mode keymaps in `emulation-mode-map-alists'.

For example, this is used by cua-mode and viper.

etc.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

[-- Attachment #1: Type: text/plain, Size: 1224 bytes --]

Richard M. Stallman wrote:

>    Go through the list below step by step. As soon as a hit is found in
>    any keymap (see KeyLookup) you normally are ready.
>
>Saying "you" is a peculiar way to word it--it is Enacs that does these
>things.  Could you rewrite this in terms of what Emacs does?
>
>Also, could you (or someone) turn it into Texinfo?
>  
>
I have attached a new version. This is in Texinfo format and written to 
be placed at the bottom of

   @node Active Keymaps

in keymaps.texi.


*** Some questions:

- Could someone please tell what is happening when key lookup finds a 
keymap entry? If no hit is found in the new keymap which keymap is then 
the next?

- Maybe the node should have an entry in the index?

- I do not understand why @emph{TERM} gives a result looking like _TERM_ 
after running "make info". It is instead converted to underlined blue 
text when I test with texinfo-format-region. (This is on w32. A 
difference might be that texinfo-format-region is using Cygwins makeinfo 
and "make info" is using makeinfo from GnuWin32. Both are version 4.8.)

- How is fill supposed to work? It seems like the texinfo makeup is not 
excluded so to say when doing a fill-paragraph. Or am I mistaken?

[-- Attachment #2: finding-keymap.texi --]
[-- Type: text/plain, Size: 3067 bytes --]


@subsection Finding the keymap to use

The list below describes step by step how Emacs finds a keymap from a
given key sequence. As soon as a hit is found in any keymap (see
@ref{Key Lookup}) then if the keymap entry is a function the search is
over. However if the keymap entry is a variable symbol or a string
then Emacs restarts with the variable symbol value or the string from
FIRST-MAP.

The keymap entry could also be a keymap. In that case the next event
is looked up in that keymap. (But what happens if there is no hit
there, I can not find any documentation on this???)

@noindent
@emph{Note 1:} When Emacs finally find a function symbol through this
process it also checks for command remapping. This just replaces the
function symbol with another. It is not recursive.

@noindent
@emph{Note 2:} You may find the function @code{current-active-maps}
useful when looking into this.

@table @asis
@item START-HERE:
First apply @code{extra-keyboard-modifiers} mask to each keyboard
character read.
@end table

@itemize @bullet
@item
Each character read from the keyboard may be translated according to
@code{keyboard-translate-table}.

@item
Characters that are self-inserting are translated according to
@code{translation-table-for-input}. If a character is self-inserting
then stop here.

@item
Translate meta characters according to @code{meta-prefix-char} to a
two character sequence.
@end itemize

@table @asis
@item FIRST-MAP:
Look in @code{special-event-map}.
@end table

@itemize @bullet
@item
If using @code{read-from-minibuffer} (directly or indirectly) then
look in the keymap given as parameter then look in this. Otherwise
look in @code{minibuffer-local-map}.

@item
If using @code{read-no-blanks-input} to read from minibuffer then look
in @code{minibuffer-local-ns-map} first and then
@code{minibuffer-local-map}.

@item
If overriding-terminal-local-map look in this. Then go to GLOBAL.

@item
If overriding-local-map look in this. Then go to GLOBAL.

@item
Is there a "keymap" property of the text or overlay at point?

@item
Look for minor mode keymaps in @code{emulation-mode-map-alists}.

@item
Look for minor mode keymaps in @code{minor-mode-overriding-map-alist}

@item
Look for minor mode keymaps in @code{minor-mode-map-alist}.

@item
Is there a @code{local-map} property of the text or overlay at point?

@item
Is there a "local keymap" (those are for major modes)?
@end itemize

@table @asis
@item GLOBAL:
Look in the "current global keymap". (This is returned by
@code{current-global-map} and may be different from @code{global-map},
see @code{use-global-map}.)
@end table

@itemize @bullet
@item
If it is an ASCII function key sequences then look in
@code{function-key-map}. This map transforms to Emacs key sequences.

@item
The possibly transformed sequence after applying
@code{function-key-map} is now handled to @code{key-translation-map}
which works the same way.

@item
If any transformation was made by @code{function-key-map} or
@code{key-translation-map} then take the new sequence and go back to
FIRST-MAP.
@end itemize

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Kim F. Storm wrote:

>This seems to be quite accurate now... but there is one thing I
>don't understand...
>  
>
I am glad someone is checking this ...   :-)

>  
>
>>*) Characters that are self-inserting are translated according to
>>   `translation-table-for-input'. If a character is self-inserting then
>>   you are ready.
>>    
>>
>
>How do you know that a character is self-inserting at this stage?
>You only find that out by looking it up in the keymaps, and you
>haven't got to that yet at this stage (unless this somehow is
>the second pass?)
>  
>
Some kind of magic thinking I guess ;-)  -- it is funny how you 
sometimes can fool yourself into thinking you know something. Maybe 
because there are too many unknown things at the moment. You are right 
of course. I have moved it to a note.

>
>
>May I suggest that you add an example of which part of emacs currently
>uses each of these methods, e.g.
>  
>
I have taken your examples. Before I send a new version: How do I make a 
cross-reference in Texinfo to cua-mode and viper here?

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

[-- Attachment #1: Type: text/plain, Size: 453 bytes --]

Lennart Borgman wrote:

> Kim F. Storm wrote:
>
>> May I suggest that you add an example of which part of emacs currently
>> uses each of these methods, e.g.
>>  
>>
> I have taken your examples. Before I send a new version: How do I make 
> a cross-reference in Texinfo to cua-mode and viper here?

I have attached my new version here. I realize there are more things 
that should be converted from @code to @ref, but I need some help to 
finish that.

[-- Attachment #2: finding-keymap.texi --]
[-- Type: text/plain, Size: 3491 bytes --]


@subsection Finding the keymap to use

The list below describes step by step how Emacs finds a keymap from a
given key sequence. As soon as a hit is found in any keymap (see
@ref{Key Lookup}) then if the keymap entry is a function the search is
over. However if the keymap entry is a variable symbol or a string
then Emacs restarts with the variable symbol value or the string from
FIRST-MAP.

The keymap entry could also be a keymap. In that case the next event
is looked up in that keymap. (But what happens if there is no hit
there, I can not find any documentation on this???)

@noindent
@emph{Note 1:} When Emacs finally find a function symbol through this
process it also checks for command remapping. This just replaces the
function symbol with another. It is not recursive.

@noindent
@emph{Note 2:} Characters that are bound to @code{self-insert-command}
are translated according to @code{translation-table-for-input} before
insertion.

@noindent
@emph{Note 3:} You may find the function @code{current-active-maps}
useful when looking into this.

@table @asis
@item START-HERE:
First apply @code{extra-keyboard-modifiers} mask to each keyboard
character read.
@end table

@itemize @bullet
@item
Each character read from the keyboard may be translated according to
@code{keyboard-translate-table}.

@item
Translate meta characters according to @code{meta-prefix-char} to a
two character sequence.

@example
For example, this normally maps M-x into ESC x.
@end example
@end itemize

@table @asis
@item FIRST-MAP:
Look in @code{special-event-map}.

@example
For example, this is where the @code{delete-frame} event is handled.
@end example
@end table

@itemize @bullet
@item
If using @code{read-from-minibuffer} (directly or indirectly) then
look in the keymap given as parameter then look in this. Otherwise
look in @code{minibuffer-local-map}.

@item
If using @code{read-no-blanks-input} to read from minibuffer then look
in @code{minibuffer-local-ns-map} first and then
@code{minibuffer-local-map}.

@item
If overriding-terminal-local-map look in this. Then go to GLOBAL.

@example
This is for example used by @code{Incremental Search}.
@end example

@item
If overriding-local-map look in this. Then go to GLOBAL.

@item
Is there a "keymap" property of the text or overlay at point?

@item
Look for minor mode keymaps in @code{emulation-mode-map-alists}.

@example
For example, this is used by @code{cua-mode} and @code{viper}.
@end example

@item
Look for minor mode keymaps in @code{minor-mode-overriding-map-alist}

@item
Look for minor mode keymaps in @code{minor-mode-map-alist}.

@item
Is there a @code{local-map} property of the text or overlay at point?

@item
Is there a "local keymap" (those are for major modes)?
@end itemize

@table @asis
@item GLOBAL:
Look in the "current global keymap". (This is returned by
@code{current-global-map} and may be different from @code{global-map},
see @code{use-global-map}.)
@end table

@itemize @bullet
@item
If it is an ASCII function key sequences then look in
@code{function-key-map}. This map transforms to Emacs key sequences.

@example
This is for example used when running Emacs on a VT-100 terminal.
@end example

@item
The possibly transformed sequence after applying
@code{function-key-map} is now handled to @code{key-translation-map}
which works the same way.

@item
If any transformation was made by @code{function-key-map} or
@code{key-translation-map} then take the new sequence and go back to
FIRST-MAP.
@end itemize

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> @item
> Characters that are self-inserting are translated according to
> @code{translation-table-for-input}. If a character is self-inserting
> then stop here.

As Kim noticed, this is wrong: this translation is applied at the very end
by the "self-insertion" function (and only if the function was correctly
fixed to take this table into account).

I suggested to move it basically to where you placed it (which implies it's
used regardless of whether it'll be self-inserting or not), but Richard
rejected it.

> @itemize @bullet
> @item
> If using @code{read-from-minibuffer} (directly or indirectly) then
> look in the keymap given as parameter then look in this. Otherwise
> look in @code{minibuffer-local-map}.

Actually, minibuffer-local-map is nothing more than the keymap used as "local
keymap" in the minibuffers.  So it shouldn't be in this list.

> @item
> If using @code{read-no-blanks-input} to read from minibuffer then look
> in @code{minibuffer-local-ns-map} first and then
> @code{minibuffer-local-map}.

Same here.  All the minibuffer-local-*-map are just various keymaps that are
used as "local keymap" in various circumstances.  So they're basically like
major mode maps for special major modes which are only used in the minibuffer.

> @item
> Is there a @code{local-map} property of the text or overlay at point?
> @item
> Is there a "local keymap" (those are for major modes)?
> @end itemize

Actually the above two are mutually exclusive: if a `local-map' property is
found, it's used instead of the local keymap.

> @itemize @bullet
> @item
> If it is an ASCII function key sequences then look in
> @code{function-key-map}. This map transforms to Emacs key sequences.

This also applies to non-ASCII sequences.  But it only applies if no binding
was found yet.

> @item
> The possibly transformed sequence after applying
> @code{function-key-map} is now handled to @code{key-translation-map}
> which works the same way.

Actually key-translation-map is different because it applies even if the
untranslated sequence already had a binding.  Also those mappings are not
repeated.


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

[-- Attachment #1: Type: text/plain, Size: 1152 bytes --]

Stefan Monnier wrote:

>As Kim noticed, this is wrong: this translation is applied at the very end
>by the "self-insertion" function (and only if the function was correctly
>fixed to take this table into account).
>  
>
Thanks, I have already moved it.

>Actually, minibuffer-local-map is nothing more than the keymap used as "local
>keymap" in the minibuffers.  So it shouldn't be in this list.
>  
>
Then maybe it should be placed in the item about "local keymap"?

>Actually the above two are mutually exclusive: if a `local-map' property is
>found, it's used instead of the local keymap.
>  
>
Thanks, I have change that.

>This also applies to non-ASCII sequences.  But it only applies if no binding
>was found yet.
>  
>
Ok, I have changed that. But then I think the doc string for 
function-key-map is wrong.

>Actually key-translation-map is different because it applies even if the
>untranslated sequence already had a binding.  Also those mappings are not
>repeated.
>  
>
I did not notice that it could override keymaps. Would it be correct to 
place this item as the FIRST-MAP in the list, before special-event-map? 
I placed it there now.

[-- Attachment #2: finding-keymap.texi --]
[-- Type: text/plain, Size: 3623 bytes --]


@subsection Finding the keymap to use

The list below describes step by step how Emacs finds a keymap from a
given key sequence. As soon as a hit is found in any keymap (see
@ref{Key Lookup}) then if the keymap entry is a function the search is
over. However if the keymap entry is a variable symbol or a string
then Emacs restarts with the variable symbol value or the string from
FIRST-MAP.

The keymap entry could also be a keymap. In that case the next event
is looked up in that keymap. (But what happens if there is no hit
there, I can not find any documentation on this???)

@noindent
@emph{Note 1:} When Emacs finally find a function symbol through this
process it also checks for command remapping. This just replaces the
function symbol with another. It is not recursive.

@noindent
@emph{Note 2:} Characters that are bound to @code{self-insert-command}
are translated according to @code{translation-table-for-input} before
insertion.

@noindent
@emph{Note 3:} You may find the function @code{current-active-maps}
useful when looking into this.

@table @asis
@item START-HERE:
First apply @code{extra-keyboard-modifiers} mask to each keyboard
character read.
@end table

@itemize @bullet
@item
Each character read from the keyboard may be translated according to
@code{keyboard-translate-table}.

@item
Translate meta characters according to @code{meta-prefix-char} to a
two character sequence.

@example
For example, this normally maps M-x into ESC x.
@end example
@end itemize

@table @asis
@item FIRST-MAP:
The key sequence is first searched for in @code{key-translation-map}
which transforms it to a new key sequences if there is a hit.
@end table

@itemize @bullet
@item
Look in @code{special-event-map}.

@example
For example, this is where the @code{delete-frame} event is handled.
@end example

@item
If overriding-terminal-local-map look in this. Then go to GLOBAL.

@example
This is for example used by @code{Incremental Search}.
@end example

@item
If overriding-local-map look in this. Then go to GLOBAL.

@item
Is there a "keymap" property of the text or overlay at point?

@item
Look for minor mode keymaps in @code{emulation-mode-map-alists}.

@example
For example, this is used by @code{cua-mode} and @code{viper}.
@end example

@item
Look for minor mode keymaps in @code{minor-mode-overriding-map-alist}

@item
Look for minor mode keymaps in @code{minor-mode-map-alist}.

@item
Is there a @code{local-map} property of the text or overlay at point?
Otherwise is there a "local keymap" (those are for major modes)?  In
the minibuffer some special maps are used.  If using
@code{read-from-minibuffer} (directly or indirectly) then look in the
keymap given as parameter then look in this. Otherwise look in
@code{minibuffer-local-map}.  If using @code{read-no-blanks-input} to
read from minibuffer then look in @code{minibuffer-local-ns-map} first
and then @code{minibuffer-local-map}.
@end itemize

@table @asis
@item GLOBAL:
Look in the "current global keymap". (This is returned by
@code{current-global-map} and may be different from @code{global-map},
see @code{use-global-map}.)
@end table

@itemize @bullet
@item
Look in @code{function-key-map}. This map transforms to a new key
sequences.

@example
This is for example used when running Emacs on a VT-100 terminal.
Such terminal sends ASCII key sequences for function keys which are
translated into a more general format Emacs uses.  For example the
sequence @code{ESC O P} is translated to [f1].
@end example


@item
If any transformation was made by @code{function-key-map} then take
the new sequence and go back to FIRST-MAP.
@end itemize

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> Ok, I have changed that. But then I think the doc string for
> function-key-map is wrong.

I guess so, yes.

>> Actually key-translation-map is different because it applies even if the
>> untranslated sequence already had a binding.  Also those mappings are not
>> repeated.
> I did not notice that it could override keymaps. Would it be correct to
> place this item as the FIRST-MAP in the list, before special-event-map?

I guess so, but note that it's applied after function-key-map (weird, huh?)
(function-key-map basically peaks ahead to try and see if the key will
be found in the keymaps or not).


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

For proper style, please write two spaces between sentences.

    @emph{Note 1:} When Emacs finally find a function symbol through this
    process it also checks for command remapping. This just replaces the
    function symbol with another. It is not recursive.

That needs a cross reference about command remapping.  Various
other cross references are needed too.

    @table @asis
    @item START-HERE:
    First apply @code{extra-keyboard-modifiers} mask to each keyboard
    character read.
    @end table

This is very peculiar Texinfo usage.  This item should be part of the
@itemize.

Please find a different way to represent these labels.  One way would
be to put the label text _inside_ the items of the @itemize.

But even better, don't use labels!  Gotos are not a clear way to
express a program.  It would be clearer to try to express this as

   (if overriding-terminal-local-map
       (look-in overriding-terminal-local-map)
     (if overriding-local-map
         (look-in overriding-local-map)
       (look-in (get-char-property (point) 'keymap))
       etc.))

which involves no labels or gotos.

Nested @itemize constructs might provide a way to do this.  You could
use @enumerate for the three alternatives, with another @itemize
inside the third one.  (See how it looks in TeX output.)

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    The list below describes step by step how Emacs finds a keymap from a
    given key sequence. As soon as a hit is found in any keymap (see
    @ref{Key Lookup}) then if the keymap entry is a function the search is

You write (@pxref{Key Lookup}).
I suggest you reread the Texinfo manual section on xrefs.

    @emph{Note 1:}

That produces Info output that looks like an xref,
so don't do that.

    @item
    If using @code{read-from-minibuffer} (directly or indirectly) then
    look in the keymap given as parameter then look in this. Otherwise
    look in @code{minibuffer-local-map}.

    @item
    If using @code{read-no-blanks-input} to read from minibuffer then look
    in @code{minibuffer-local-ns-map} first and then
    @code{minibuffer-local-map}.

These items can be deleted.  Those maps are simply used
as local maps for the buffer.

    @item
    If overriding-terminal-local-map look in this.

You need @code there.

    @example
    This is for example used by @code{Incremental Search}.
    @end example

`@example' is used for examples of code or input.
It is incorrect to use @example here.

    @item
    Is there a "keymap" property of the text or overlay at point?

This question fails to say what to _do_.

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    >This also applies to non-ASCII sequences.  But it only applies if no binding
    >was found yet.
    >  
    >
    Ok, I have changed that. But then I think the doc string for 
    function-key-map is wrong.

I will clarify the doc string.

But function-key-map does not belong in this table.  It is used as
part of _reading_ key sequences, not as part of _lookup_.
Likewise for key-translation-map.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Richard M. Stallman wrote:

>But even better, don't use labels!  Gotos are not a clear way to
>express a program.  It would be clearer to try to express this as
>
>   (if overriding-terminal-local-map
>       (look-in overriding-terminal-local-map)
>     (if overriding-local-map
>         (look-in overriding-local-map)
>       (look-in (get-char-property (point) 'keymap))
>       etc.))
>
>which involves no labels or gotos.
>  
>
I a little bit doubt it is readable outside a buffer in Emacs-Lisp mode. 
Here is a version I have made to see how it looks:


(unless (FIND-IN special-event-map)
  (if overriding-terminal-local-map
      (FIND-IN overriding-terminal-local-map)
    (if overriding-local-map
        (FIND-IN overriding-local-map)
      (unless (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
        (unless (FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
          (unless (FIND-IN-ANY minor-mode-overriding-map-alist)
            (unless (FIND-IN-ANY minor-mode-map-alist)
              (unless (FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
                (FIND-IN (current-local-map))))))))))
(unless FOUND
  (FIND-IN (current-global-map)))
       

I think it would need some explanation too.

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

> (unless (FIND-IN special-event-map)
>   (if overriding-terminal-local-map
>       (FIND-IN overriding-terminal-local-map)
>     (if overriding-local-map
>         (FIND-IN overriding-local-map)
>       (unless (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
>         (unless (FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
>           (unless (FIND-IN-ANY minor-mode-overriding-map-alist)
>             (unless (FIND-IN-ANY minor-mode-map-alist)
>               (unless (FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
>                 (FIND-IN (current-local-map))))))))))
> (unless FOUND
>   (FIND-IN (current-global-map)))

How 'bout

(or (FIND-IN special-event-map)
    (if overriding-terminal-local-map
        (FIND-IN overriding-terminal-local-map)
      (if overriding-local-map
          (FIND-IN overriding-local-map)
        (or (FIND-IN (get-text-property (point) 'keymap))
            (FIND-IN-ANY emulation-mode-map-alists)
            (FIND-IN-ANY minor-mode-overriding-map-alist)
            (FIND-IN-ANY minor-mode-map-alist)
            (FIND-IN (or (get-text-property (point) 'local-map)
                         (current-local-map))))))
    (FIND-IN (current-global-map)))

BTW, the special-event-map should be moved elsewhere, since it's applied not
to event-sequences but to single events, during read-key-sequence (IIRC).
I.e. just like function-key-map and key-translation-map, it's
used differently.


        Stefan


PS: I wish the actual code were as clear as the above ;-)

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

If we want to write it in pseudo-Lisp, this is much
more Lisp-like yet with much less nesting.

    (or (FIND-IN special-event-map)
	(if overriding-terminal-local-map
	    (FIND-IN overriding-terminal-local-map)
	  (if overriding-local-map
	      (FIND-IN overriding-local-map)
	    (or (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
		(FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
		(FIND-IN-ANY minor-mode-overriding-map-alist)
		(FIND-IN-ANY minor-mode-map-alist)
		(FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
		(FIND-IN (current-local-map)))))
        (FIND-IN (current-global-map)))

However, we're writing English, not Polish.  That's not necessary the
best way to structure it in the manual.  However, it might give ideas
for how to do so in the manual.

This pseudo-Lisp structure might give better ideas, since it has fewer
levels of nesting of control constructs.

    (or (FIND-IN special-event-map)
	(cond (overriding-terminal-local-map
	       (FIND-IN overriding-terminal-local-map))
	      (overriding-local-map
	       (FIND-IN overriding-local-map))
	      (t
	       (or (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
		   (FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
		   (FIND-IN-ANY minor-mode-overriding-map-alist)
		   (FIND-IN-ANY minor-mode-map-alist)
		   (FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
		   (FIND-IN (current-local-map)))))
        (FIND-IN (current-global-map)))

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

Stefan Monnier wrote:

>BTW, the special-event-map should be moved elsewhere, since it's applied not
>to event-sequences but to single events, during read-key-sequence (IIRC).
>I.e. just like function-key-map and key-translation-map, it's
>used differently.
>  
>
Without looking at the code I would then guess it is applied after 
extra-keyboard-modifiers, keyboard-translate-table and meta-prefix-char, 
but before function-key-map. Could you perhaps tell exactly where since 
you seem to have looked in the code?

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

[-- Attachment #1: Type: text/plain, Size: 1426 bytes --]

Richard M. Stallman wrote:

>If we want to write it in pseudo-Lisp, this is much
>more Lisp-like yet with much less nesting.
>
>    (or (FIND-IN special-event-map)
>	(if overriding-terminal-local-map
>	    (FIND-IN overriding-terminal-local-map)
>	  (if overriding-local-map
>	      (FIND-IN overriding-local-map)
>	    (or (FIND-IN (KEYMAP-PROPERTY-AT-POINT))
>		(FIND-IN-ANY EMULATION-MODE-MAP-ALISTS)
>		(FIND-IN-ANY minor-mode-overriding-map-alist)
>		(FIND-IN-ANY minor-mode-map-alist)
>		(FIND-IN (LOCAL-MAP-PROPERTY-AT-POINT))
>		(FIND-IN (current-local-map)))))
>        (FIND-IN (current-global-map)))
>
>  
>
I have taken your and Stefan´s suggestions and merged it with what I had 
previously. It looks better than I expected. I have in this case left 
out the examples that Kim wanted because I think they will clutter the 
pseudo-Lisp structure. Maybe these examples fit better in the longer 
descriptions of the functions and variables in Info?

We have slightly different ideas of what this subnode should be for. I 
believe it serves its main purpose of finding the keymap with a little 
bit broader picture so I have written a suggestion along that line. I 
renamed the header to "Finding the keymap and its entry to use" to 
reflect this a bit.

I have attached a the new version. Please try to answer the two 
questions in there that I do not know the answer of myself!


[-- Attachment #2: finding-keymap.texi --]
[-- Type: text/plain, Size: 2671 bytes --]


@subsection Finding the keymap and its entry to use

First the keyboard input events must be translated (@pxref{Translating
Input}).  This is done in two steps, first character translation and
then key sequence translation:

@itemize @bullet
@item
The character translation is done in three sequential steps using
@code{extra-keyboard-modifiers}, @code{keyboard-translate-table} and
@code{meta-prefix-char}.

@item
Key sequence translation: Keyboard event at this stage that has not
yet been mapped to a keymap are kept in a queue.  The subsequences in
this queue are checked and may be transformed by the tables in
@code{function-key-map} and @code{key-translation-map}.  Note that
this requires a look ahead in the keymaps in the order described
below.
@end itemize

(@strong{special-even-map is missing above yet!!!})

After the translations above Emacs looks in the active keymaps for a
match.  As soon as a match is found (see @pxref{Key Lookup}) then if
the keymap entry is a function the search is over.  However if the
keymap entry is a variable symbol or a string then Emacs replaces the
input key sequences with the variable symbol value or the string and
restarts searching in the active keymaps.

The keymap entry could also be a keymap.  In that case the next event
is looked up in that keymap.  

(@strong{But what happens if there is no hit there, I can not find any
documentation on this???})

Here is a Pseudo-Lisp description of the order in which the active keymaps are searched:

@lisp
(or (if overriding-terminal-local-map
        (FIND-IN overriding-terminal-local-map)
      (if overriding-local-map
          (FIND-IN overriding-local-map)
        (or (FIND-IN (get-text-property (point) 'keymap))
            (FIND-IN-ANY emulation-mode-map-alists)
            (FIND-IN-ANY minor-mode-overriding-map-alist)
            (FIND-IN-ANY minor-mode-map-alist)
            (FIND-IN (get-text-property (point) 'local-map))
            (FIND-IN (current-local-map)))))
    (FIND-IN (current-global-map)))
@end lisp

@noindent
The FIND-IN and FIND-IN-ANY are pseudo functions that searches in one
keymap respectively an alist of keymaps.

@noindent
@strong{Remark 1:} When Emacs finally find a function symbol through
this process it also checks for command remapping (@pxref{Remapping
Commands}).  This just replaces the function symbol with another.  It
is not recursive.

@noindent
@strong{Remark 2:} Characters that are bound to
@code{self-insert-command} are translated according to
@code{translation-table-for-input} before insertion.

@noindent
@strong{Remark 3:} You may find the function
@code{current-active-maps} useful when looking into this.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Function for deleting a key binding in a sparse keymap

[Stefan Monnier]

>> BTW, the special-event-map should be moved elsewhere, since it's applied not
>> to event-sequences but to single events, during read-key-sequence (IIRC).
>> I.e. just like function-key-map and key-translation-map, it's
>> used differently.
>> 
> Without looking at the code I would then guess it is applied after
> extra-keyboard-modifiers, keyboard-translate-table and meta-prefix-char, but
> before function-key-map.

That sounds right.


        Stefan

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    First the keyboard input events must be translated (@pxref{Translating
    Input}).  This is done in two steps, first character translation and
    then key sequence translation:

I don't think that belongs in this node.  These things should be
documented elsewhere.  What is needed here is a brief statement that
key lookup is separate from key input, with mention of
read-key-sequence, and an xref.

    The keymap entry could also be a keymap.  In that case the next event
    is looked up in that keymap.  

    (@strong{But what happens if there is no hit there, I can not find any
    documentation on this???})

The question is not clear.  "No hit there"--where is "there"?

    @lisp
    (or (if overriding-terminal-local-map
	    (FIND-IN overriding-terminal-local-map)
	  (if overriding-local-map
	      (FIND-IN overriding-local-map)
	    (or (FIND-IN (get-text-property (point) 'keymap))
		(FIND-IN-ANY emulation-mode-map-alists)
		(FIND-IN-ANY minor-mode-overriding-map-alist)
		(FIND-IN-ANY minor-mode-map-alist)
		(FIND-IN (get-text-property (point) 'local-map))
		(FIND-IN (current-local-map)))))
	(FIND-IN (current-global-map)))

Please use @var instead of capital letters.

    @noindent
    @strong{Remark 2:} Characters that are bound to
    @code{self-insert-command} are translated according to
    @code{translation-table-for-input} before insertion.

How self-insert-command works is not part of this topic.
It might be desirable to add this info somewhere else,
but here it does not belong.

    @noindent
    @strong{Remark 3:} You may find the function
    @code{current-active-maps} useful when looking into this.

Such vagueness is unhelpful.  Please say what the function does.
Then add an xref to it.

Re: Function for deleting a key binding in a sparse keymap

[Lennart Borgman]

[-- Attachment #1: Type: text/plain, Size: 1640 bytes --]

Richard M. Stallman wrote:

>I don't think that belongs in this node.  These things should be
>documented elsewhere.  What is needed here is a brief statement that
>key lookup is separate from key input, with mention of
>read-key-sequence, and an xref.
>  
>
I have made a much shorter version.

>    The keymap entry could also be a keymap.  In that case the next event
>    is looked up in that keymap.  
>
>    (@strong{But what happens if there is no hit there, I can not find any
>    documentation on this???})
>
>The question is not clear.  "No hit there"--where is "there"?
>  
>
It was just a silly misunderstanding of me. I have removed it.

>    @noindent
>    @strong{Remark 2:} Characters that are bound to
>    @code{self-insert-command} are translated according to
>    @code{translation-table-for-input} before insertion.
>
>How self-insert-command works is not part of this topic.
>It might be desirable to add this info somewhere else,
>but here it does not belong.
>  
>
I think a link to the place wher translation-table-for-input is 
explained would be good. BTW it would be easier to understand the 
purpose of this variable if it was named translation-table-for-insert. 
Is not that what it is?

I kept the remark in the code but think it should be replaced with that 
link.

>    @noindent
>    @strong{Remark 3:} You may find the function
>    @code{current-active-maps} useful when looking into this.
>
>Such vagueness is unhelpful.  Please say what the function does.
>Then add an xref to it.
>
I have rewritten it but I do not know how to make an xref to it.

I pretty much like the version I have attached now.

[-- Attachment #2: finding-keymap.texi --]
[-- Type: text/plain, Size: 1652 bytes --]

@subsection Finding the keymap and its entry to use

After translation of the input events (@pxref{Translating Input})
Emacs looks in the active keymaps.  As soon as a match is found
(@pxref{Key Lookup}) and the keymap entry is a function the search is
over.  However if the keymap entry is a variable symbol or a string
then Emacs replaces the input key sequences with the variable symbol
value or the string and restarts searching in the active keymaps.

Here is a pseudo-Lisp description of the order in which the active
keymaps are searched:

@lisp
(or (if overriding-terminal-local-map
        (@var{find-in} overriding-terminal-local-map)
      (if overriding-local-map
          (@var{find-in} overriding-local-map)
        (or (@var{find-in} (get-text-property (point) 'keymap))
            (@var{find-in-any} emulation-mode-map-alists)
            (@var{find-in-any} minor-mode-overriding-map-alist)
            (@var{find-in-any} minor-mode-map-alist)
            (@var{find-in} (get-text-property (point) 'local-map))
            (@var{find-in} (current-local-map)))))
    (@var{find-in} (current-global-map)))
@end lisp

@noindent
The @var{find-in} and @var{find-in-any} are pseudo functions that
searches in one keymap respectively an alist of keymaps.

@noindent
@strong{Remark 1:} The finally found function may be remapped
(@pxref{Remapping Commands}).

@noindent
@strong{Remark 2:} Characters that are bound to
@code{self-insert-command} are translated according to
@code{translation-table-for-input} before insertion.

@noindent
@strong{Remark 3:} @code{current-active-maps} returns a list of the
currently active keymaps at (point).

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Function for deleting a key binding in a sparse keymap

[Richard M. Stallman]

    I think a link to the place wher translation-table-for-input is 
    explained would be good.

Ok.

			     BTW it would be easier to understand the 
    purpose of this variable if it was named translation-table-for-insert. 
    Is not that what it is?

Now it is not used only for insertion.  Search commands use it too.
(I will update its documentation.)

    >Such vagueness is unhelpful.  Please say what the function does.
    >Then add an xref to it.
    >
    I have rewritten it but I do not know how to make an xref to it.

The simple way is to make an xref to the node containing the main
explanation of that function.


I think your draft is ready to install.  I will do that, and clarify
some of the wording.