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