Re: Consistent face for keys in *Help* and `substitute-command-keys'

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

>> +  "Face for keybindings in *Help* buffers.
>
> I wonder why green?  It looks quite weird.
>
> All the most popular
> markup renderers nowadays such as GitHub and GitLab display keybindings
> using light grey background like this:

Yes, I agree.  Sorry about that...

I was considering for a while to do mimic the color scheme of VSCode:

    https://code.visualstudio.com/docs/getstarted/userinterface

But I was going back and forth on this and in the end decided on using
green (for now, and look at this more properly later).  You are correct
that green is not an excellent choice.

> diff --git a/lisp/faces.el b/lisp/faces.el
> index b2d47edca0..0f956b0cde 100644
> --- a/lisp/faces.el
> +++ b/lisp/faces.el
> @@ -2816,11 +2816,11 @@ help-argument-name
>    :group 'help)
>
>  (defface help-key-binding
> -  '((((class color) (min-colors 88) (background light)) :foreground 
> "ForestGreen")
> -    (((class color) (min-colors 88) (background dark)) :foreground "#44bc44")
> -    (((class color grayscale) (background light)) :foreground "grey15")
> -    (((class color grayscale) (background dark)) :foreground "grey85")
> -    (t :foreground "ForestGreen"))
> +  '((((class color) (min-colors 88) (background light)) :background "grey85")
> +    (((class color) (min-colors 88) (background dark)) :background "grey25")
> +    (((class color grayscale) (background light)) :background "grey85")
> +    (((class color grayscale) (background dark)) :background "grey25")
> +    (t :background "grey85"))
>    "Face for keybindings in *Help* buffers.

Excellent idea, let's do it.  But grey85 is much too dark.  Compare
grey85 (using M-x list-colors-display) to the hexadecimal values used in
the VSCode documentation or on GitHub, and see that they use very bright
greys (#f9f2f4 and #f6f8fa) while grey85 is #d9d9d9.

I was toying with the much brighter grey95 (or perhaps something even
brighter -- again, compare the hexadecimal values).

Did you test this on a terminal, BTW?  What do you think?

Another thing I see is that they use more padding (a bigger square)
around the keybindings.  We can muck around with the display properties
to achieve something similar, but the lines won't be even height.  It
would automatically look slightly better here if our `line-spacing'
variable was something like 1, 2 or even 3 by default in these buffers.
(This would really be a better all-around choice in all buffers for
legibility, and is what is done on all modern text editors AFAICT.)

(I was also looking at possibly using some blue colour for the
foreground like VSCode does.  It really looks superb in their use, and
makes it highly readable.  But it was tricky to do something similar
when we also want to avoid confusion with our links.  They also
consistently use a subtle red #c7254e to highlight their functions,
which is interesting [the idea, not the colour].)

>  This face is added by `substitute-command-keys', which see.
>
> BTW, I noticed after typing 'C-u C-x =' that face information is
> duplicated:
>
>   There are text properties here:
>     face                 help-key-binding
>     font-lock-face       help-key-binding

Yes, this is because this was the only way to get this to work
consistently: in some buffers only `face' works and in others only
`font-lock-face' works.  :-(