doc of prompt change with minor mode for read-key-sequence?

doc of prompt change with minor mode for read-key-sequence?

[Drew Adams]

I may not be characterizing this 100% correctly, but perhaps this will help
someone knowledgeable to understand.

I have this:

;; Make [pause] key be a synonym for `C-x 8' (compose key).
(define-key key-translation-map [pause]
  (lookup-key key-translation-map "\C-x8"))

I also have a minor mode named "Foo".

When I do `C-h k' without the minor mode active, and hit the [pause] key,
the prompt remains "Describe key: " (that is, I see "Describe key: pause-").
When I do the same thing with the minor mode active, the prompt changes to
"Foo: " (and there is no "pause-" to indicate the prefix).

It took me quite a while to discover where this second prompt was coming
from. Because the translation happens at a low level, I couldn't figure out
a way to debug it. By experimenting and searching source code, I found that
"Foo: " comes from the name of the minor-mode keymap: (make-sparse-keymap
"Foo"). (I don't know where the ": " is appended or in what code that takes
place.)

Questions:

1) Why does this happen? What is the purpose of the prompt change? Why
doesn't "pause-" appear, as it does without the minor mode?

2) What are users to understand by this? Should the prompt instead say at
least "Foo mode: " perhaps, to at least let users know what "Foo" refers to?

3) Shouldn't this be documented somewhere, especially since it is so
difficult to find/debug (being a low-level translation)?

Re: doc of prompt change with minor mode for read-key-sequence?

[Richard Stallman]

    It took me quite a while to discover where this second prompt was coming
    from. Because the translation happens at a low level, I couldn't figure out
    a way to debug it. By experimenting and searching source code, I found that
    "Foo: " comes from the name of the minor-mode keymap: (make-sparse-keymap
    "Foo"). (I don't know where the ": " is appended or in what code that takes
    place.)

I am not quite sure why this is happening, but I can tell you
something.  The "Foo" you specified in the keymap is its name as a
menu.  It ought to be used if the map is used as a menu, either a
mouse menu or a keyboard menu.

I do not see why it would be used as a menu in this case,
but apparently it is.

RE: doc of prompt change with minor mode for read-key-sequence?

[Drew Adams]

        It took me quite a while to discover where this second
        prompt was coming from. Because the translation happens
        at a low level, I couldn't figure out a way to debug it.
        By experimenting and searching source code, I found that
        "Foo: " comes from the name of the minor-mode keymap:
        (make-sparse-keymap "Foo"). (I don't know where the ": "
        is appended or in what code that takes place.)

    I am not quite sure why this is happening, but I can tell you
    something.  The "Foo" you specified in the keymap is its name as a
    menu.  It ought to be used if the map is used as a menu, either a
    mouse menu or a keyboard menu.

    I do not see why it would be used as a menu in this case,
    but apparently it is.

Right. I don't know why this happens either.

My concern is that this is incomprehensible to users. If there is a good
reason why this happens, then perhaps the prompt should make the meaning
more explicit somehow. And, it should be documented somewhere. That was my
point.

Does someone know what this is all about, what it is for? (And where in the
code it happens?)

Re: doc of prompt change with minor mode for read-key-sequence?

[Stefan Monnier]

> Does someone know what this is all about, what it is for? (And where in the
> code it happens?)

IIUC this is the so-called "HierarKey" feature (or something like that).
To see it in (useful) action, try M-o.
I can't figure out from your original report what your minor mode "Foo" does
(how is it defined, what does its keymap look like, ...?), so I'm not sure if
what you see is the "expected" behavior or a bug.


        Stefan

RE: doc of prompt change with minor mode for read-key-sequence?

[Drew Adams]

    > Does someone know what this is all about, what it is for?
    > (And where in the code it happens?)

    IIUC this is the so-called "HierarKey" feature (or something
    like that). To see it in (useful) action, try M-o. I can't
    figure out from your original report what your minor mode
    "Foo" does (how is it defined, what does its keymap look
    like, ...?), so I'm not sure if what you see is the
    "expected" behavior or a bug.

