bug#14086: 24.3.50; `substitute-command-keys': inappropriate "(that binding is currently shadowed by another mode)"

[Drew Adams <drew.adams@oracle.com>]

> > Not sure what you're saying.  Why should we show the
> > shadowed binding?  That's the question I was asking
> > there.  How it comes to be shown was the subject
> > above that in the post.  But should it be shown?
> > If so, why?
> 
> It's debatable, sure.  But sometimes it's useful info, don't you think?
> If you unbind the shadowing key to nil, the other binding will take
> effect, so in that sense it is meaningful to the behavior of the keymap.
> 
> Do you think we should not list shadowed bindings (and why)?

No, I was just asking the question - open.

You provided a reason to show shadowed bindings.
That's good enough for me - makes sense.

But it only makes sense if someone can understand.
What's missing is something, somewhere, that tells
you what it means to show one binding for a key
with no special mention (no mention of shadowing)
and another binding for the same key, with just a
mention that it is shadowed by some other key.

What shadowing means needs to be conveyed somehow,
somewhere.  And it would be better to list the
command that shadows the shadowed command/binding.

As an analogy, if some function or variable is an
alias for another, the help tells you that.  Or if
you ask for the value of a variable in a buffer
where it's local, the help tells you the local
value and lets you know what the global value is.

If we list an `M-r' binding to
`previous-matching-history-element' that's shadowed
by an `M-r' binding to `icicle-roundup' then it
would be good to say that the former is shadowed by
the latter.  Currently we say only that it is
shadowed by another "mode".

It would be even better if we said what keymap
the shadowed binding is bound in, and what keymap
the shadowing binding is bound in.  Dunno whether
that's always possible, but it would help.

The first thing that's missing is what "shadow"
means - that wasn't clear to me at all.  I think
it would help, even if we didn't explain that
term, if we explicitly said which binding (e.g.
`icicle-roundup') does the shadowing.  With that
info a user might be able to guess what "shadow"
means.

What's most important is that it's clear to a user
that ONLY the shadowing binding is in effect.
Mentioning the shadowed binding is only extra info
about what could happen if the shadowing binding
weren't in effect.  (Like what would happen if a
buffer-local value were removed.)

Another thing that hampers understanding is the
order of the bindings listed.  Both bindings of
`M-r' should be listed next to each other.

I'm looking at the output of `describe-keymap'
for `minibuffer-local-completion-map', and the
order is not clear/useful, I think.

[I see the same thing using either my version of
`describe-keymap' or the version added to Emacs 28
(bug #30660).]

But #14086 is about the unclear help when it comes
to listing shadowed bindings.  I agree that it can
be useful to list such bindings, but only if we
can make clear what they mean.  The gain is minor,
and not worth it if we can't make this clear, I
think.