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

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

> The first step was to insert the keybindings with the new face.  But
> rather than doing that in just `help-for-help', and perhaps improve
> other things later, I realized that it is better to decide on a
> consistent look for keybindings in _all_ help commands.
> 
> This means introducing a new face `help-key-binding' and then using
> that any time we output a keybinding for use in the help system.
> 
> But going even further than that, I realized it would be very useful if
> this face applies to any key in any message we output, by convention.
> This would be a useful improvement in consistency, in the same way it
> helps to consistently use `C-' to mean the Control modifier.  It makes
> it easier for users to see that, hey, this text is different in the
> same way that other keybindings have been, so it must also be referring to a
> keybinding.
> 
> So I have made `substitute-command-keys' add this face unconditionally
> to keys.

I think you already knew that I've been doing this
in help-fns+.el for over a decade.  I've offered
the code before, and we've discussed it.  It uses
`help-substitute-command-keys':

  Same as `substitute-command-keys', but optionally
  adds buttons for help.

  Non-nil optional arg ADD-HELP-BUTTONS does that,
  adding buttons to key descriptions, which link to
  the key's command help.

That is, keys are linked to their commands.
So their face is the face Emacs uses for links.

I think that's the right (better) approach.

My code only bothers to recognize keys within
`...'.  Emacs help buffers consistently use
that notation for keys within text, but when
keys are simply listed (e.g. `C-h b') they are
sometimes just written without `...'.

Nevertheless, in those special contexts it
should be relatively straightforward to
recognize the keys, and give them links.

(Presumably, for you to have given them a new
face, you've already got code to recognize them.)

That's maybe not so useful for `C-h b' (since
the command names have links to the same targets).
But for other cases where `...' isn't used it
could help. And even in a case like `C-h b' it
wouldn't hurt - the keys would stand out - which
is presumably your current aim.

I don't see the need for another face, one that
has no associated action.  Just put links on keys.

I couldn't change `substitute-command-keys'
itself, to add an optional arg ADD-HELP-BUTTONS,
but Emacs itself could, of course.  I just
defined a new function, adding prefix `help-'.

> Having looked over the 430 matches for s-c-k in our tree, I couldn't
> find any location where we would not benefit from this consistency.  On
> the contrary, it would be quite nice to see that the same face used in
> *Help* also shows up in messages such as these:
> 
>     "Use \\[shadow-copy-files] to update shadows."
>     "Press \\[wdired-finish-edit] when finished or \\[wdired-abort-
> changes] ..."
>     "\\[scroll-up] scrolls up, \\[scroll-down] scrolls down, ..."
> 
> Please find attached a patch.  It is a little bit rough around the
> edges still so needs polishing up and documentation.  For testing,
> try e.g. `C-h C-h', `C-h C-h', `C-h C-c', or even `C-s C-h ?'.

That's already been solved.

> Thoughts welcome.

Don't do it.  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.