RE: [External] : Consistent face for keys in *Help* and `substitute-command-keys'

[Drew Adams]

> >> I also don't know of too many examples where
> >> links will be highly useful.
> >
> > Specifics, please.  Show an example where a
> > `...' key link isn't useful.
> 
> I actually meant what I wrote literally.
> 
> So I would rather have hoped that you have some
> examples of where it is "highly useful".

Pretty much any *Help* buffer where keys are described.

1. emacs -Q
2. Load help-fns+.el.
3. Dired a directory.
4. `C-h m'

Contrast that with the same recipe without loading
help-fns+.el.  In this case the keys aren't even
surrounded by `...', but they're nevertheless
handled by `substitute-command-keys' (which is the
real criterion), so they're given links.

Or try any other *Help* that describes keys, where
`substitute-command-keys' gets used (because of
\\[...]).

There's nothing special about Dired `C-h m'.  When
I start Emacs (even with -Q) I start in a Dired
buffer.  So it's the first thing I tried.  It's a
fine recipe, but pretty much any other help command
that shows some keys would be as fine.

> >> Still, I'm not writing off the idea completely,
> >> I just don't currently see how to balance the drawbacks.
> >
> > What drawbacks?  So far, you've talked only
> > abstractly, about things that don't exist.
> 
> I see two drawbacks:
> 
> a) Too many links in the *Help* buffer that compete for attention.

Not at all.  Try the recipe.  There's nothing
distracting; not "too many links" at all.

(Sounds like Emperor Joseph II's "Too many notes".
Not that I compare myself with Mozart. ;-))

Please show an example with "too many links".

> b) Not being able to show a consistent face in the minibuffer and the
>    help buffer.  (This is true iff we would use the `button' face also
>    for linked keys in *Help*.  Of course we could just not do that, but
>    then we have an inconsistent face for the links instead...)
> 
> >> it is unfortunately not much help to start from anything
> >> that is not the Emacs source code or a patch to the Emacs
> >> source code.
> >
> > And yet that's what you've done with other parts
> > of help-fns+.el...  Suit yourself.
> 
> I assume you refer to `describe-keymap'?  That work was
> very different in nature.

`describe-keymap', `describe-package', `describe-command',
`describe-option',... so far.

And there's nothing "very different in nature" about
any of those help-fns+.el inventions.  They're all
minor and simple, but useful.

> My point is that it is not always as easy as just re-using
> some existing code.  We still need to integrate it in Emacs.

I said, from the beginning:

  If you can recognize keys then give them links,
  not just a new face.

  You can start with the code in help-fns+.el.
  Or you can start from scratch.  But DTRT.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The point is to _give keys links_, not just color
them.  I have code that does that, which you can
use, but you haven't even tried yet (so you say).

If you want to do it some other way, then do that,
but do it - give keys links - color, yes, but
color with purpose.

> It is of course good that you offer your code for
> inclusion, but when you do so in general terms
> (rather than, say, as a patch) there is still quite
> some work remaining to make it happen.  This was
> true for a highly isolated command like
> `describe-keymap', and even more so for the feature
> we discuss here.

Actually no, there was nothing you needed to do, for
`describe-keymap'.  But you wanted different behavior,
so you changed it slightly.  Fine.  (That means I
still need to provide my version, which has optional
arg SEARCH-SYMBOLS-P, but so be it.)

I don't care if you use my `describe-command' or
whatever.  If the behavior you provide is equal or
better, then I can get rid of my version (except for
older Emacs versions, where it's not provided yet).

But if the behavior you provide isn't as good, then
unfortunately, I need to keep providing my version.
I'd prefer that Emacs itself offer such features - for
Emacs's benefit, not just so I can stop maintaining
them.  But if it doesn't, then it's no big deal.

IMO, keys should have links in *Help* - in general,
and pretty much all the time.  There are no doubt some
rare exceptions.  `C-h b' could be an exception, since
the keys are just listed next to their commands, which
have links (and the key and command targets would be
the same).

I can't think of any other exceptions off hand, but
there might be one or two.  Clearly, *Help* that
lists keys together with their _descriptions_ is not
an exception.  That includes `C-h C-h', just as much
as `C-h m'.

The point is a general one: link keys, just like we
link variables & functions.  Should be a no-brainer,
IMO.  I'd think that anyone comparing even just
Dired `C-h m' with & without key links would agree.
___

But what do I know?

[NIH?  I also thought (think) that Lar's "solution"
for providing command filtering for `M-x' is waaay
overengineered, obtrusive, hard to maintain, and
impossible for users to modify.  A simple `put'
of a property on the command symbol would be far
better, for the reasons I gave.

But though that's been argued several times (even
by Eli), the arguments go ignored - no counter
argument, no response at all.  Just ignore it;
it'll go away, and Emacs'll be none the wiser.
Alas.]