Qs on key-description, substitute-command-keys

Qs on key-description, substitute-command-keys

[Drew Adams]

Why was the output from `key-description' and `substitute-command-keys'
changed to use angle brackets around simple key sequences like S-tab?

I have, for instance, a help string that looks like this when displayed:
(S-tab or TAB: list, C-h: help). I mean, that's what it looks like in Emacs
20 - in Emacs 22, the first key sequence is shown as <S-tab>, while the
others remain simple, without angle brackets.

I'm sure there are good reasons why this was changed, but I'm curious why.

Is there another standard function I can call, perhaps in combination with
`substitute-command-keys', to get the simpler representation, S-tab, from
the less readable <S-tab>? Or should I just roll my own?

Also, is there a good way to control which of several key bindings for a
command is output by `substitute-command-keys'? The only way I've found is
to make sure that the one I want is the last of the key sequences for that
command defined in the map - and that's not always feasible. I found nothing
in the manual about which binding is displayed or how to control that.

Re: Qs on key-description, substitute-command-keys

[Kevin Rodgers]

Drew Adams wrote:
 > Why was the output from `key-description' and `substitute-command-keys'
 > changed to use angle brackets around simple key sequences like S-tab?

I would guess to make them consistent with kbd, insert-kdb-macro,
edit-kbd-macro, and view-lossage.

 > I have, for instance, a help string that looks like this when displayed:
 > (S-tab or TAB: list, C-h: help). I mean, that's what it looks like in 
Emacs
 > 20 - in Emacs 22, the first key sequence is shown as <S-tab>, while the
 > others remain simple, without angle brackets.

TAB (aka C-i) and C-h are ASCII characters and thus are categorized as
keyboard events.  <tab> is a function key, and <S-tab> is a modified
function key.

 > I'm sure there are good reasons why this was changed, but I'm curious 
why.
 >
 > Is there another standard function I can call, perhaps in combination 
with
 > `substitute-command-keys', to get the simpler representation, S-tab, from
 > the less readable <S-tab>? Or should I just roll my own?

The Keyboard Events node of the Emacs Lisp manual says "The 2**25 bit in
the character code indicates an ASCII control character typed with the
shift key held down."  So if you want a Shift-TAB, try (kbd "S-TAB"),
[(shift ?\t)], or [?\S-\C-i].

 > Also, is there a good way to control which of several key bindings for a
 > command is output by `substitute-command-keys'? The only way I've 
found is
 > to make sure that the one I want is the last of the key sequences for 
that
 > command defined in the map - and that's not always feasible. I found 
nothing
 > in the manual about which binding is displayed or how to control that.

-- 
Kevin Rodgers

RE: Qs on key-description, substitute-command-keys

[Drew Adams]

     > to get the simpler representation, S-tab, from
     > the less readable <S-tab>?
    
    if you want a Shift-TAB, try (kbd "S-TAB"),
    [(shift ?\t)], or [?\S-\C-i].

Thanks! Using [(shift ?\t)] works fine.

RE: Qs on key-description, substitute-command-keys

[Drew Adams]

I never got any feedback on this question:

    Also, is there a good way to control which of several key bindings for a
    command is output by `substitute-command-keys'? The only way
    I've found is to make sure that the one I want is the last of the key
    sequences for that command defined in the map - and that's not always
    feasible. I found nothing in the manual about which binding is displayed
    or how to control that.

Does anyone know how to control which of several bindings for a command is
displayed by `substitute-command-keys'?

The workaround I mentioned works only when you can control all of the
`define-key's. It does not work, for instance, if you do a
`substitute-key-definition' or, presumably, a (define-key [remap...]...).

For example:

(substitute-key-definition 'scroll-left 'my-cmd
                           'minibuffer-local-completion-map)

`scroll-left' is globally bound to `C-next' and `C-x <'. I would like the
former binding to show via `substitute-command-keys', but the latter shows.
I have several bindings like this, all closely related, and all simple
bindings using prefix `C-'. But the resulting doc string shows bindings that
are all seemingly unrelated (all over the map, so to speak ;-)).

If there is no way to control this, could Emacs itself be configured to
prefer a binding that does not use a prefix key whenever there is one?  That
is, could it be designed so that `substitute-command-keys' prefers to show
`C-next' instead of `C-x <' for `scroll-left'?  (Somehow, I anticipate
people saying that some terminals don't have [next] keys, so `C-x <' is
better...)

Thx.

Re: Qs on key-description, substitute-command-keys

[Juri Linkov]