Thanks for replying. I'm not sure what you mean - how to try it with M-o.
Could you provide a short recipe, and mention what to look for?

Searching for "Hierarkey", I found node Keyboard Menus in the Elisp manual.
I'm not sure if what I'm describing is a bug - I hope so, because I find the
behavior confusing, if not incomprehensible for users.

The doc says that the feature is used "When a prefix key ending with a
keyboard event (a character or function key) has a definition that is a menu
keymap". In that case, you can "use the keyboard to choose a menu item."

However, that is not the case here, I believe. The prefix key does not end
with a function key that has a menu-keymap definition. It has a definition
that _belongs_ to a menu keymap, which is not the same thing. And I cannot
see how someone would/could use this feature in this context - it seems only
to confuse things, to me. But I'm willing to learn.

Also, since this feature obviously affects user-observable behavior, it
should be documented in the Emacs manual. It is not only the implementation
that is of interest to Emacs-Lisp programmers: Apparently, Emacs users must
also be aware of this feature.

As for my code, I have this:
(define-key key-translation-map [f12]
  (lookup-key key-translation-map "\C-x8"))

The minor mode is "Icicles", not "Foo". The minor mode
(`icicle-mode') and its keymap (`icicle-mode-map')
are defined here:
http://www.emacswiki.org/cgi-bin/wiki/icicles-mode.el.

Here is an outline of the keymap definition:

  (let ((map (make-sparse-keymap "Icicles")))
    (define-key map [menu-bar] (make-sparse-keymap))
    (define-key map [menu-bar icicles] (cons "Icicles" map))
    ...
    (define-key map [pause] 'icicle-switch-to/from-minibuffer)
    (define-key map [f10] 'icicle-execute-menu-command)
    (push (cons 'icicle-mode map) minor-mode-map-alist)
    (setq icicle-mode-map map))

As I indicated, when I do `C-h k' for the `f12' key with the minor mode
active, the prompt changes to "Icicles: ", and there is no longer any "f12-"
in the prompt to indicate the prefix.

(So, to reply to RMS: yes, "Icicles" is for the menu title, but the keymap
is not used only for the menubar menu.)

Re: doc of prompt change with minor mode for read-key-sequence?

[Stefan Monnier]

>> Does someone know what this is all about, what it is for?
>> (And where in the code it happens?)

>     IIUC this is the so-called "HierarKey" feature (or something
>     like that). To see it in (useful) action, try M-o. I can't
>     figure out from your original report what your minor mode
>     "Foo" does (how is it defined, what does its keymap look
>     like, ...?), so I'm not sure if what you see is the
>     "expected" behavior or a bug.

> Thanks for replying. I'm not sure what you mean - how to try it with M-o.
> Could you provide a short recipe, and mention what to look for?

> Searching for "Hierarkey", I found node Keyboard Menus in the Elisp manual.
> I'm not sure if what I'm describing is a bug - I hope so, because I find the
> behavior confusing, if not incomprehensible for users.

> The doc says that the feature is used "When a prefix key ending with a
> keyboard event (a character or function key) has a definition that is a menu
> keymap". In that case, you can "use the keyboard to choose a menu item."

> However, that is not the case here, I believe. The prefix key does not end
> with a function key that has a menu-keymap definition. It has a definition
> that _belongs_ to a menu keymap, which is not the same thing. And I cannot
> see how someone would/could use this feature in this context - it seems only
> to confuse things, to me. But I'm willing to learn.

> Also, since this feature obviously affects user-observable behavior, it
> should be documented in the Emacs manual. It is not only the implementation
> that is of interest to Emacs-Lisp programmers: Apparently, Emacs users must
> also be aware of this feature.

> As for my code, I have this:
> (define-key key-translation-map [f12]
>   (lookup-key key-translation-map "\C-x8"))

> The minor mode is "Icicles", not "Foo". The minor mode
> (`icicle-mode') and its keymap (`icicle-mode-map')
> are defined here:
> http://www.emacswiki.org/cgi-bin/wiki/icicles-mode.el.

> Here is an outline of the keymap definition:

>   (let ((map (make-sparse-keymap "Icicles")))
>     (define-key map [menu-bar] (make-sparse-keymap))
>     (define-key map [menu-bar icicles] (cons "Icicles" map))
>     ...
>     (define-key map [pause] 'icicle-switch-to/from-minibuffer)
>     (define-key map [f10] 'icicle-execute-menu-command)
>     (push (cons 'icicle-mode map) minor-mode-map-alist)
>     (setq icicle-mode-map map))

> As I indicated, when I do `C-h k' for the `f12' key with the minor mode
> active, the prompt changes to "Icicles: ", and there is no longer any "f12-"
> in the prompt to indicate the prefix.

Looks like a bug indeed.  The interaction of key-translation-map with the
rest of the key lookup and handling is pretty messy.  I'll try and take
a look at it.


        Stefan

Re: doc of prompt change with minor mode for read-key-sequence?

[Richard Stallman]

If you don't want that keymap to function as a menu, why give it a
menu title?

(This does not mean I am against fixing the bug in Emacs
if this is due to one.)

RE: doc of prompt change with minor mode for read-key-sequence?

[Drew Adams]

    If you don't want that keymap to function as a menu, why give it a
    menu title?

It is the map for a global minor mode, Icicles. It functions as a menu-bar
menu map, and there are also keyboard sequences bound in it.

IOW, when that minor mode is turned on: 1) you get an "Icicles" menu-bar
menu and 2) certain key sequences are defined. When the mode is turned off,
the key sequences and menu bar are returned to the normal state.

    (This does not mean I am against fixing the bug in Emacs
    if this is due to one.)

Re: doc of prompt change with minor mode for read-key-sequence?

[Richard Stallman]

    It is the map for a global minor mode, Icicles. It functions as a menu-bar
    menu map, and there are also keyboard sequences bound in it.

To make the menu-bar menu work, you need to give a prompt string aka
menu name to the map that you put on the prefix key menu-bar.  But you don't
need to give a prompt string aka menu name to the overall keymap for
Icicles.  That never needs to operate as a menu.

So try removing the arg to make-sparse-keymap when you make the
overall keymap, and see if everything works right.

RE: doc of prompt change with minor mode for read-key-sequence?

[Drew Adams]

        It is the map for a global minor mode, Icicles. It
        functions as a menu-bar
        menu map, and there are also keyboard sequences bound in it.

    To make the menu-bar menu work, you need to give a prompt string aka
    menu name to the map that you put on the prefix key menu-bar.
    But you don't
    need to give a prompt string aka menu name to the overall keymap for
    Icicles.  That never needs to operate as a menu.

    So try removing the arg to make-sparse-keymap when you make the
    overall keymap, and see if everything works right.

Thank you; that took care of it.

I think maybe I used the name in the call to `make-sparse-keymap' because I
figured it wouldn't hurt, and I might use it someday as a pop-up-menu
(somehow). This part of the doc string might have given me that impression:

 "The optional arg string supplies a menu name for the keymap
 in case you use it as a menu with `x-popup-menu'."

I think I figured "in case you use it" meant that it would only be used in
that case, and I didn't know at the time whether I might use it in that way
in some context. Actually, I don't really remember. Anyway, thanks. I know
now that I should reserve supplying the name for when I really want a menu.

Re: doc of prompt change with minor mode for read-key-sequence?

[Richard Stallman]

I improved the Lisp Manual's documentation about these issues.

Re: doc of prompt change with minor mode for read-key-sequence?

[Stefan Monnier]

> As for my code, I have this:
> (define-key key-translation-map [f12]
>   (lookup-key key-translation-map "\C-x8"))

> The minor mode is "Icicles", not "Foo". The minor mode
> (`icicle-mode') and its keymap (`icicle-mode-map')
> are defined here:
> http://www.emacswiki.org/cgi-bin/wiki/icicles-mode.el.

Can't reproduce this.  Can you give a detailed step-by-step recipe, starting
from `emacs -Q'?


        Stefan