>     Also, is there a good way to control which of several key bindings for a
>     command is output by `substitute-command-keys'? The only way
>     I've found is to make sure that the one I want is the last of the key
>     sequences for that command defined in the map - and that's not always
>     feasible. I found nothing in the manual about which binding is displayed
>     or how to control that.
>
> Does anyone know how to control which of several bindings for a command is
> displayed by `substitute-command-keys'?

There is the same problem for the key suggestion feature activated by
`suggest-key-bindings' displaying in the echo area only the "first"
key binding which is not always better than other key bindings.
A good solution is to suggest all key bindings in the echo area
just like `where-is' (`C-h w') does.

Perhaps it is not a good solution for `substitute-command-keys' to
replace key descriptions with all key bindings since the resulting
string might be too long.  However, how about introducing a new
convention that all strings on which `substitute-command-keys' is used
should be designed to reserve enough space for the case when the
command is not on any keys, and so `M-x COMMAND' is printed.  The size
of the command name plus 4 characters of the "M-x " string should
define the maximum length of allowed substitutions, and if the command
is bound to several key, then to print as many keys as many of them
fits into this limit.  For example:

M-x scroll-left        -> defines the maximum 15 characters
C-next, C-x <          -> both keys fit into 15-characters limit,
                          so replace \[scroll-left] with both keys

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: Qs on key-description, substitute-command-keys

[Drew Adams]

    > Does anyone know how to control which of several bindings for
    > a command is displayed by `substitute-command-keys'?

    There is the same problem for the key suggestion feature activated by
    `suggest-key-bindings' displaying in the echo area only the "first"
    key binding which is not always better than other key bindings.
    A good solution is to suggest all key bindings in the echo area
    just like `where-is' (`C-h w') does.

    Perhaps it is not a good solution for `substitute-command-keys' to
    replace key descriptions with all key bindings since the resulting
    string might be too long.  However, how about introducing a new
    convention that all strings on which `substitute-command-keys' is used
    should be designed to reserve enough space for the case when the
    command is not on any keys, and so `M-x COMMAND' is printed.  The size
    of the command name plus 4 characters of the "M-x " string should
    define the maximum length of allowed substitutions, and if the command
    is bound to several key, then to print as many keys as many of them
    fits into this limit.  For example:

    M-x scroll-left        -> defines the maximum 15 characters
    C-next, C-x <          -> both keys fit into 15-characters limit,
                              so replace \[scroll-left] with both keys

I appreciate the response, and the workaround suggestion. However, this
convention will not work for many uses of `substitute-command-keys', because
the helpful prompt, message or help text 1) already has a premium on space
and, more importantly, 2) often mentions more than one key.

Here's an example of text I append to the minibuffer prompt during
completion:

(substitute-command-keys
   " (\\<minibuffer-local-completion-map>\\[icicle-apropos-complete], \
\\[icicle-prefix-complete]: list, \\[icicle-completion-help]: help) ")

That produces this text: " (<S-tab>, TAB: list, C-h: help) "

If each of these commands had several bindings, the result would be not only
long but incomprensible. Even something like the "tab" key can involve
multiple bindings, to deal with different kinds of terminals.

Re: Qs on key-description, substitute-command-keys

[Richard M. Stallman]

      The size
    of the command name plus 4 characters of the "M-x " string should
    define the maximum length of allowed substitutions, and if the command
    is bound to several key, then to print as many keys as many of them
    fits into this limit.  For example:

That would be a big in convenience for the users.
It would burded those doc strings with inconvenient lists
that would make them harder to read.

No way.

Please remember that completeness is _not_ the goal of documentation.
"More information" is not necessary better.  Often it is just clutter.

Re: Qs on key-description, substitute-command-keys

[Stefan Monnier]

> Does anyone know how to control which of several bindings for a command is
> displayed by `substitute-command-keys'?

There is no way to get this kind of control.  `substitute-command-keys' has
some rules such as "prefer a binding using plain ascii keys" (so it'll
prefer C-x < over C-next, based on the principle that not all terminals have
a `next' key and even fewer have a way to generate a C-next event) and
"prefer a shorter binding".

In Emacs, what we do usually when we need to control which binding to show,
is to define `advertized-foo' as an alias for `foo' and then bind the key we
want shown to `advertized-foo' (and then use \\[advertized-foo] in the
string).  I find this to be a bad solution: it interacts very poorly with
things like `remap' or `substitute-key-definition' and C-h f `foo' forgets
to show the main advertized binding (bummer!).

I think we should devise some way to get the desired result without going
through contorsions like `advertized-bla'.  I haven't thought very deep
about how to do that, but the first thing that jumps to my mind is to rely
on a `preferred-binding' property (containing a key-sequence) on the command
symbol, or otherwise require the use of a menu-item for the main binding and
then obey a boolean ":preferred-binding" property placed on the menu-item.


        Stefan

RE: Qs on key-description, substitute-command-keys

[Drew Adams]

    > Does anyone know how to control which of several bindings for
    > a command is displayed by `substitute-command-keys'?

    There is no way to get this kind of control.

    I think we should devise some way to get the desired result
    without going through contorsions like `advertized-bla'.
    ... the first thing that jumps to my mind is to rely
    on a `preferred-binding' property (containing a key-sequence)
    on the command symbol, or otherwise require the use of a
    menu-item for the main binding and then obey a boolean
    ":preferred-binding" property placed on the  menu-item.

I like the former, as the latter sounds very restrictive (we don't want menu
explosion, just so people can get user-friendly messages with bindings in
them).

However, I would prefer a list of preferred bindings, in order of
preference, to a single binding. If, for some reason, the exact binding is
not known (e.g. might have changed), so that the first preference isn't
available (bound), the next available binding would be used, in order. As a
shortcut, a single binding name could be used in place of the list (= your
suggestion).

Re: Qs on key-description, substitute-command-keys

[Stefan Monnier]

>     I think we should devise some way to get the desired result
>     without going through contorsions like `advertized-bla'.
>     ... the first thing that jumps to my mind is to rely
>     on a `preferred-binding' property (containing a key-sequence)
>     on the command symbol, or otherwise require the use of a
>     menu-item for the main binding and then obey a boolean
>     ":preferred-binding" property placed on the  menu-item.

> I like the former, as the latter sounds very restrictive (we don't want menu
> explosion, just so people can get user-friendly messages with bindings in
> them).

Please read up on what is a "menu-item" in a keymap.  It's used for "menu
items", but can be used anywhere.  E.g. grep for menu-item in pcvs-defs.el.

> However, I would prefer a list of preferred bindings, in order of
> preference, to a single binding. If, for some reason, the exact binding is
> not known (e.g. might have changed), so that the first preference isn't
> available (bound), the next available binding would be used, in order. As a
> shortcut, a single binding name could be used in place of the list (= your
> suggestion).

That makes sense,


        Stefan

Re: Qs on key-description, substitute-command-keys

[Richard M. Stallman]

    However, I would prefer a list of preferred bindings, in order of
    preference, to a single binding. If, for some reason, the exact binding is
    not known (e.g. might have changed), so that the first preference isn't
    available (bound), the next available binding would be used, in order. As a
    shortcut, a single binding name could be used in place of the list (= your
    suggestion).

I don't think we should do this before the release.  Would someone
like to add it to etc/TODO?

Re: Qs on key-description, substitute-command-keys

[John S. Yates, Jr.]

On Sat, 15 Oct 2005 07:54:14 -0400, Stefan Monnier wrote:

> There is no way to get this kind of control.  `substitute-command-keys' has
> some rules such as "prefer a binding using plain ascii keys" (so it'll
> prefer C-x < over C-next, based on the principle that not all terminals have
> a `next' key and even fewer have a way to generate a C-next event) and
> "prefer a shorter binding".

While I can understand the impulse behind this heuristic, it ultimately
seems paternalistic ("we need to prepare you for the great variety of
terminals that you may encounter").

A better approach might be a set of configurable rules that would lead
to a considered choice. 

1) Emacs can usually query the environment to determine the nature of the
keyboard in use.  With this information it can exclude bindings that would
be impossible to produce.  In the same vein, if the menubar is not displayed
there is again no point in suggesting menu bindings.

2) There should be a set of rules.  I imagine an ordered set of predicates.
After applying the hard filtering described above, if more than one binding
survives, develop a per-binding preference strings as follows: apply each
predicate in order; encode each failed predicate as '0', and each successful
predicate as '1'.  Compare the strings lexically. The lexically lowest string
will correspond to the most desirable binding.  (With a limit on the number
of rules an analogous scheme could be implement using bit strings encoded as
integers.)

My hope is that after describing my preferences as a set of rules, emacs
would oblige me by suggesting bindings compatible with my idiosyncrasies.
In particular I would like this to work for new packages that I have not
used before, let alone customized in any fashion.

/john
a users is likely to find 

/john

Re: Qs on key-description, substitute-command-keys

[Stefan Monnier]

> While I can understand the impulse behind this heuristic, it ultimately
> seems paternalistic ("we need to prepare you for the great variety of
> terminals that you may encounter").

No, it's just done for lack of anything better.  Currently, Emacs almost
never knows which keys you have access to.  The only exception is that we
try to figure out whether you have both `delete' and `backspace', but
already that only works in some restricted cases.

> 1) Emacs can usually query the environment to determine the nature of the
> keyboard in use.  With this information it can exclude bindings that would
> be impossible to produce.

Patch welcome,


        Stefan