Proposal for an improved `help-for-help'

Proposal for an improved `help-for-help'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 621 bytes --]

One of the usability complaints I've heard is that `help-for-help'
(`C-h C-h') could be better organized.  I also think some colors could
really help in making it easier to navigate.

I have attached a rough draft for what an improved version of might look
like.  It would be great to get some feedback.

I have also attached a patch, but it's very rough.  I'm specifically
having some trouble with font-locking: It works if I copy the contents
of the " *Metahelp*" buffer and invoke the mode manually, but it will
not work when I say `C-h C-h'.  Help with this is also welcome -- I'm
probably missing something obvious.

[-- Attachment #2: help-for-help-new.png --]
[-- Type: image/png, Size: 229054 bytes --]

[-- Attachment #3: 0001-Help-for-help-mode.patch --]
[-- Type: text/x-diff, Size: 7844 bytes --]

From 25604343235028d606bdd0b26bc0eae6a76e281c Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Sat, 20 Feb 2021 17:07:23 +0100
Subject: [PATCH] Help for help mode

---
 lisp/help-macro.el | 13 +++++++---
 lisp/help-mode.el  | 36 +++++++++++++++++++++++++++
 lisp/help.el       | 61 +++++++++++++++++++++++++++++-----------------
 3 files changed, 84 insertions(+), 26 deletions(-)

diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 791b10a878..6d4d901acf 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -83,15 +83,21 @@ three-step-help
   :type 'boolean
   :group 'help)
 
-(defmacro make-help-screen (fname help-line help-text helped-map)
+(defmacro make-help-screen (fname help-line help-text helped-map &optional mode)
   "Construct help-menu function name FNAME.
 When invoked, FNAME shows HELP-LINE and reads a command using HELPED-MAP.
+
 If the command is the help character, FNAME displays HELP-TEXT
 and continues trying to read a command using HELPED-MAP.
+
 If HELP-TEXT contains the sequence `%THIS-KEY%', that is replaced
 with the key sequence that invoked FNAME.
+
 When FNAME finally does get a command, it executes that command
-and then returns."
+and then returns.
+
+If optional argument MODE is non-nil, use that mode instead of
+`help-mode'."
   (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
     `(progn
        (defun ,doc-fn () ,help-text nil)
@@ -145,7 +151,8 @@ make-help-screen
 		       (erase-buffer)
 		       (insert help-screen))
 		     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-		       (help-mode)
+                       ,(or (and mode `(,mode))
+                            '(help-mode))
 		       (setq new-minor-mode-map-alist minor-mode-map-alist))
 		     (goto-char (point-min))
 		     (while (or (memq char (append help-event-list
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 30a1ce053c..7dd9317aea 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -788,6 +788,42 @@ help-insert-string
   (with-output-to-temp-buffer (help-buffer)
     (insert string)))
 
+\f
+;; `help-for-help' syntax highlighting
+
+(defface help-for-help-header '((t :weight bold :foreground "darkblue"
+                               :height 1.2))
+  "Face used for headers in the `help-for-help' buffer."
+  :group 'help)
+
+(defface help-for-help-binding '((t :weight bold :foreground "SpringGreen4"))
+  "Face used for headers in the `help-for-help' buffer."
+  :group 'help)
+
+(defvar help-for-help-mode-font-lock-keywords
+  `((,(rx bol (or "Basic Help"
+                  "Documentation"
+                  "Searching and packages"
+                  "Other")
+          eol)
+     0 'help-for-help-header)
+    (,(rx bol (? (any "MCs") "-") (any letter ".")
+      " "
+      (? (one-or-more (or alnum "-"))))
+     0 'help-for-help-binding)
+    (,(rx word-start (group (or "C-h" "F1" "SPC" "DEL")) word-end)
+     (1 'help-for-help-binding))
+    (,(rx (seq "Type " (group "q") " to")) (1 'help-for-help-binding)))
+  "Font lock keywords for `help-for-help-mode'.")
+
+;;;###autoload
+(define-derived-mode help-for-help-mode help-mode "Help X"
+  "Major mode used by `help-for-help'."
+  :interactive t
+  (setq-local font-lock-defaults `(,help-for-help-mode-font-lock-keywords t))
+  ;; FIXME: Why is this needed?
+  (font-lock-fontify-buffer))
+
 \f
 ;; Bookmark support
 
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..e842c600aa 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -199,39 +199,53 @@ 'help-for-help
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
 \(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
 
-a PATTERN   Show commands whose name matches the PATTERN (a list of words
-              or a regexp).  See also the `apropos' command.
+Basic Help
+
+m           Display documentation of current minor modes and current major mode,
+              including their special commands.
 b           Display all key bindings.
+x COMMAND   Display documentation for the given command.
+k KEYS      Display the full documentation for the key sequence.
+
+f FUNCTION  Display documentation for the given function.
+o SYMBOL    Display the given function or variable's documentation and value.
+v VARIABLE  Display the given variable's documentation and value.
+
 c KEYS      Display the command name run by the given key sequence.
-C CODING    Describe the given coding system, or RET for current ones.
+w COMMAND   Display which keystrokes invoke the given command (where-is).
+.           Display any available local help at point in the echo area.
+
+Documentation
+
+r           Display the Emacs manual in Info mode.
+i           Start the Info documentation reader: read included manuals.
+t           Start the Emacs learn-by-doing tutorial.
+F COMMAND   Show the Emacs manual's section that describes the command.
+K KEYS      Show the Emacs manual's section for the command bound to KEYS.
+S SYMBOL    Show the section for the given symbol in the Info manual
+              for the programming language used in this buffer.
+R           Prompt for a manual and then display it in Info mode.
+
+Searching and packages
+
+a PATTERN   Show commands whose name matches the PATTERN (a list of words
+              or a regexp).  See also the `apropos' command.
 d PATTERN   Show a list of functions, variables, and other items whose
               documentation matches the PATTERN (a list of words or a regexp).
+P PACKAGE   Describe the given Emacs Lisp package.
+p TOPIC     Find packages matching a given topic keyword.
+
+Other
+
+C CODING    Describe the given coding system, or RET for current ones.
 e           Go to the *Messages* buffer which logs echo-area messages.
-f FUNCTION  Display documentation for the given function.
-F COMMAND   Show the Emacs manual's section that describes the command.
 g           Display information about the GNU project.
 h           Display the HELLO file which illustrates various scripts.
-i           Start the Info documentation reader: read included manuals.
 I METHOD    Describe a specific input method, or RET for current.
-k KEYS      Display the full documentation for the key sequence.
-K KEYS      Show the Emacs manual's section for the command bound to KEYS.
-l           Show last 300 input keystrokes (lossage).
 L LANG-ENV  Describes a specific language environment, or RET for current.
-m           Display documentation of current minor modes and current major mode,
-              including their special commands.
+l           Show last 300 input keystrokes (lossage).
 n           Display news of recent Emacs changes.
-o SYMBOL    Display the given function or variable's documentation and value.
-p TOPIC     Find packages matching a given topic keyword.
-P PACKAGE   Describe the given Emacs Lisp package.
-r           Display the Emacs manual in Info mode.
-R           Prompt for a manual and then display it in Info mode.
 s           Display contents of current syntax table, plus explanations.
-S SYMBOL    Show the section for the given symbol in the Info manual
-              for the programming language used in this buffer.
-t           Start the Emacs learn-by-doing tutorial.
-v VARIABLE  Display the given variable's documentation and value.
-w COMMAND   Display which keystrokes invoke the given command (where-is).
-.           Display any available local help at point in the echo area.
 
 C-a         Information about Emacs.
 C-c         Emacs copying permission (GNU General Public License).
@@ -245,7 +259,8 @@ 'help-for-help
 C-s         Search forward \"help window\".
 C-t         Emacs TODO list.
 C-w         Information on absence of warranty for GNU Emacs."
-  help-map)
+  help-map
+  help-for-help-mode)
 
 \f
 
-- 
2.30.0

RE: [External] : Proposal for an improved `help-for-help'

[Drew Adams]

It's good to discuss possible improvements to `C-h'.

(I do hope that, this time however, changes aren't
made before a wide discussion here, and preferably
some consensus is reached.  And at least this isn't
happening only in a bug thread.)
___

FWIW, I've never been a big fan of the help-for-help UI.

At a minimum, keys and commands mentioned should
have links to their full doc (or other info).

(In particular, if only keys are shown, they should
be linked to doc that shows their command bindings.)

Not as a _substitute_, but just as an example, using
`describe-keymap help-map' shows you each `C-h' key,
together with its command.  And the command, at least,
is linked to its doc string.

Again, I'm not saying that this is a _substitute_
for help-for-help.  I'm just saying that suggestions
such as yours should have links on things, at a
minimum.

RE: [External] : Proposal for an improved `help-for-help'

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> FWIW, I've never been a big fan of the help-for-help UI.
>
> At a minimum, keys and commands mentioned should
> have links to their full doc (or other info).

I don't see the need for such links in `help-for-help' in particular,
but I'm open to being convinced.  It might make sense if we can find a
good UI that is easy to understand and does not overwhelm.

What do you imagine this would look like?  For example, which keys would
a user press after `C-h C-h' to follow these added links?

(This might also be outside the scope of the reformatting I attempt
here.)

RE: [External] : Proposal for an improved `help-for-help'

[Drew Adams]

> > FWIW, I've never been a big fan of the help-for-help UI.
> >
> > At a minimum, keys and commands mentioned should
> > have links to their full doc (or other info).
> 
> I don't see the need for such links in `help-for-help' in particular,
> but I'm open to being convinced.  It might make sense if we can find a
> good UI that is easy to understand and does not overwhelm.
> 
> What do you imagine this would look like?  For example, which keys
> would a user press after `C-h C-h' to follow these added links?
> 
> (This might also be outside the scope of the reformatting I attempt
> here.)

I really haven't thought about it.  At all.

Off the top of my head, `C-h C-h' wouldn't
put you in a semi-modal dialog, showing you
some keys you can press to get particular
info (or keys to scroll for more such).

Instead, it could show you, and perhaps
select, a *Help* buffer that describes the
help system - keys with their descriptions,
and with links.

That is, after all, how you will interact
with help generally, once you get into it.
It's what each help command does: show you
some help info and (usually) provide some
links to more info.

The `C-h C-h' dialog seems a bit weird,
to me; that's all.  (I don't claim it's
weird for others.)
___

But again, I'm not proposing anything
particular as a replacement for the
`C-h C-h' dialog.  My point about that
was just that I've never been a big fan
of it.

That comment is really separate from my
feedback about your proposal, which was
to consider adding links.

Re: Proposal for an improved `help-for-help'

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> One of the usability complaints I've heard is that `help-for-help'
> (`C-h C-h') could be better organized.  I also think some colors could
> really help in making it easier to navigate.

Looks lot better to me.

> I have also attached a patch, but it's very rough.  I'm specifically
> having some trouble with font-locking: It works if I copy the contents
> of the " *Metahelp*" buffer and invoke the mode manually, but it will
> not work when I say `C-h C-h'.  Help with this is also welcome -- I'm
> probably missing something obvious.

Is using font locking the best option here, though?  What about just
inserting the text with the text properties already applied?

(Drew responds here that he doesn't much like how `C-h C-h' works -- and
I don't much like it either.  But that's a different discussion.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> (Drew responds here that he doesn't much like how `C-h C-h' works --
> and I don't much like it either.  But that's a different discussion.)

It's definitely a different discussion.
Apologies for possibly muddying the waters.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Is using font locking the best option here, though?  What about just
> inserting the text with the text properties already applied?

Yes, that would probably be better.

It's a little bit more work, but shouldn't be too bad.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 2060 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> One of the usability complaints I've heard is that `help-for-help'
>> (`C-h C-h') could be better organized.  I also think some colors could
>> really help in making it easier to navigate.
>
[...]
>
> Is using font locking the best option here, though?  What about just
> inserting the text with the text properties already applied?

OK, so here's what I came up with so far.

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.

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 ?'.

Thoughts welcome.

[-- Attachment #2: 0001-Colorize-keybindings-in-help.patch --]
[-- Type: text/x-diff, Size: 28125 bytes --]

From b7c2db02f46a44fac317a6c81efa001ecfea93a0 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 24 Feb 2021 01:18:13 +0100
Subject: [PATCH] Colorize keybindings in help

---
 lisp/faces.el      |   4 +
 lisp/help-fns.el   |  17 ++--
 lisp/help-macro.el | 226 ++++++++++++++++++++++-----------------------
 lisp/help.el       | 120 +++++++++++++-----------
 lisp/isearch.el    |   8 +-
 src/keymap.c       |  13 ++-
 6 files changed, 208 insertions(+), 180 deletions(-)

diff --git a/lisp/faces.el b/lisp/faces.el
index 90f11bbe3b..d6bab5e732 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2815,6 +2815,10 @@ help-argument-name
   "Face to highlight argument names in *Help* buffers."
   :group 'help)
 
+(defface help-key-binding '((t :weight semi-bold :foreground "ForestGreen"))
+  "Face for keybindings in *Help* buffers."
+  :group 'help)
+
 (defface glyphless-char
   '((((type tty)) :inherit underline)
     (((type pc)) :inherit escape-glyph)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 7244695094..8277bbdad1 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -466,12 +466,15 @@ help-fns--key-bindings
               ;; If lots of ordinary text characters run this command,
               ;; don't mention them one by one.
               (if (< (length non-modified-keys) 10)
-                  (princ (mapconcat #'key-description keys ", "))
+                  (with-current-buffer standard-output
+                    (insert (mapconcat #'help--key-description-fontified
+                                       keys ", ")))
                 (dolist (key non-modified-keys)
                   (setq keys (delq key keys)))
                 (if keys
                     (progn
-                      (princ (mapconcat #'key-description keys ", "))
+                      (princ (mapconcat #'help--key-description-fontified
+                                        keys ", "))
                       (princ ", and many ordinary text characters"))
                   (princ "many ordinary text characters"))))
             (when (or remapped keys non-modified-keys)
@@ -1825,10 +1828,12 @@ describe-mode
 	      (save-excursion
 		(re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
                                     nil t)
-		(help-xref-button 1 'help-function-def mode file-name)))))
-	(princ ":\n")
-	(princ (help-split-fundoc (documentation major-mode) nil 'doc))
-        (princ (help-fns--list-local-commands)))))
+                (help-xref-button 1 'help-function-def mode file-name)))))
+        (let ((fundoc (help-split-fundoc (documentation major-mode) nil 'doc)))
+          (with-current-buffer standard-output
+            (insert ":\n")
+            (insert fundoc)
+            (insert (help-fns--list-local-commands)))))))
   ;; For the sake of IELM and maybe others
   nil)
 
diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 791b10a878..4bb5e00906 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -92,119 +92,119 @@ make-help-screen
 with the key sequence that invoked FNAME.
 When FNAME finally does get a command, it executes that command
 and then returns."
-  (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
-    `(progn
-       (defun ,doc-fn () ,help-text nil)
-       (defun ,fname ()
-	 "Help command."
-	 (interactive)
-	 (let ((line-prompt
-		(substitute-command-keys ,help-line)))
-	   (when three-step-help
-	     (message "%s" line-prompt))
-	   (let* ((help-screen (documentation (quote ,doc-fn)))
-		  ;; We bind overriding-local-map for very small
-		  ;; sections, *excluding* where we switch buffers
-		  ;; and where we execute the chosen help command.
-		  (local-map (make-sparse-keymap))
-		  (new-minor-mode-map-alist minor-mode-map-alist)
-		  (prev-frame (selected-frame))
-		  config new-frame key char)
-	     (when (string-match "%THIS-KEY%" help-screen)
-	       (setq help-screen
-		     (replace-match (key-description
-				     (substring (this-command-keys) 0 -1))
-				    t t help-screen)))
-	     (unwind-protect
-		 (let ((minor-mode-map-alist nil))
-		   (setcdr local-map ,helped-map)
-		   (define-key local-map [t] 'undefined)
-		   ;; Make the scroll bar keep working normally.
-		   (define-key local-map [vertical-scroll-bar]
-		     (lookup-key global-map [vertical-scroll-bar]))
-		   (if three-step-help
-		       (progn
-			 (setq key (let ((overriding-local-map local-map))
-				     (read-key-sequence nil)))
-			 ;; Make the HELP key translate to C-h.
-			 (if (lookup-key function-key-map key)
-			     (setq key (lookup-key function-key-map key)))
-			 (setq char (aref key 0)))
-		     (setq char ??))
-		   (when (or (eq char ??) (eq char help-char)
-			     (memq char help-event-list))
-		     (setq config (current-window-configuration))
-		     (pop-to-buffer " *Metahelp*" nil t)
-		     (and (fboundp 'make-frame)
-			  (not (eq (window-frame)
-				   prev-frame))
-			  (setq new-frame (window-frame)
-				config nil))
-		     (setq buffer-read-only nil)
-		     (let ((inhibit-read-only t))
-		       (erase-buffer)
-		       (insert help-screen))
-		     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-		       (help-mode)
-		       (setq new-minor-mode-map-alist minor-mode-map-alist))
-		     (goto-char (point-min))
-		     (while (or (memq char (append help-event-list
-						   (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
-				(eq (car-safe char) 'switch-frame)
-				(equal key "\M-v"))
-		       (condition-case nil
-			   (cond
-			    ((eq (car-safe char) 'switch-frame)
-			     (handle-switch-frame char))
-			    ((memq char '(?\C-v ?\s))
-			     (scroll-up))
-			    ((or (memq char '(?\177 ?\M-v delete backspace))
-				 (equal key "\M-v"))
-			     (scroll-down)))
-			 (error nil))
-		       (let ((cursor-in-echo-area t)
-			     (overriding-local-map local-map))
-			 (setq key (read-key-sequence
-				    (format "Type one of the options listed%s: "
-					    (if (pos-visible-in-window-p
-						 (point-max))
-						"" ", or SPACE or DEL to scroll")))
-			       char (aref key 0)))
-
-		       ;; If this is a scroll bar command, just run it.
-		       (when (eq char 'vertical-scroll-bar)
-			 (command-execute (lookup-key local-map key) nil key))))
-		   ;; We don't need the prompt any more.
-		   (message "")
-		   ;; Mouse clicks are not part of the help feature,
-		   ;; so reexecute them in the standard environment.
-		   (if (listp char)
-		       (setq unread-command-events
-			     (cons char unread-command-events)
-			     config nil)
-		     (let ((defn (lookup-key local-map key)))
-		       (if defn
-			   (progn
-			     (when config
-			       (set-window-configuration config)
-			       (setq config nil))
-			     ;; Temporarily rebind `minor-mode-map-alist'
-			     ;; to `new-minor-mode-map-alist' (Bug#10454).
-			     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-			       ;; `defn' must make sure that its frame is
-			       ;; selected, so we won't iconify it below.
-			       (call-interactively defn))
-			     (when new-frame
-			       ;; Do not iconify the selected frame.
-			       (unless (eq new-frame (selected-frame))
-				 (iconify-frame new-frame))
-			       (setq new-frame nil)))
-			 (ding)))))
-	       (when config
-		 (set-window-configuration config))
-	       (when new-frame
-		 (iconify-frame new-frame))
-	       (setq minor-mode-map-alist new-minor-mode-map-alist))))))))
+  `(defun ,fname ()
+     "Help command."
+     (interactive)
+     (let ((line-prompt
+            (substitute-command-keys ,help-line)))
+       (when three-step-help
+         (message "%s" line-prompt))
+       (let* ((help-screen ,help-text)
+              ;; We bind overriding-local-map for very small
+              ;; sections, *excluding* where we switch buffers
+              ;; and where we execute the chosen help command.
+              (local-map (make-sparse-keymap))
+              (new-minor-mode-map-alist minor-mode-map-alist)
+              (prev-frame (selected-frame))
+              config new-frame key char)
+         (when (string-match "%THIS-KEY%" help-screen)
+           (setq help-screen
+                 (replace-match (propertize
+                                 (key-description
+                                  (substring (this-command-keys) 0 -1))
+                                 'font-lock-face 'help-key-binding
+                                 'face 'help-key-binding)
+                                t t help-screen)))
+         (unwind-protect
+             (let ((minor-mode-map-alist nil))
+               (setcdr local-map ,helped-map)
+               (define-key local-map [t] 'undefined)
+               ;; Make the scroll bar keep working normally.
+               (define-key local-map [vertical-scroll-bar]
+                 (lookup-key global-map [vertical-scroll-bar]))
+               (if three-step-help
+                   (progn
+                     (setq key (let ((overriding-local-map local-map))
+                                 (read-key-sequence nil)))
+                     ;; Make the HELP key translate to C-h.
+                     (if (lookup-key function-key-map key)
+                         (setq key (lookup-key function-key-map key)))
+                     (setq char (aref key 0)))
+                 (setq char ??))
+               (when (or (eq char ??) (eq char help-char)
+                         (memq char help-event-list))
+                 (setq config (current-window-configuration))
+                 (pop-to-buffer " *Metahelp*" nil t)
+                 (and (fboundp 'make-frame)
+                      (not (eq (window-frame)
+                               prev-frame))
+                      (setq new-frame (window-frame)
+                            config nil))
+                 (setq buffer-read-only nil)
+                 (let ((inhibit-read-only t))
+                   (erase-buffer)
+                   (insert (substitute-command-keys help-screen)))
+                 (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                   (help-mode)
+                   (setq new-minor-mode-map-alist minor-mode-map-alist))
+                 (goto-char (point-min))
+                 (while (or (memq char (append help-event-list
+                                               (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
+                            (eq (car-safe char) 'switch-frame)
+                            (equal key "\M-v"))
+                   (condition-case nil
+                       (cond
+                        ((eq (car-safe char) 'switch-frame)
+                         (handle-switch-frame char))
+                        ((memq char '(?\C-v ?\s))
+                         (scroll-up))
+                        ((or (memq char '(?\177 ?\M-v delete backspace))
+                             (equal key "\M-v"))
+                         (scroll-down)))
+                     (error nil))
+                   (let ((cursor-in-echo-area t)
+                         (overriding-local-map local-map))
+                     (setq key (read-key-sequence
+                                (format "Type one of the options listed%s: "
+                                        (if (pos-visible-in-window-p
+                                             (point-max))
+                                            "" ", or SPACE or DEL to scroll")))
+                           char (aref key 0)))
+
+                   ;; If this is a scroll bar command, just run it.
+                   (when (eq char 'vertical-scroll-bar)
+                     (command-execute (lookup-key local-map key) nil key))))
+               ;; We don't need the prompt any more.
+               (message "")
+               ;; Mouse clicks are not part of the help feature,
+               ;; so reexecute them in the standard environment.
+               (if (listp char)
+                   (setq unread-command-events
+                         (cons char unread-command-events)
+                         config nil)
+                 (let ((defn (lookup-key local-map key)))
+                   (if defn
+                       (progn
+                         (when config
+                           (set-window-configuration config)
+                           (setq config nil))
+                         ;; Temporarily rebind `minor-mode-map-alist'
+                         ;; to `new-minor-mode-map-alist' (Bug#10454).
+                         (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                           ;; `defn' must make sure that its frame is
+                           ;; selected, so we won't iconify it below.
+                           (call-interactively defn))
+                         (when new-frame
+                           ;; Do not iconify the selected frame.
+                           (unless (eq new-frame (selected-frame))
+                             (iconify-frame new-frame))
+                           (setq new-frame nil)))
+                     (ding)))))
+           (when config
+             (set-window-configuration config))
+           (when new-frame
+             (iconify-frame new-frame))
+           (setq minor-mode-map-alist new-minor-mode-map-alist))))))
 
 (provide 'help-macro)
 
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..0247f08706 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -104,8 +104,8 @@ help-map
     (define-key map "R" 'info-display-manual)
     (define-key map "s" 'describe-syntax)
     (define-key map "t" 'help-with-tutorial)
-    (define-key map "w" 'where-is)
     (define-key map "v" 'describe-variable)
+    (define-key map "w" 'where-is)
     (define-key map "q" 'help-quit)
     map)
   "Keymap for characters following the Help key.")
@@ -199,52 +199,52 @@ 'help-for-help
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
 \(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
 
-a PATTERN   Show commands whose name matches the PATTERN (a list of words
+\\[apropos-command] PATTERN   Show commands whose name matches the PATTERN (a list of words
               or a regexp).  See also the `apropos' command.
-b           Display all key bindings.
-c KEYS      Display the command name run by the given key sequence.
-C CODING    Describe the given coding system, or RET for current ones.
-d PATTERN   Show a list of functions, variables, and other items whose
+\\[describe-bindings]           Display all key bindings.
+\\[describe-key-briefly] KEYS      Display the command name run by the given key sequence.
+\\[describe-coding-system] CODING    Describe the given coding system, or RET for current ones.
+\\[apropos-documentation] PATTERN   Show a list of functions, variables, and other items whose
               documentation matches the PATTERN (a list of words or a regexp).
-e           Go to the *Messages* buffer which logs echo-area messages.
-f FUNCTION  Display documentation for the given function.
-F COMMAND   Show the Emacs manual's section that describes the command.
-g           Display information about the GNU project.
-h           Display the HELLO file which illustrates various scripts.
-i           Start the Info documentation reader: read included manuals.
-I METHOD    Describe a specific input method, or RET for current.
-k KEYS      Display the full documentation for the key sequence.
-K KEYS      Show the Emacs manual's section for the command bound to KEYS.
-l           Show last 300 input keystrokes (lossage).
-L LANG-ENV  Describes a specific language environment, or RET for current.
-m           Display documentation of current minor modes and current major mode,
-              including their special commands.
-n           Display news of recent Emacs changes.
-o SYMBOL    Display the given function or variable's documentation and value.
-p TOPIC     Find packages matching a given topic keyword.
-P PACKAGE   Describe the given Emacs Lisp package.
-r           Display the Emacs manual in Info mode.
-R           Prompt for a manual and then display it in Info mode.
-s           Display contents of current syntax table, plus explanations.
-S SYMBOL    Show the section for the given symbol in the Info manual
+\\[view-echo-area-messages]           Go to the *Messages* buffer which logs echo-area messages.
+\\[describe-function] FUNCTION  Display documentation for the given function.
+\\[Info-goto-emacs-command-node] COMMAND   Show the Emacs manual's section that describes the command.
+\\[describe-gnu-project]           Display information about the GNU project.
+\\[view-hello-file]           Display the HELLO file which illustrates various scripts.
+\\[info]           Start the Info documentation reader: read included manuals.
+\\[describe-input-method] METHOD    Describe a specific input method, or RET for current.
+\\[describe-key] KEYS      Display the full documentation for the key sequence.
+\\[Info-goto-emacs-key-command-node] KEYS      Show the Emacs manual's section for the command bound to KEYS.
+\\[view-lossage]           Show last 300 input keystrokes (lossage).
+\\[describe-language-environment] LANG-ENV  Describes a specific language environment, or RET for current.
+\\[describe-mode]           Display documentation of current minor modes and current major mode,
+             including their special commands.
+\\[view-emacs-news]           Display news of recent Emacs changes.
+\\[describe-symbol] SYMBOL    Display the given function or variable's documentation and value.
+\\[finder-by-keyword] TOPIC     Find packages matching a given topic keyword.
+\\[describe-package] PACKAGE   Describe the given Emacs Lisp package.
+\\[info-emacs-manual]           Display the Emacs manual in Info mode.
+\\[info-display-manual]           Prompt for a manual and then display it in Info mode.
+\\[describe-syntax]           Display contents of current syntax table, plus explanations.
+\\[info-lookup-symbol] SYMBOL    Show the section for the given symbol in the Info manual
               for the programming language used in this buffer.
-t           Start the Emacs learn-by-doing tutorial.
-v VARIABLE  Display the given variable's documentation and value.
-w COMMAND   Display which keystrokes invoke the given command (where-is).
-.           Display any available local help at point in the echo area.
-
-C-a         Information about Emacs.
-C-c         Emacs copying permission (GNU General Public License).
-C-d         Instructions for debugging GNU Emacs.
-C-e         External packages and information about Emacs.
-C-f         Emacs FAQ.
+\\[help-with-tutorial]           Start the Emacs learn-by-doing tutorial.
+\\[describe-variable] VARIABLE  Display the given variable's documentation and value.
+\\[where-is] COMMAND   Display which keystrokes invoke the given command (where-is).
+\\[display-local-help]           Display any available local help at point in the echo area.
+
+\\[about-emacs]         Information about Emacs.
+\\[describe-copying]         Emacs copying permission (GNU General Public License).
+\\[view-emacs-debugging]         Instructions for debugging GNU Emacs.
+\\[view-external-packages]         External packages and information about Emacs.
+\\[view-emacs-FAQ]         Emacs FAQ.
 C-m         How to order printed Emacs manuals.
 C-n         News of recent Emacs changes.
-C-o         Emacs ordering and distribution information.
-C-p         Info about known Emacs problems.
-C-s         Search forward \"help window\".
-C-t         Emacs TODO list.
-C-w         Information on absence of warranty for GNU Emacs."
+\\[describe-distribution]         Emacs ordering and distribution information.
+\\[view-emacs-problems]         Info about known Emacs problems.
+\\[search-forward-help-for-help]         Search forward \"help window\".
+\\[view-emacs-todo]         Emacs TODO list.
+\\[describe-no-warranty]         Information on absence of warranty for GNU Emacs."
   help-map)
 
 \f
@@ -492,6 +492,15 @@ view-lossage
 \f
 ;; Key bindings
 
+(defun help--key-description-fontified (keys &optional prefix)
+  "Like `key-description' but add face for \"*Help*\" buffers."
+  ;; We add both the `font-lock-face' and `face' properties here, as this
+  ;; seems to be the only way to get this to work reliably in any
+  ;; buffer.
+  (propertize (key-description keys prefix)
+              'font-lock-face 'help-key-binding
+              'face 'help-key-binding))
+
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
 The keys are displayed in order of precedence.
@@ -511,7 +520,6 @@ describe-bindings
     (with-current-buffer (help-buffer)
       (describe-buffer-bindings buffer prefix))))
 
-;; This function used to be in keymap.c.
 (defun describe-bindings-internal (&optional menus prefix)
   "Show a list of all defined keys, and their definitions.
 We put that list in a buffer, and display the buffer.
@@ -559,7 +567,8 @@ where-is
       (let* ((remapped (command-remapping symbol))
 	     (keys (where-is-internal
 		    symbol overriding-local-map nil nil remapped))
-	     (keys (mapconcat 'key-description keys ", "))
+             (keys (mapconcat #'help--key-description-fontified
+                              keys ", "))
 	     string)
 	(setq string
 	      (if insert
@@ -587,11 +596,11 @@ where-is
   nil)
 
 (defun help-key-description (key untranslated)
-  (let ((string (key-description key)))
+  (let ((string (help--key-description-fontified key)))
     (if (or (not untranslated)
 	    (and (eq (aref untranslated 0) ?\e) (not (eq (aref key 0) ?\e))))
 	string
-      (let ((otherstring (key-description untranslated)))
+      (let ((otherstring (help--key-description-fontified untranslated)))
 	(if (equal string otherstring)
 	    string
 	  (format "%s (translated from %s)" string otherstring))))))
@@ -1053,12 +1062,14 @@ substitute-command-keys
                                 (where-is-internal fun keymap t))))
                   (if (not key)
                       ;; Function is not on any key.
-                      (progn (insert "M-x ")
+                      (progn (insert (propertize "M-x "
+                                                 'font-lock-face 'help-key-binding
+                                                 'face 'help-key-binding))
                              (goto-char (+ end-point 3))
                              (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (key-description key)))))
+                    (insert (help--key-description-fontified key)))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
@@ -1172,7 +1183,7 @@ describe-map-tree
                           (concat title
                                   (if prefix
                                       (concat " Starting With "
-                                              (key-description prefix)))
+                                              (help--key-description-fontified prefix)))
                                   ":\n"))
                       "key             binding\n"
                       "---             -------\n")))
@@ -1244,7 +1255,8 @@ help--describe-translation
   (cond ((symbolp definition)
          (insert (symbol-name definition) "\n"))
         ((or (stringp definition) (vectorp definition))
-         (insert (key-description definition nil) "\n"))
+         (insert (help--key-description-fontified definition nil)
+                 "\n"))
         ((keymapp definition)
          (insert "Prefix Command\n"))
         (t (insert "??\n"))))
@@ -1351,9 +1363,9 @@ describe-map
               (setq end (caar vect))))
           ;; Now START .. END is the range to describe next.
           ;; Insert the string to describe the event START.
-          (insert (key-description (vector start) prefix))
+          (insert (help--key-description-fontified (vector start) prefix))
           (when (not (eq start end))
-            (insert " .. " (key-description (vector end) prefix)))
+            (insert " .. " (help--key-description-fontified (vector end) prefix)))
           ;; Print a description of the definition of this character.
           ;; Called function will take care of spacing out far enough
           ;; for alignment purposes.
@@ -1420,7 +1432,7 @@ describe-map
 ;;             (setq first nil))
 ;;           (when (and prefix (> (length prefix) 0))
 ;;             (insert (format "%s" prefix)))
-;;           (insert (key-description (vector start-idx) prefix))
+;;           (insert (help--key-description-fontified (vector start-idx) prefix))
 ;;           ;; Find all consecutive characters or rows that have the
 ;;           ;; same definition.
 ;;           (while (equal (keymap--get-keyelt (aref vector (1+ idx)) nil)
@@ -1433,7 +1445,7 @@ describe-map
 ;;             (insert " .. ")
 ;;             (when (and prefix (> (length prefix) 0))
 ;;               (insert (format "%s" prefix)))
-;;             (insert (key-description (vector idx) prefix)))
+;;             (insert (help--key-description-fontified (vector idx) prefix)))
 ;;           (if transl
 ;;               (help--describe-translation definition)
 ;;             (help--describe-command definition))
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 8266c4b7a0..b691673c9f 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -460,11 +460,11 @@ isearch-help-map
 (make-help-screen isearch-help-for-help-internal
   (purecopy "Type a help option: [bkm] or ?")
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
-\(Type \\<help-map>\\[help-quit] to exit the Help command.)
+\(Type \\<isearch-help-map>\\[help-quit] to exit the Help command.)
 
-b           Display all Isearch key bindings.
-k KEYS      Display full documentation of Isearch key sequence.
-m           Display documentation of Isearch mode.
+\\[isearch-describe-bindings]           Display all Isearch key bindings.
+\\[isearch-describe-key] KEYS      Display full documentation of Isearch key sequence.
+\\[isearch-describe-mode]           Display documentation of Isearch mode.
 
 You can't type here other help keys available in the global help map,
 but outside of this help window when you type them in Isearch mode,
diff --git a/src/keymap.c b/src/keymap.c
index 782931fadf..8df037bffc 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -3021,7 +3021,10 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
       if (!NILP (elt_prefix))
 	insert1 (elt_prefix);
 
-      insert1 (Fkey_description (kludge, prefix));
+      Lisp_Object desc = Fkey_description (kludge, prefix);
+      if (keymap_p)
+	desc = CALLN (Fpropertize, desc, Qfont_lock_face, Qhelp_key_binding);
+      insert1 (desc);
 
       /* Find all consecutive characters or rows that have the same
 	 definition.  But, if VECTOR is a char-table, we had better
@@ -3071,7 +3074,10 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
 	  if (!NILP (elt_prefix))
 	    insert1 (elt_prefix);
 
-	  insert1 (Fkey_description (kludge, prefix));
+	  Lisp_Object desc = Fkey_description (kludge, prefix);
+	  if (keymap_p)
+	    desc = CALLN (Fpropertize, desc, Qfont_lock_face, Qhelp_key_binding);
+	  insert1 (desc);
 	}
 
       /* Print a description of the definition of this character.
@@ -3107,7 +3113,8 @@ syms_of_keymap (void)
 {
   DEFSYM (Qkeymap, "keymap");
   DEFSYM (Qdescribe_map_tree, "describe-map-tree");
-
+  DEFSYM (Qfont_lock_face, "font-lock-face");
+  DEFSYM (Qhelp_key_binding, "help-key-binding");
   DEFSYM (Qkeymap_canonicalize, "keymap-canonicalize");
 
   /* Now we are ready to set up this property, so we can
-- 
2.30.0

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

[Drew Adams]

> 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.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> 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':

I admit that I have never used any of your libraries.

But I have seen Bug#8951 and the code you presented there.

> 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.

I'm not convinced of that.  There will be many links all over the place,
sometimes many links to the same place.  It risks cluttering the help
screen too much, whereas the effect you see with my patch is more
subtle.  I also don't know of too many examples where links will be
highly useful.

Still, I'm not writing off the idea completely, I just don't currently
see how to balance the drawbacks.

>> 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.

Care to elaborate?  AFAICT, messages do not currently display
keybindings in a different face.

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

The work is mostly to identify the places where we output keys and
ensure the strings get the correct face properties applied to them.
Therefore, 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.

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

[Drew Adams]

> > 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':
> 
> I admit that I have never used any of your libraries.
> 
> But I have seen Bug#8951 and the code you presented there.
> 
> > 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.
> 
> I'm not convinced of that.  There will be many links all
> over the place, sometimes many links to the same place.

Why do you think so?  I haven't seen that.

> It risks cluttering the help screen too much,
> whereas the effect you see with my patch is
> more subtle.

What makes you think your highlighting is more
subtle?  And more subtle than what?  You just
said that you've never even tried help-fns+.el.

> 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.

> 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.

> > That's already been solved.
> 
> Care to elaborate?  AFAICT, messages do not currently 
> display keybindings in a different face.

I meant that `...' for keys in *Help* is solved.

And the key listings you speak of there (e.g.
C-h C-h), which do _not_ use `...', can be dealt
with separately.  That help (e.g. `C-h h') is
constructed individually - it doesn't use doc
strings or `substitute-command-keys'.

> > You can start with the code in help-fns+.el.
> > Or you can start from scratch.  But DTRT.
> 
> The work is mostly to identify the places where we output keys and
> ensure the strings get the correct face properties applied to them.
> Therefore, 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.

My point is that it's more helpful to users to
put links on those keys, in addition to keys
wrapped with `...'.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> What makes you think your highlighting is more
> subtle?  And more subtle than what?  You just
> said that you've never even tried help-fns+.el.

OK, this is a fair point.  I will try help-fns+.el.

>> 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".

>> 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.

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...)

>> The work is mostly to identify the places where we output keys and
>> ensure the strings get the correct face properties applied to them.
>> Therefore, 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.

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.  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.

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.]

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Thu, 25 Feb 2021 06:43:09 +0000
> Cc: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> 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.

Please don't misrepresent what happens in these discussions.  Those
arguments were not ignored; expressing disagreement doesn't mean
ignoring.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Actually no, there was nothing you needed to do, for
> `describe-keymap'.  But you wanted different behavior,
> so you changed it slightly.  Fine.

There are all kinds of adaptions to make before putting things on master
besides just copying it from some library: making sure the code conforms
to our style (yours doesn't), does not have features we do not need
(support for your other "foo+" libraries), adding proper documentation
(yes, we need to update the manual as well), adding NEWS, discussing the
details, testing, etc.

I have no idea why you dismiss that work as "nothing to do".  If it is
so easy and so little work, please start sending patches instead of just
linking some library.  Thanks in advance.

> I don't care if you use my `describe-command' or
> whatever.
[...]
> But what do I know?
>
> [NIH?

Oh, please.  Here is the definition of `describe-command':

    (defun describe-command (command)
      (interactive (help-fns--describe-function-or-command-prompt 'is-command))
      (describe-function command))

Yeah, I chose not to "re-use" anything here.  Sorry for suffering from
NIH.

I would suggest you actually study my patch, and then point out any
opportunities for re-using your code.  I have now studied your code and
I see *no* such opportunities.  (This was a fully expected result, for
the reasons I have already provided.)

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

[Basil L. Contovounesios]

Stefan Kangas <stefan@marxist.se> writes:

> Thoughts welcome.

Thanks, just some questions from me.

[...]

> +(defface help-key-binding '((t :weight semi-bold :foreground "ForestGreen"))
> +  "Face for keybindings in *Help* buffers."
> +  :group 'help)

Missing :version?

> diff --git a/lisp/help-fns.el b/lisp/help-fns.el
> index 7244695094..8277bbdad1 100644
> --- a/lisp/help-fns.el
> +++ b/lisp/help-fns.el
> @@ -466,12 +466,15 @@ help-fns--key-bindings
>                ;; If lots of ordinary text characters run this command,
>                ;; don't mention them one by one.
>                (if (< (length non-modified-keys) 10)
> -                  (princ (mapconcat #'key-description keys ", "))
> +                  (with-current-buffer standard-output
> +                    (insert (mapconcat #'help--key-description-fontified
> +                                       keys ", ")))

Why is insert needed in place of princ here, but not below?

>                  (dolist (key non-modified-keys)
>                    (setq keys (delq key keys)))
>                  (if keys
>                      (progn
> -                      (princ (mapconcat #'key-description keys ", "))
> +                      (princ (mapconcat #'help--key-description-fontified
> +                                        keys ", "))

[...]

> +                 (replace-match (propertize
> +                                 (key-description
> +                                  (substring (this-command-keys) 0 -1))
> +                                 'font-lock-face 'help-key-binding
> +                                 'face 'help-key-binding)

Why not use help--key-description-fontified here?

-- 
Basil

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

[Stefan Kangas]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

>> +(defface help-key-binding '((t :weight semi-bold :foreground "ForestGreen"))
>> +  "Face for keybindings in *Help* buffers."
>> +  :group 'help)
>
> Missing :version?

Fixed.

>> diff --git a/lisp/help-fns.el b/lisp/help-fns.el
>> index 7244695094..8277bbdad1 100644
>> --- a/lisp/help-fns.el
>> +++ b/lisp/help-fns.el
>> @@ -466,12 +466,15 @@ help-fns--key-bindings
>>                ;; If lots of ordinary text characters run this command,
>>                ;; don't mention them one by one.
>>                (if (< (length non-modified-keys) 10)
>> -                  (princ (mapconcat #'key-description keys ", "))
>> +                  (with-current-buffer standard-output
>> +                    (insert (mapconcat #'help--key-description-fontified
>> +                                       keys ", ")))
>
> Why is insert needed in place of princ here, but not below?

We do need `insert' here.  Fixed.

>>                  (dolist (key non-modified-keys)
>>                    (setq keys (delq key keys)))
>>                  (if keys
>>                      (progn
>> -                      (princ (mapconcat #'key-description keys ", "))
>> +                      (princ (mapconcat #'help--key-description-fontified
>> +                                        keys ", "))
>
> [...]
>
>> +                 (replace-match (propertize
>> +                                 (key-description
>> +                                  (substring (this-command-keys) 0 -1))
>> +                                 'font-lock-face 'help-key-binding
>> +                                 'face 'help-key-binding)
>
> Why not use help--key-description-fontified here?

Using it would introduce a circular dependency between help-macro.el and
help.el.

Thanks for your comments.

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

[Basil L. Contovounesios]

Stefan Kangas <stefan@marxist.se> writes:

> "Basil L. Contovounesios" <contovob@tcd.ie> writes:
>>
>>> +                 (replace-match (propertize
>>> +                                 (key-description
>>> +                                  (substring (this-command-keys) 0 -1))
>>> +                                 'font-lock-face 'help-key-binding
>>> +                                 'face 'help-key-binding)
>>
>> Why not use help--key-description-fontified here?
>
> Using it would introduce a circular dependency between help-macro.el and
> help.el.

How would it do that given that neither make-help-screen nor the defun
it expands to is used within help-macro.el?

-- 
Basil

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

[Stefan Kangas]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

>> Using it would introduce a circular dependency between help-macro.el and
>> help.el.
>
> How would it do that given that neither make-help-screen nor the defun
> it expands to is used within help-macro.el?

Oops, that is true of course, it won't be cyclical.  I'll change it.

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> 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.

I think this is a very good idea.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 23 Feb 2021 19:40:07 -0600
> Cc: emacs-devel@gnu.org
> 
> So I have made `substitute-command-keys' add this face unconditionally
> to keys.
> 
> 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.

What about tooltips? we run their text through
substitute-command-keys, AFAIR, but the tooltip's faces need to use
smaller fonts.  So at the very least this face should be documented to
affect only some of the face attributes, not all of them (which is
generally not such a good idea, as it confuses users).

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> What about tooltips? we run their text through
> substitute-command-keys, AFAIR, but the tooltip's faces need to use
> smaller fonts.  So at the very least this face should be documented to
> affect only some of the face attributes, not all of them (which is
> generally not such a good idea, as it confuses users).

This doesn't have any effect on the appearance of the tooltip, neither
in GTK or Lucid.  Perhaps because it is all overwritten with the
`tooltip' face in `tooltip'-show?  Or am I missing something?

BTW, it doesn't seem to have any effect to customize the `tooltip' face
here.  Is it supposed to change the look of the tooltip in GTK?

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 24 Feb 2021 20:26:46 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What about tooltips? we run their text through
> > substitute-command-keys, AFAIR, but the tooltip's faces need to use
> > smaller fonts.  So at the very least this face should be documented to
> > affect only some of the face attributes, not all of them (which is
> > generally not such a good idea, as it confuses users).
> 
> This doesn't have any effect on the appearance of the tooltip, neither
> in GTK or Lucid.

In GTK, I'm not surprised, but I thought with Lucid Emacs itself pops
up tooltips.

What exactly did you try?  The easiest test is to put a help-echo
property on some text in Fundamental mode, then hover the mouse
pointer over that text.

> Perhaps because it is all overwritten with the
> `tooltip' face in `tooltip'-show?

No, that uses 'propertize', which _adds_ text properties.

> BTW, it doesn't seem to have any effect to customize the `tooltip' face
> here.  Is it supposed to change the look of the tooltip in GTK?

Not in GTK, I think, not unless you set x-gtk-use-system-tooltips to a
nil value.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> In GTK, I'm not surprised, but I thought with Lucid Emacs itself pops
> up tooltips.
>
> What exactly did you try?  The easiest test is to put a help-echo
> property on some text in Fundamental mode, then hover the mouse
> pointer over that text.

0. emacs -Q
1. M-x fundamental-mode RET
2. M-: (insert (propertize "foo" 'help-echo "foo \\[forward-line]")) RET

No visible effect on the tooltip --with-x-toolkit={gtk,lucid,athena,no}.

(With GTK, I also tried with x-gtk-use-system-tooltips set to nil.)

>> BTW, it doesn't seem to have any effect to customize the `tooltip' face
>> here.  Is it supposed to change the look of the tooltip in GTK?
>
> Not in GTK, I think, not unless you set x-gtk-use-system-tooltips to a
> nil value.

Ah, right.  I will add that to the docstring of the `tooltip' face.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 25 Feb 2021 10:45:42 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> 0. emacs -Q
> 1. M-x fundamental-mode RET
> 2. M-: (insert (propertize "foo" 'help-echo "foo \\[forward-line]")) RET
> 
> No visible effect on the tooltip --with-x-toolkit={gtk,lucid,athena,no}.

And the face for keys is defined how?

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> 0. emacs -Q
>> 1. M-x fundamental-mode RET
>> 2. M-: (insert (propertize "foo" 'help-echo "foo \\[forward-line]")) RET
>>
>> No visible effect on the tooltip --with-x-toolkit={gtk,lucid,athena,no}.
>
> And the face for keys is defined how?

(defface help-key-binding '((t :foreground "RoyalBlue3"))
  "Face for keybindings in *Help* buffers."
  :version "28.1"
  :group 'help)

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 25 Feb 2021 12:48:37 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> >> 2. M-: (insert (propertize "foo" 'help-echo "foo \\[forward-line]")) RET
> >>
> >> No visible effect on the tooltip --with-x-toolkit={gtk,lucid,athena,no}.
> >
> > And the face for keys is defined how?
> 
> (defface help-key-binding '((t :foreground "RoyalBlue3"))
>   "Face for keybindings in *Help* buffers."
>   :version "28.1"
>   :group 'help)

Ah, okay: you are putting the 'face' property, but so does
'tooltip-show'.  So yes, the latter one overrides the former one.

So I guess we will need to change the design of this to avoid
overriding the whole face of a tooltip, or maybe add some special code
to help_echo_substitute_command_keys.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Ah, okay: you are putting the 'face' property, but so does
> 'tooltip-show'.  So yes, the latter one overrides the former one.
>
> So I guess we will need to change the design of this to avoid
> overriding the whole face of a tooltip, or maybe add some special code
> to help_echo_substitute_command_keys.

Oh, okay.  I actually thought your concern was the opposite case here.

I think it is okay that tooltips do not use the `help-key-binding' face.
That seems in line with what other software does for tooltips, I
believe.  But I could be wrong.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 25 Feb 2021 13:47:07 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> I think it is okay that tooltips do not use the `help-key-binding' face.

If you are willing to give up on key sequences in tooltips, then why
do it in substitute-command-keys?

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I think it is okay that tooltips do not use the `help-key-binding' face.
>
> If you are willing to give up on key sequences in tooltips, then why
> do it in substitute-command-keys?

I have thought a bit more about this and I can see that supporting this
in tooltips could be useful.  So I'll look into it.

> So I guess we will need to change the design of this to avoid overriding
> the whole face of a tooltip, or maybe add some special code to
> help_echo_substitute_command_keys.

Could we just use `add-face-text-property' here, perhaps?

It seems to do what we want:

    (let ((foo "x") bar)
      (add-face-text-property 0 (length foo) 'bold nil foo)
      (setq bar (concat "y" foo "y"))
      (add-face-text-property 0 (length bar) 'italic nil bar)
      bar)

    => #("yxy" 0 1 (face italic) 1 2 (face (italic bold)) 2 3 (face italic))

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 4 Mar 2021 00:24:14 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> > So I guess we will need to change the design of this to avoid overriding
> > the whole face of a tooltip, or maybe add some special code to
> > help_echo_substitute_command_keys.
> 
> Could we just use `add-face-text-property' here, perhaps?
> 
> It seems to do what we want:
> 
>     (let ((foo "x") bar)
>       (add-face-text-property 0 (length foo) 'bold nil foo)
>       (setq bar (concat "y" foo "y"))
>       (add-face-text-property 0 (length bar) 'italic nil bar)
>       bar)
> 
>     => #("yxy" 0 1 (face italic) 1 2 (face (italic bold)) 2 3 (face italic))

That's because you add a property which was unspecified by the
original face.  But in the tooltip case, the function tooltip-show
propertizes the entire text it receives with the 'tooltip' face, so
any face attributes in the text that are also specified by the
'tooltip' face will be overwritten.  So, for example, if the tooltip
text had a :background attribute, that attribute would be overwritten
by the background color of the 'tooltip' face.  Isn't that what you
see?

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1754 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> Could we just use `add-face-text-property' here, perhaps?
>>
>> It seems to do what we want:
>>
>>     (let ((foo "x") bar)
>>       (add-face-text-property 0 (length foo) 'bold nil foo)
>>       (setq bar (concat "y" foo "y"))
>>       (add-face-text-property 0 (length bar) 'italic nil bar)
>>       bar)
>>
>>     => #("yxy" 0 1 (face italic) 1 2 (face (italic bold)) 2 3 (face italic))
>
> That's because you add a property which was unspecified by the
> original face.  But in the tooltip case, the function tooltip-show
> propertizes the entire text it receives with the 'tooltip' face, so
> any face attributes in the text that are also specified by the
> 'tooltip' face will be overwritten.  So, for example, if the tooltip
> text had a :background attribute, that attribute would be overwritten
> by the background color of the 'tooltip' face.  Isn't that what you
> see?

But that just comes down to which face takes priority, right?  So if we
we would need to set the APPEND argument of `add-face-text-property' to
t.

See the attached latest version of the patch, which seems to work as
you'd expect: the `help-key-binding' face overrides any attributes in
the `tooltip' face (tested using --with-x-toolkit={no,lucid}).

The interesting part for tooltips is:

modified   lisp/tooltip.el
@@ -248,7 +248,8 @@ tooltip-show
 	    (setf (alist-get 'border-color params) fg))
 	  (when (stringp bg)
 	    (setf (alist-get 'background-color params) bg))
-	  (x-show-tip (propertize text 'face 'tooltip)
+          (add-face-text-property 0 (length text) 'tooltip t text)
+          (x-show-tip text
 		      (selected-frame)
 		      params

Unless I am missing something, I think this is what we want here.

[-- Attachment #2: 0001-Colorize-keybindings-in-help.patch --]
[-- Type: text/x-diff, Size: 32000 bytes --]

From b772b42ee39f4595cf6df21d9c0b7694771f1cb6 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 24 Feb 2021 01:18:13 +0100
Subject: [PATCH] Colorize keybindings in help

---
 etc/NEWS           |   3 +
 lisp/faces.el      |   5 +
 lisp/help-fns.el   |  21 +++--
 lisp/help-macro.el | 223 ++++++++++++++++++++++-----------------------
 lisp/help.el       | 139 +++++++++++++++-------------
 lisp/isearch.el    |   8 +-
 lisp/tooltip.el    |   3 +-
 src/keymap.c       |  27 +++++-
 8 files changed, 239 insertions(+), 190 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 3522fce03a..92705d2a7b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -911,6 +911,9 @@ skipped.
 
 ** Help
 
+---
+*** Keybindings in 'help-mode' use the new `help-key-binding' face.
+
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
diff --git a/lisp/faces.el b/lisp/faces.el
index 90f11bbe3b..ffe8eccdbe 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2815,6 +2815,11 @@ help-argument-name
   "Face to highlight argument names in *Help* buffers."
   :group 'help)
 
+(defface help-key-binding '((t :foreground "ForestGreen"))
+  "Face for keybindings in *Help* buffers."
+  :version "28.1"
+  :group 'help)
+
 (defface glyphless-char
   '((((type tty)) :inherit underline)
     (((type pc)) :inherit escape-glyph)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 290bebf7e5..fc57ec1cca 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -466,13 +466,16 @@ help-fns--key-bindings
               ;; If lots of ordinary text characters run this command,
               ;; don't mention them one by one.
               (if (< (length non-modified-keys) 10)
-                  (princ (mapconcat #'key-description keys ", "))
+                  (with-current-buffer standard-output
+                    (insert (mapconcat #'help--key-description-fontified
+                                       keys ", ")))
                 (dolist (key non-modified-keys)
                   (setq keys (delq key keys)))
                 (if keys
-                    (progn
-                      (princ (mapconcat #'key-description keys ", "))
-                      (princ ", and many ordinary text characters"))
+                    (with-current-buffer standard-output
+                      (insert (mapconcat #'help--key-description-fontified
+                                        keys ", "))
+                      (insert ", and many ordinary text characters"))
                   (princ "many ordinary text characters"))))
             (when (or remapped keys non-modified-keys)
               (princ ".")
@@ -1824,10 +1827,12 @@ describe-mode
 	      (save-excursion
 		(re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
                                     nil t)
-		(help-xref-button 1 'help-function-def mode file-name)))))
-	(princ ":\n")
-	(princ (help-split-fundoc (documentation major-mode) nil 'doc))
-        (princ (help-fns--list-local-commands)))))
+                (help-xref-button 1 'help-function-def mode file-name)))))
+        (let ((fundoc (help-split-fundoc (documentation major-mode) nil 'doc)))
+          (with-current-buffer standard-output
+            (insert ":\n")
+            (insert fundoc)
+            (insert (help-fns--list-local-commands)))))))
   ;; For the sake of IELM and maybe others
   nil)
 
diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 791b10a878..74689cb5b4 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -92,119 +92,116 @@ make-help-screen
 with the key sequence that invoked FNAME.
 When FNAME finally does get a command, it executes that command
 and then returns."
-  (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
-    `(progn
-       (defun ,doc-fn () ,help-text nil)
-       (defun ,fname ()
-	 "Help command."
-	 (interactive)
-	 (let ((line-prompt
-		(substitute-command-keys ,help-line)))
-	   (when three-step-help
-	     (message "%s" line-prompt))
-	   (let* ((help-screen (documentation (quote ,doc-fn)))
-		  ;; We bind overriding-local-map for very small
-		  ;; sections, *excluding* where we switch buffers
-		  ;; and where we execute the chosen help command.
-		  (local-map (make-sparse-keymap))
-		  (new-minor-mode-map-alist minor-mode-map-alist)
-		  (prev-frame (selected-frame))
-		  config new-frame key char)
-	     (when (string-match "%THIS-KEY%" help-screen)
-	       (setq help-screen
-		     (replace-match (key-description
-				     (substring (this-command-keys) 0 -1))
-				    t t help-screen)))
-	     (unwind-protect
-		 (let ((minor-mode-map-alist nil))
-		   (setcdr local-map ,helped-map)
-		   (define-key local-map [t] 'undefined)
-		   ;; Make the scroll bar keep working normally.
-		   (define-key local-map [vertical-scroll-bar]
-		     (lookup-key global-map [vertical-scroll-bar]))
-		   (if three-step-help
-		       (progn
-			 (setq key (let ((overriding-local-map local-map))
-				     (read-key-sequence nil)))
-			 ;; Make the HELP key translate to C-h.
-			 (if (lookup-key function-key-map key)
-			     (setq key (lookup-key function-key-map key)))
-			 (setq char (aref key 0)))
-		     (setq char ??))
-		   (when (or (eq char ??) (eq char help-char)
-			     (memq char help-event-list))
-		     (setq config (current-window-configuration))
-		     (pop-to-buffer " *Metahelp*" nil t)
-		     (and (fboundp 'make-frame)
-			  (not (eq (window-frame)
-				   prev-frame))
-			  (setq new-frame (window-frame)
-				config nil))
-		     (setq buffer-read-only nil)
-		     (let ((inhibit-read-only t))
-		       (erase-buffer)
-		       (insert help-screen))
-		     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-		       (help-mode)
-		       (setq new-minor-mode-map-alist minor-mode-map-alist))
-		     (goto-char (point-min))
-		     (while (or (memq char (append help-event-list
-						   (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
-				(eq (car-safe char) 'switch-frame)
-				(equal key "\M-v"))
-		       (condition-case nil
-			   (cond
-			    ((eq (car-safe char) 'switch-frame)
-			     (handle-switch-frame char))
-			    ((memq char '(?\C-v ?\s))
-			     (scroll-up))
-			    ((or (memq char '(?\177 ?\M-v delete backspace))
-				 (equal key "\M-v"))
-			     (scroll-down)))
-			 (error nil))
-		       (let ((cursor-in-echo-area t)
-			     (overriding-local-map local-map))
-			 (setq key (read-key-sequence
-				    (format "Type one of the options listed%s: "
-					    (if (pos-visible-in-window-p
-						 (point-max))
-						"" ", or SPACE or DEL to scroll")))
-			       char (aref key 0)))
-
-		       ;; If this is a scroll bar command, just run it.
-		       (when (eq char 'vertical-scroll-bar)
-			 (command-execute (lookup-key local-map key) nil key))))
-		   ;; We don't need the prompt any more.
-		   (message "")
-		   ;; Mouse clicks are not part of the help feature,
-		   ;; so reexecute them in the standard environment.
-		   (if (listp char)
-		       (setq unread-command-events
-			     (cons char unread-command-events)
-			     config nil)
-		     (let ((defn (lookup-key local-map key)))
-		       (if defn
-			   (progn
-			     (when config
-			       (set-window-configuration config)
-			       (setq config nil))
-			     ;; Temporarily rebind `minor-mode-map-alist'
-			     ;; to `new-minor-mode-map-alist' (Bug#10454).
-			     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-			       ;; `defn' must make sure that its frame is
-			       ;; selected, so we won't iconify it below.
-			       (call-interactively defn))
-			     (when new-frame
-			       ;; Do not iconify the selected frame.
-			       (unless (eq new-frame (selected-frame))
-				 (iconify-frame new-frame))
-			       (setq new-frame nil)))
-			 (ding)))))
-	       (when config
-		 (set-window-configuration config))
-	       (when new-frame
-		 (iconify-frame new-frame))
-	       (setq minor-mode-map-alist new-minor-mode-map-alist))))))))
+  `(defun ,fname ()
+     "Help command."
+     (interactive)
+     (let ((line-prompt
+            (substitute-command-keys ,help-line)))
+       (when three-step-help
+         (message "%s" line-prompt))
+       (let* ((help-screen ,help-text)
+              ;; We bind overriding-local-map for very small
+              ;; sections, *excluding* where we switch buffers
+              ;; and where we execute the chosen help command.
+              (local-map (make-sparse-keymap))
+              (new-minor-mode-map-alist minor-mode-map-alist)
+              (prev-frame (selected-frame))
+              config new-frame key char)
+         (when (string-match "%THIS-KEY%" help-screen)
+           (setq help-screen
+                 (replace-match (help--key-description-fontified
+                                 (substring (this-command-keys) 0 -1))
+                                t t help-screen)))
+         (unwind-protect
+             (let ((minor-mode-map-alist nil))
+               (setcdr local-map ,helped-map)
+               (define-key local-map [t] 'undefined)
+               ;; Make the scroll bar keep working normally.
+               (define-key local-map [vertical-scroll-bar]
+                 (lookup-key global-map [vertical-scroll-bar]))
+               (if three-step-help
+                   (progn
+                     (setq key (let ((overriding-local-map local-map))
+                                 (read-key-sequence nil)))
+                     ;; Make the HELP key translate to C-h.
+                     (if (lookup-key function-key-map key)
+                         (setq key (lookup-key function-key-map key)))
+                     (setq char (aref key 0)))
+                 (setq char ??))
+               (when (or (eq char ??) (eq char help-char)
+                         (memq char help-event-list))
+                 (setq config (current-window-configuration))
+                 (pop-to-buffer " *Metahelp*" nil t)
+                 (and (fboundp 'make-frame)
+                      (not (eq (window-frame)
+                               prev-frame))
+                      (setq new-frame (window-frame)
+                            config nil))
+                 (setq buffer-read-only nil)
+                 (let ((inhibit-read-only t))
+                   (erase-buffer)
+                   (insert (substitute-command-keys help-screen)))
+                 (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                   (help-mode)
+                   (setq new-minor-mode-map-alist minor-mode-map-alist))
+                 (goto-char (point-min))
+                 (while (or (memq char (append help-event-list
+                                               (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
+                            (eq (car-safe char) 'switch-frame)
+                            (equal key "\M-v"))
+                   (condition-case nil
+                       (cond
+                        ((eq (car-safe char) 'switch-frame)
+                         (handle-switch-frame char))
+                        ((memq char '(?\C-v ?\s))
+                         (scroll-up))
+                        ((or (memq char '(?\177 ?\M-v delete backspace))
+                             (equal key "\M-v"))
+                         (scroll-down)))
+                     (error nil))
+                   (let ((cursor-in-echo-area t)
+                         (overriding-local-map local-map))
+                     (setq key (read-key-sequence
+                                (format "Type one of the options listed%s: "
+                                        (if (pos-visible-in-window-p
+                                             (point-max))
+                                            "" ", or SPACE or DEL to scroll")))
+                           char (aref key 0)))
+
+                   ;; If this is a scroll bar command, just run it.
+                   (when (eq char 'vertical-scroll-bar)
+                     (command-execute (lookup-key local-map key) nil key))))
+               ;; We don't need the prompt any more.
+               (message "")
+               ;; Mouse clicks are not part of the help feature,
+               ;; so reexecute them in the standard environment.
+               (if (listp char)
+                   (setq unread-command-events
+                         (cons char unread-command-events)
+                         config nil)
+                 (let ((defn (lookup-key local-map key)))
+                   (if defn
+                       (progn
+                         (when config
+                           (set-window-configuration config)
+                           (setq config nil))
+                         ;; Temporarily rebind `minor-mode-map-alist'
+                         ;; to `new-minor-mode-map-alist' (Bug#10454).
+                         (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                           ;; `defn' must make sure that its frame is
+                           ;; selected, so we won't iconify it below.
+                           (call-interactively defn))
+                         (when new-frame
+                           ;; Do not iconify the selected frame.
+                           (unless (eq new-frame (selected-frame))
+                             (iconify-frame new-frame))
+                           (setq new-frame nil)))
+                     (ding)))))
+           (when config
+             (set-window-configuration config))
+           (when new-frame
+             (iconify-frame new-frame))
+           (setq minor-mode-map-alist new-minor-mode-map-alist))))))
 
 (provide 'help-macro)
 
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..50abb28cb1 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -104,8 +104,8 @@ help-map
     (define-key map "R" 'info-display-manual)
     (define-key map "s" 'describe-syntax)
     (define-key map "t" 'help-with-tutorial)
-    (define-key map "w" 'where-is)
     (define-key map "v" 'describe-variable)
+    (define-key map "w" 'where-is)
     (define-key map "q" 'help-quit)
     map)
   "Keymap for characters following the Help key.")
@@ -187,11 +187,8 @@ help-print-return-message
 ;; So keyboard macro definitions are documented correctly
 (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro))
 
-(defalias 'help 'help-for-help-internal)
-;; find-function can find this.
-(defalias 'help-for-help 'help-for-help-internal)
-;; It can't find this, but nobody will look.
-(make-help-screen help-for-help-internal
+(defalias 'help 'help-for-help)
+(make-help-screen help-for-help
   (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
   ;; Don't purecopy this one, because it's not evaluated (it's
   ;; directly used as a docstring in a function definition, so it'll
@@ -199,52 +196,52 @@ 'help-for-help
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
 \(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
 
-a PATTERN   Show commands whose name matches the PATTERN (a list of words
+\\[apropos-command] PATTERN   Show commands whose name matches the PATTERN (a list of words
               or a regexp).  See also the `apropos' command.
-b           Display all key bindings.
-c KEYS      Display the command name run by the given key sequence.
-C CODING    Describe the given coding system, or RET for current ones.
-d PATTERN   Show a list of functions, variables, and other items whose
+\\[describe-bindings]           Display all key bindings.
+\\[describe-key-briefly] KEYS      Display the command name run by the given key sequence.
+\\[describe-coding-system] CODING    Describe the given coding system, or RET for current ones.
+\\[apropos-documentation] PATTERN   Show a list of functions, variables, and other items whose
               documentation matches the PATTERN (a list of words or a regexp).
-e           Go to the *Messages* buffer which logs echo-area messages.
-f FUNCTION  Display documentation for the given function.
-F COMMAND   Show the Emacs manual's section that describes the command.
-g           Display information about the GNU project.
-h           Display the HELLO file which illustrates various scripts.
-i           Start the Info documentation reader: read included manuals.
-I METHOD    Describe a specific input method, or RET for current.
-k KEYS      Display the full documentation for the key sequence.
-K KEYS      Show the Emacs manual's section for the command bound to KEYS.
-l           Show last 300 input keystrokes (lossage).
-L LANG-ENV  Describes a specific language environment, or RET for current.
-m           Display documentation of current minor modes and current major mode,
-              including their special commands.
-n           Display news of recent Emacs changes.
-o SYMBOL    Display the given function or variable's documentation and value.
-p TOPIC     Find packages matching a given topic keyword.
-P PACKAGE   Describe the given Emacs Lisp package.
-r           Display the Emacs manual in Info mode.
-R           Prompt for a manual and then display it in Info mode.
-s           Display contents of current syntax table, plus explanations.
-S SYMBOL    Show the section for the given symbol in the Info manual
+\\[view-echo-area-messages]           Go to the *Messages* buffer which logs echo-area messages.
+\\[describe-function] FUNCTION  Display documentation for the given function.
+\\[Info-goto-emacs-command-node] COMMAND   Show the Emacs manual's section that describes the command.
+\\[describe-gnu-project]           Display information about the GNU project.
+\\[view-hello-file]           Display the HELLO file which illustrates various scripts.
+\\[info]           Start the Info documentation reader: read included manuals.
+\\[describe-input-method] METHOD    Describe a specific input method, or RET for current.
+\\[describe-key] KEYS      Display the full documentation for the key sequence.
+\\[Info-goto-emacs-key-command-node] KEYS      Show the Emacs manual's section for the command bound to KEYS.
+\\[view-lossage]           Show last 300 input keystrokes (lossage).
+\\[describe-language-environment] LANG-ENV  Describes a specific language environment, or RET for current.
+\\[describe-mode]           Display documentation of current minor modes and current major mode,
+             including their special commands.
+\\[view-emacs-news]           Display news of recent Emacs changes.
+\\[describe-symbol] SYMBOL    Display the given function or variable's documentation and value.
+\\[finder-by-keyword] TOPIC     Find packages matching a given topic keyword.
+\\[describe-package] PACKAGE   Describe the given Emacs Lisp package.
+\\[info-emacs-manual]           Display the Emacs manual in Info mode.
+\\[info-display-manual]           Prompt for a manual and then display it in Info mode.
+\\[describe-syntax]           Display contents of current syntax table, plus explanations.
+\\[info-lookup-symbol] SYMBOL    Show the section for the given symbol in the Info manual
               for the programming language used in this buffer.
-t           Start the Emacs learn-by-doing tutorial.
-v VARIABLE  Display the given variable's documentation and value.
-w COMMAND   Display which keystrokes invoke the given command (where-is).
-.           Display any available local help at point in the echo area.
-
-C-a         Information about Emacs.
-C-c         Emacs copying permission (GNU General Public License).
-C-d         Instructions for debugging GNU Emacs.
-C-e         External packages and information about Emacs.
-C-f         Emacs FAQ.
+\\[help-with-tutorial]           Start the Emacs learn-by-doing tutorial.
+\\[describe-variable] VARIABLE  Display the given variable's documentation and value.
+\\[where-is] COMMAND   Display which keystrokes invoke the given command (where-is).
+\\[display-local-help]           Display any available local help at point in the echo area.
+
+\\[about-emacs]         Information about Emacs.
+\\[describe-copying]         Emacs copying permission (GNU General Public License).
+\\[view-emacs-debugging]         Instructions for debugging GNU Emacs.
+\\[view-external-packages]         External packages and information about Emacs.
+\\[view-emacs-FAQ]         Emacs FAQ.
 C-m         How to order printed Emacs manuals.
 C-n         News of recent Emacs changes.
-C-o         Emacs ordering and distribution information.
-C-p         Info about known Emacs problems.
-C-s         Search forward \"help window\".
-C-t         Emacs TODO list.
-C-w         Information on absence of warranty for GNU Emacs."
+\\[describe-distribution]         Emacs ordering and distribution information.
+\\[view-emacs-problems]         Info about known Emacs problems.
+\\[search-forward-help-for-help]         Search forward \"help window\".
+\\[view-emacs-todo]         Emacs TODO list.
+\\[describe-no-warranty]         Information on absence of warranty for GNU Emacs."
   help-map)
 
 \f
@@ -492,6 +489,15 @@ view-lossage
 \f
 ;; Key bindings
 
+(defun help--key-description-fontified (keys &optional prefix)
+  "Like `key-description' but add face for \"*Help*\" buffers."
+  ;; We add both the `font-lock-face' and `face' properties here, as this
+  ;; seems to be the only way to get this to work reliably in any
+  ;; buffer.
+  (propertize (key-description keys prefix)
+              'font-lock-face 'help-key-binding
+              'face 'help-key-binding))
+
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
 The keys are displayed in order of precedence.
@@ -511,7 +517,6 @@ describe-bindings
     (with-current-buffer (help-buffer)
       (describe-buffer-bindings buffer prefix))))
 
-;; This function used to be in keymap.c.
 (defun describe-bindings-internal (&optional menus prefix)
   "Show a list of all defined keys, and their definitions.
 We put that list in a buffer, and display the buffer.
@@ -559,7 +564,8 @@ where-is
       (let* ((remapped (command-remapping symbol))
 	     (keys (where-is-internal
 		    symbol overriding-local-map nil nil remapped))
-	     (keys (mapconcat 'key-description keys ", "))
+             (keys (mapconcat #'help--key-description-fontified
+                              keys ", "))
 	     string)
 	(setq string
 	      (if insert
@@ -587,11 +593,11 @@ where-is
   nil)
 
 (defun help-key-description (key untranslated)
-  (let ((string (key-description key)))
+  (let ((string (help--key-description-fontified key)))
     (if (or (not untranslated)
 	    (and (eq (aref untranslated 0) ?\e) (not (eq (aref key 0) ?\e))))
 	string
-      (let ((otherstring (key-description untranslated)))
+      (let ((otherstring (help--key-description-fontified untranslated)))
 	(if (equal string otherstring)
 	    string
 	  (format "%s (translated from %s)" string otherstring))))))
@@ -979,7 +985,7 @@ substitute-command-keys
   "Substitute key descriptions for command names in STRING.
 Each substring of the form \\\\=[COMMAND] is replaced by either a
 keystroke sequence that invokes COMMAND, or \"M-x COMMAND\" if COMMAND
-is not on any keys.
+is not on any keys.  Keybindings will use the face `help-key-binding'.
 
 Each substring of the form \\\\={MAPVAR} is replaced by a summary of
 the value of MAPVAR as a keymap.  This summary is similar to the one
@@ -999,7 +1005,7 @@ substitute-command-keys
 output.
 
 Return the original STRING if no substitutions are made.
-Otherwise, return a new string (without any text properties)."
+Otherwise, return a new string."
   (when (not (null string))
     ;; KEYMAP is either nil (which means search all the active
     ;; keymaps) or a specified local map (which means search just that
@@ -1053,12 +1059,15 @@ substitute-command-keys
                                 (where-is-internal fun keymap t))))
                   (if (not key)
                       ;; Function is not on any key.
-                      (progn (insert "M-x ")
-                             (goto-char (+ end-point 3))
-                             (delete-char 1))
+                      (progn
+                        (insert (propertize "M-x "
+                                            'face 'help-key-binding
+                                            'font-lock-face 'help-key-binding))
+                        (goto-char (+ end-point 3))
+                        (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (key-description key)))))
+                    (insert (help--key-description-fontified key)))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
@@ -1172,7 +1181,7 @@ describe-map-tree
                           (concat title
                                   (if prefix
                                       (concat " Starting With "
-                                              (key-description prefix)))
+                                              (help--key-description-fontified prefix)))
                                   ":\n"))
                       "key             binding\n"
                       "---             -------\n")))
@@ -1228,6 +1237,8 @@ help--describe-command
                                              (= help--previous-description-column 32)))
                                     32)
                                    (t 16))))
+    ;; Insert tab without face to avoid using the `help-keymap' face.
+    (insert (propertize "\t" 'face nil 'font-lock-face nil))
     (indent-to description-column 1)
     (setq help--previous-description-column description-column)
     (cond ((symbolp definition)
@@ -1240,6 +1251,8 @@ help--describe-command
 
 (defun help--describe-translation (definition)
   ;; Converted from describe_translation in keymap.c.
+  ;; Insert tab without face to avoid using the `help-keymap' face.
+  (insert (propertize "\t" 'face nil 'font-lock-face nil))
   (indent-to 16 1)
   (cond ((symbolp definition)
          (insert (symbol-name definition) "\n"))
@@ -1351,9 +1364,9 @@ describe-map
               (setq end (caar vect))))
           ;; Now START .. END is the range to describe next.
           ;; Insert the string to describe the event START.
-          (insert (key-description (vector start) prefix))
+          (insert (help--key-description-fontified (vector start) prefix))
           (when (not (eq start end))
-            (insert " .. " (key-description (vector end) prefix)))
+            (insert " .. " (help--key-description-fontified (vector end) prefix)))
           ;; Print a description of the definition of this character.
           ;; Called function will take care of spacing out far enough
           ;; for alignment purposes.
@@ -1420,7 +1433,7 @@ describe-map
 ;;             (setq first nil))
 ;;           (when (and prefix (> (length prefix) 0))
 ;;             (insert (format "%s" prefix)))
-;;           (insert (key-description (vector start-idx) prefix))
+;;           (insert (help--key-description-fontified (vector start-idx) prefix))
 ;;           ;; Find all consecutive characters or rows that have the
 ;;           ;; same definition.
 ;;           (while (equal (keymap--get-keyelt (aref vector (1+ idx)) nil)
@@ -1433,7 +1446,7 @@ describe-map
 ;;             (insert " .. ")
 ;;             (when (and prefix (> (length prefix) 0))
 ;;               (insert (format "%s" prefix)))
-;;             (insert (key-description (vector idx) prefix)))
+;;             (insert (help--key-description-fontified (vector idx) prefix)))
 ;;           (if transl
 ;;               (help--describe-translation definition)
 ;;             (help--describe-command definition))
@@ -1924,6 +1937,8 @@ help-command-error-confusable-suggestions
 (add-function :after command-error-function
               #'help-command-error-confusable-suggestions)
 
+(define-obsolete-function-alias 'help-for-help-internal #'help-for-help "28.1")
+
 \f
 (provide 'help)
 
diff --git a/lisp/isearch.el b/lisp/isearch.el
index e7926ac08c..943e24aa56 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -460,11 +460,11 @@ isearch-help-map
 (make-help-screen isearch-help-for-help-internal
   (purecopy "Type a help option: [bkm] or ?")
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
-\(Type \\<help-map>\\[help-quit] to exit the Help command.)
+\(Type \\<isearch-help-map>\\[help-quit] to exit the Help command.)
 
-b           Display all Isearch key bindings.
-k KEYS      Display full documentation of Isearch key sequence.
-m           Display documentation of Isearch mode.
+\\[isearch-describe-bindings]           Display all Isearch key bindings.
+\\[isearch-describe-key] KEYS      Display full documentation of Isearch key sequence.
+\\[isearch-describe-mode]           Display documentation of Isearch mode.
 
 You can't type here other help keys available in the global help map,
 but outside of this help window when you type them in Isearch mode,
diff --git a/lisp/tooltip.el b/lisp/tooltip.el
index 8e00aa5c2a..09ee977cf2 100644
--- a/lisp/tooltip.el
+++ b/lisp/tooltip.el
@@ -248,7 +248,8 @@ tooltip-show
 	    (setf (alist-get 'border-color params) fg))
 	  (when (stringp bg)
 	    (setf (alist-get 'background-color params) bg))
-	  (x-show-tip (propertize text 'face 'tooltip)
+          (add-face-text-property 0 (length text) 'tooltip t text)
+          (x-show-tip text
 		      (selected-frame)
 		      params
 		      tooltip-hide-delay
diff --git a/src/keymap.c b/src/keymap.c
index 782931fadf..e38c9b908a 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2846,6 +2846,23 @@ DEFUN ("describe-vector", Fdescribe_vector, Sdescribe_vector, 1, 2, 0,
   return unbind_to (count, Qnil);
 }
 
+static Lisp_Object fontify_key_properties;
+
+static Lisp_Object
+describe_key_maybe_fontify (Lisp_Object str, Lisp_Object prefix,
+				   bool keymap_p)
+{
+  Lisp_Object key_desc = Fkey_description (str, prefix);
+
+  if (keymap_p)
+    return Fadd_text_properties (make_fixnum (0),
+				 make_fixnum (SCHARS (key_desc)),
+				 fontify_key_properties,
+				 key_desc);
+  else
+    return key_desc;
+}
+
 DEFUN ("help--describe-vector", Fhelp__describe_vector, Shelp__describe_vector, 7, 7, 0,
        doc: /* Insert in the current buffer a description of the contents of VECTOR.
 Call DESCRIBER to insert the description of one value found in VECTOR.
@@ -3021,7 +3038,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
       if (!NILP (elt_prefix))
 	insert1 (elt_prefix);
 
-      insert1 (Fkey_description (kludge, prefix));
+      insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 
       /* Find all consecutive characters or rows that have the same
 	 definition.  But, if VECTOR is a char-table, we had better
@@ -3071,7 +3088,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
 	  if (!NILP (elt_prefix))
 	    insert1 (elt_prefix);
 
-	  insert1 (Fkey_description (kludge, prefix));
+	  insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 	}
 
       /* Print a description of the definition of this character.
@@ -3200,6 +3217,12 @@ syms_of_keymap (void)
   staticpro (&where_is_cache);
   staticpro (&where_is_cache_keymaps);
 
+  DEFSYM (Qfont_lock_face, "font-lock-face");
+  DEFSYM (Qhelp_key_binding, "help-key-binding");
+  staticpro (&fontify_key_properties);
+  fontify_key_properties = Fcons (Qfont_lock_face,
+				  Fcons (Qhelp_key_binding, Qnil));
+
   defsubr (&Skeymapp);
   defsubr (&Skeymap_parent);
   defsubr (&Skeymap_prompt);
-- 
2.30.1

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

[Drew Adams]

Still haven't seen a reason why we would want only
colored text instead of links to help for the keys.

The reason is...?

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Still haven't seen a reason why we would want only
> colored text instead of links to help for the keys.

I think optionally adding links to `\\[foo]' substitutions could be
useful.

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

[Drew Adams]

> > Still haven't seen a reason why we would want only
> > colored text instead of links to help for the keys.
> 
> I think optionally adding links to `\\[foo]'
> substitutions could be useful.

So will your coloring also be optional - opt in?

There's still the question of why to only colorize
when we can link instead?  You didn't answer that.
You only said that we could also, optionally, link.

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> There's still the question of why to only colorize
> when we can link instead?  You didn't answer that.
> You only said that we could also, optionally, link.

Because colorizing makes sense everywhere while linking does not.

The effect is also much less obtrusive.

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

[Drew Adams]

> > There's still the question of why to only colorize
> > when we can link instead?  You didn't answer that.
> > You only said that we could also, optionally, link.
> 
> Because colorizing makes sense everywhere while
> linking does not.

Why do you think so?  Where does colorizing
make sense but linking does not?

> The effect is also much less obtrusive.

Why do you think so?  Is it because you think
the default face for linking is ore obtrusive
than the default appearance you've given to
your colorizing face?

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 5 Mar 2021 10:18:25 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> >>     => #("yxy" 0 1 (face italic) 1 2 (face (italic bold)) 2 3 (face italic))
> >
> > That's because you add a property which was unspecified by the
> > original face.  But in the tooltip case, the function tooltip-show
> > propertizes the entire text it receives with the 'tooltip' face, so
> > any face attributes in the text that are also specified by the
> > 'tooltip' face will be overwritten.  So, for example, if the tooltip
> > text had a :background attribute, that attribute would be overwritten
> > by the background color of the 'tooltip' face.  Isn't that what you
> > see?
> 
> But that just comes down to which face takes priority, right?  So if we
> we would need to set the APPEND argument of `add-face-text-property' to
> t.

This would take care of the conflicting colors, but that's not the
original problem which caused us to talk about tooltips.  The original
problem was that someone could customize the help-key-binding face to
specify size as well.  What do you see then?

> +          (add-face-text-property 0 (length text) 'tooltip t text)

This should have a comment explaining why we use a non-nil APPEND
argument.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 530 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> This would take care of the conflicting colors, but that's not the
> original problem which caused us to talk about tooltips.  The original
> problem was that someone could customize the help-key-binding face to
> specify size as well.  What do you see then?

It works as expected also when you specify :height.

>> +          (add-face-text-property 0 (length text) 'tooltip t text)
>
> This should have a comment explaining why we use a non-nil APPEND
> argument.

Fixed in the attached.

[-- Attachment #2: 0001-Add-new-face-help-key-binding-for-keybindings-in-hel.patch --]
[-- Type: text/x-diff, Size: 33431 bytes --]

From 7475c25ae5ff0c66046edb209d160bda03a70b62 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 24 Feb 2021 01:18:13 +0100
Subject: [PATCH] Add new face 'help-key-binding' for keybindings in help

* lisp/faces.el (help-key-binding): New face.
* lisp/help.el
(help-for-help): Rename from 'help-for-help-internal'.  Use
'substitute-command-keys' syntax.
(help): Make into alias for 'help-for-help'.
(help-for-help-internal): Make into obsolete alias for
'help-for-help'.
(help--key-description-fontified): New function to add the
'help-key-binding' face.
(help-key-description, substitute-command-keys)
(describe-map-tree, help--describe-command)
(help--describe-translation, describe-map):
* lisp/help-fns.el (help-fns--key-bindings, describe-mode):
Use above new function.
* lisp/isearch.el (isearch-help-for-help-internal): Use
`substitute-command-keys' syntax.
* lisp/help-macro.el (make-help-screen): Use
'substitute-command-keys' and 'help--key-description-fontified'.
Simplify.
* src/keymap.c (describe_key_maybe_fontify): New function to add
the 'help-key-binding' face to keybindings.
(describe_vector): Use above new keybinding.
(syms_of_keymap) <Qfont_lock_face, Qhelp_key_binding>: New
DEFSYMs.
(fontify_key_properties): New static variable.
* lisp/tooltip.el (tooltip-show): Avoid overriding faces in
specified tooltip text.
---
 etc/NEWS           |   3 +
 lisp/faces.el      |   5 +
 lisp/help-fns.el   |  21 +++--
 lisp/help-macro.el | 223 ++++++++++++++++++++++-----------------------
 lisp/help.el       | 139 +++++++++++++++-------------
 lisp/isearch.el    |   8 +-
 lisp/tooltip.el    |   7 +-
 src/keymap.c       |  27 +++++-
 8 files changed, 243 insertions(+), 190 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 3522fce03a..92705d2a7b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -911,6 +911,9 @@ skipped.
 
 ** Help
 
+---
+*** Keybindings in 'help-mode' use the new `help-key-binding' face.
+
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
diff --git a/lisp/faces.el b/lisp/faces.el
index 90f11bbe3b..ffe8eccdbe 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2815,6 +2815,11 @@ help-argument-name
   "Face to highlight argument names in *Help* buffers."
   :group 'help)
 
+(defface help-key-binding '((t :foreground "ForestGreen"))
+  "Face for keybindings in *Help* buffers."
+  :version "28.1"
+  :group 'help)
+
 (defface glyphless-char
   '((((type tty)) :inherit underline)
     (((type pc)) :inherit escape-glyph)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 01d3756bf0..c27cdb5aa4 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -466,13 +466,16 @@ help-fns--key-bindings
               ;; If lots of ordinary text characters run this command,
               ;; don't mention them one by one.
               (if (< (length non-modified-keys) 10)
-                  (princ (mapconcat #'key-description keys ", "))
+                  (with-current-buffer standard-output
+                    (insert (mapconcat #'help--key-description-fontified
+                                       keys ", ")))
                 (dolist (key non-modified-keys)
                   (setq keys (delq key keys)))
                 (if keys
-                    (progn
-                      (princ (mapconcat #'key-description keys ", "))
-                      (princ ", and many ordinary text characters"))
+                    (with-current-buffer standard-output
+                      (insert (mapconcat #'help--key-description-fontified
+                                        keys ", "))
+                      (insert ", and many ordinary text characters"))
                   (princ "many ordinary text characters"))))
             (when (or remapped keys non-modified-keys)
               (princ ".")
@@ -1824,10 +1827,12 @@ describe-mode
 	      (save-excursion
 		(re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
                                     nil t)
-		(help-xref-button 1 'help-function-def mode file-name)))))
-	(princ ":\n")
-	(princ (help-split-fundoc (documentation major-mode) nil 'doc))
-        (princ (help-fns--list-local-commands)))))
+                (help-xref-button 1 'help-function-def mode file-name)))))
+        (let ((fundoc (help-split-fundoc (documentation major-mode) nil 'doc)))
+          (with-current-buffer standard-output
+            (insert ":\n")
+            (insert fundoc)
+            (insert (help-fns--list-local-commands)))))))
   ;; For the sake of IELM and maybe others
   nil)
 
diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 791b10a878..74689cb5b4 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -92,119 +92,116 @@ make-help-screen
 with the key sequence that invoked FNAME.
 When FNAME finally does get a command, it executes that command
 and then returns."
-  (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
-    `(progn
-       (defun ,doc-fn () ,help-text nil)
-       (defun ,fname ()
-	 "Help command."
-	 (interactive)
-	 (let ((line-prompt
-		(substitute-command-keys ,help-line)))
-	   (when three-step-help
-	     (message "%s" line-prompt))
-	   (let* ((help-screen (documentation (quote ,doc-fn)))
-		  ;; We bind overriding-local-map for very small
-		  ;; sections, *excluding* where we switch buffers
-		  ;; and where we execute the chosen help command.
-		  (local-map (make-sparse-keymap))
-		  (new-minor-mode-map-alist minor-mode-map-alist)
-		  (prev-frame (selected-frame))
-		  config new-frame key char)
-	     (when (string-match "%THIS-KEY%" help-screen)
-	       (setq help-screen
-		     (replace-match (key-description
-				     (substring (this-command-keys) 0 -1))
-				    t t help-screen)))
-	     (unwind-protect
-		 (let ((minor-mode-map-alist nil))
-		   (setcdr local-map ,helped-map)
-		   (define-key local-map [t] 'undefined)
-		   ;; Make the scroll bar keep working normally.
-		   (define-key local-map [vertical-scroll-bar]
-		     (lookup-key global-map [vertical-scroll-bar]))
-		   (if three-step-help
-		       (progn
-			 (setq key (let ((overriding-local-map local-map))
-				     (read-key-sequence nil)))
-			 ;; Make the HELP key translate to C-h.
-			 (if (lookup-key function-key-map key)
-			     (setq key (lookup-key function-key-map key)))
-			 (setq char (aref key 0)))
-		     (setq char ??))
-		   (when (or (eq char ??) (eq char help-char)
-			     (memq char help-event-list))
-		     (setq config (current-window-configuration))
-		     (pop-to-buffer " *Metahelp*" nil t)
-		     (and (fboundp 'make-frame)
-			  (not (eq (window-frame)
-				   prev-frame))
-			  (setq new-frame (window-frame)
-				config nil))
-		     (setq buffer-read-only nil)
-		     (let ((inhibit-read-only t))
-		       (erase-buffer)
-		       (insert help-screen))
-		     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-		       (help-mode)
-		       (setq new-minor-mode-map-alist minor-mode-map-alist))
-		     (goto-char (point-min))
-		     (while (or (memq char (append help-event-list
-						   (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
-				(eq (car-safe char) 'switch-frame)
-				(equal key "\M-v"))
-		       (condition-case nil
-			   (cond
-			    ((eq (car-safe char) 'switch-frame)
-			     (handle-switch-frame char))
-			    ((memq char '(?\C-v ?\s))
-			     (scroll-up))
-			    ((or (memq char '(?\177 ?\M-v delete backspace))
-				 (equal key "\M-v"))
-			     (scroll-down)))
-			 (error nil))
-		       (let ((cursor-in-echo-area t)
-			     (overriding-local-map local-map))
-			 (setq key (read-key-sequence
-				    (format "Type one of the options listed%s: "
-					    (if (pos-visible-in-window-p
-						 (point-max))
-						"" ", or SPACE or DEL to scroll")))
-			       char (aref key 0)))
-
-		       ;; If this is a scroll bar command, just run it.
-		       (when (eq char 'vertical-scroll-bar)
-			 (command-execute (lookup-key local-map key) nil key))))
-		   ;; We don't need the prompt any more.
-		   (message "")
-		   ;; Mouse clicks are not part of the help feature,
-		   ;; so reexecute them in the standard environment.
-		   (if (listp char)
-		       (setq unread-command-events
-			     (cons char unread-command-events)
-			     config nil)
-		     (let ((defn (lookup-key local-map key)))
-		       (if defn
-			   (progn
-			     (when config
-			       (set-window-configuration config)
-			       (setq config nil))
-			     ;; Temporarily rebind `minor-mode-map-alist'
-			     ;; to `new-minor-mode-map-alist' (Bug#10454).
-			     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-			       ;; `defn' must make sure that its frame is
-			       ;; selected, so we won't iconify it below.
-			       (call-interactively defn))
-			     (when new-frame
-			       ;; Do not iconify the selected frame.
-			       (unless (eq new-frame (selected-frame))
-				 (iconify-frame new-frame))
-			       (setq new-frame nil)))
-			 (ding)))))
-	       (when config
-		 (set-window-configuration config))
-	       (when new-frame
-		 (iconify-frame new-frame))
-	       (setq minor-mode-map-alist new-minor-mode-map-alist))))))))
+  `(defun ,fname ()
+     "Help command."
+     (interactive)
+     (let ((line-prompt
+            (substitute-command-keys ,help-line)))
+       (when three-step-help
+         (message "%s" line-prompt))
+       (let* ((help-screen ,help-text)
+              ;; We bind overriding-local-map for very small
+              ;; sections, *excluding* where we switch buffers
+              ;; and where we execute the chosen help command.
+              (local-map (make-sparse-keymap))
+              (new-minor-mode-map-alist minor-mode-map-alist)
+              (prev-frame (selected-frame))
+              config new-frame key char)
+         (when (string-match "%THIS-KEY%" help-screen)
+           (setq help-screen
+                 (replace-match (help--key-description-fontified
+                                 (substring (this-command-keys) 0 -1))
+                                t t help-screen)))
+         (unwind-protect
+             (let ((minor-mode-map-alist nil))
+               (setcdr local-map ,helped-map)
+               (define-key local-map [t] 'undefined)
+               ;; Make the scroll bar keep working normally.
+               (define-key local-map [vertical-scroll-bar]
+                 (lookup-key global-map [vertical-scroll-bar]))
+               (if three-step-help
+                   (progn
+                     (setq key (let ((overriding-local-map local-map))
+                                 (read-key-sequence nil)))
+                     ;; Make the HELP key translate to C-h.
+                     (if (lookup-key function-key-map key)
+                         (setq key (lookup-key function-key-map key)))
+                     (setq char (aref key 0)))
+                 (setq char ??))
+               (when (or (eq char ??) (eq char help-char)
+                         (memq char help-event-list))
+                 (setq config (current-window-configuration))
+                 (pop-to-buffer " *Metahelp*" nil t)
+                 (and (fboundp 'make-frame)
+                      (not (eq (window-frame)
+                               prev-frame))
+                      (setq new-frame (window-frame)
+                            config nil))
+                 (setq buffer-read-only nil)
+                 (let ((inhibit-read-only t))
+                   (erase-buffer)
+                   (insert (substitute-command-keys help-screen)))
+                 (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                   (help-mode)
+                   (setq new-minor-mode-map-alist minor-mode-map-alist))
+                 (goto-char (point-min))
+                 (while (or (memq char (append help-event-list
+                                               (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
+                            (eq (car-safe char) 'switch-frame)
+                            (equal key "\M-v"))
+                   (condition-case nil
+                       (cond
+                        ((eq (car-safe char) 'switch-frame)
+                         (handle-switch-frame char))
+                        ((memq char '(?\C-v ?\s))
+                         (scroll-up))
+                        ((or (memq char '(?\177 ?\M-v delete backspace))
+                             (equal key "\M-v"))
+                         (scroll-down)))
+                     (error nil))
+                   (let ((cursor-in-echo-area t)
+                         (overriding-local-map local-map))
+                     (setq key (read-key-sequence
+                                (format "Type one of the options listed%s: "
+                                        (if (pos-visible-in-window-p
+                                             (point-max))
+                                            "" ", or SPACE or DEL to scroll")))
+                           char (aref key 0)))
+
+                   ;; If this is a scroll bar command, just run it.
+                   (when (eq char 'vertical-scroll-bar)
+                     (command-execute (lookup-key local-map key) nil key))))
+               ;; We don't need the prompt any more.
+               (message "")
+               ;; Mouse clicks are not part of the help feature,
+               ;; so reexecute them in the standard environment.
+               (if (listp char)
+                   (setq unread-command-events
+                         (cons char unread-command-events)
+                         config nil)
+                 (let ((defn (lookup-key local-map key)))
+                   (if defn
+                       (progn
+                         (when config
+                           (set-window-configuration config)
+                           (setq config nil))
+                         ;; Temporarily rebind `minor-mode-map-alist'
+                         ;; to `new-minor-mode-map-alist' (Bug#10454).
+                         (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                           ;; `defn' must make sure that its frame is
+                           ;; selected, so we won't iconify it below.
+                           (call-interactively defn))
+                         (when new-frame
+                           ;; Do not iconify the selected frame.
+                           (unless (eq new-frame (selected-frame))
+                             (iconify-frame new-frame))
+                           (setq new-frame nil)))
+                     (ding)))))
+           (when config
+             (set-window-configuration config))
+           (when new-frame
+             (iconify-frame new-frame))
+           (setq minor-mode-map-alist new-minor-mode-map-alist))))))
 
 (provide 'help-macro)
 
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..50abb28cb1 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -104,8 +104,8 @@ help-map
     (define-key map "R" 'info-display-manual)
     (define-key map "s" 'describe-syntax)
     (define-key map "t" 'help-with-tutorial)
-    (define-key map "w" 'where-is)
     (define-key map "v" 'describe-variable)
+    (define-key map "w" 'where-is)
     (define-key map "q" 'help-quit)
     map)
   "Keymap for characters following the Help key.")
@@ -187,11 +187,8 @@ help-print-return-message
 ;; So keyboard macro definitions are documented correctly
 (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro))
 
-(defalias 'help 'help-for-help-internal)
-;; find-function can find this.
-(defalias 'help-for-help 'help-for-help-internal)
-;; It can't find this, but nobody will look.
-(make-help-screen help-for-help-internal
+(defalias 'help 'help-for-help)
+(make-help-screen help-for-help
   (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
   ;; Don't purecopy this one, because it's not evaluated (it's
   ;; directly used as a docstring in a function definition, so it'll
@@ -199,52 +196,52 @@ 'help-for-help
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
 \(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
 
-a PATTERN   Show commands whose name matches the PATTERN (a list of words
+\\[apropos-command] PATTERN   Show commands whose name matches the PATTERN (a list of words
               or a regexp).  See also the `apropos' command.
-b           Display all key bindings.
-c KEYS      Display the command name run by the given key sequence.
-C CODING    Describe the given coding system, or RET for current ones.
-d PATTERN   Show a list of functions, variables, and other items whose
+\\[describe-bindings]           Display all key bindings.
+\\[describe-key-briefly] KEYS      Display the command name run by the given key sequence.
+\\[describe-coding-system] CODING    Describe the given coding system, or RET for current ones.
+\\[apropos-documentation] PATTERN   Show a list of functions, variables, and other items whose
               documentation matches the PATTERN (a list of words or a regexp).
-e           Go to the *Messages* buffer which logs echo-area messages.
-f FUNCTION  Display documentation for the given function.
-F COMMAND   Show the Emacs manual's section that describes the command.
-g           Display information about the GNU project.
-h           Display the HELLO file which illustrates various scripts.
-i           Start the Info documentation reader: read included manuals.
-I METHOD    Describe a specific input method, or RET for current.
-k KEYS      Display the full documentation for the key sequence.
-K KEYS      Show the Emacs manual's section for the command bound to KEYS.
-l           Show last 300 input keystrokes (lossage).
-L LANG-ENV  Describes a specific language environment, or RET for current.
-m           Display documentation of current minor modes and current major mode,
-              including their special commands.
-n           Display news of recent Emacs changes.
-o SYMBOL    Display the given function or variable's documentation and value.
-p TOPIC     Find packages matching a given topic keyword.
-P PACKAGE   Describe the given Emacs Lisp package.
-r           Display the Emacs manual in Info mode.
-R           Prompt for a manual and then display it in Info mode.
-s           Display contents of current syntax table, plus explanations.
-S SYMBOL    Show the section for the given symbol in the Info manual
+\\[view-echo-area-messages]           Go to the *Messages* buffer which logs echo-area messages.
+\\[describe-function] FUNCTION  Display documentation for the given function.
+\\[Info-goto-emacs-command-node] COMMAND   Show the Emacs manual's section that describes the command.
+\\[describe-gnu-project]           Display information about the GNU project.
+\\[view-hello-file]           Display the HELLO file which illustrates various scripts.
+\\[info]           Start the Info documentation reader: read included manuals.
+\\[describe-input-method] METHOD    Describe a specific input method, or RET for current.
+\\[describe-key] KEYS      Display the full documentation for the key sequence.
+\\[Info-goto-emacs-key-command-node] KEYS      Show the Emacs manual's section for the command bound to KEYS.
+\\[view-lossage]           Show last 300 input keystrokes (lossage).
+\\[describe-language-environment] LANG-ENV  Describes a specific language environment, or RET for current.
+\\[describe-mode]           Display documentation of current minor modes and current major mode,
+             including their special commands.
+\\[view-emacs-news]           Display news of recent Emacs changes.
+\\[describe-symbol] SYMBOL    Display the given function or variable's documentation and value.
+\\[finder-by-keyword] TOPIC     Find packages matching a given topic keyword.
+\\[describe-package] PACKAGE   Describe the given Emacs Lisp package.
+\\[info-emacs-manual]           Display the Emacs manual in Info mode.
+\\[info-display-manual]           Prompt for a manual and then display it in Info mode.
+\\[describe-syntax]           Display contents of current syntax table, plus explanations.
+\\[info-lookup-symbol] SYMBOL    Show the section for the given symbol in the Info manual
               for the programming language used in this buffer.
-t           Start the Emacs learn-by-doing tutorial.
-v VARIABLE  Display the given variable's documentation and value.
-w COMMAND   Display which keystrokes invoke the given command (where-is).
-.           Display any available local help at point in the echo area.
-
-C-a         Information about Emacs.
-C-c         Emacs copying permission (GNU General Public License).
-C-d         Instructions for debugging GNU Emacs.
-C-e         External packages and information about Emacs.
-C-f         Emacs FAQ.
+\\[help-with-tutorial]           Start the Emacs learn-by-doing tutorial.
+\\[describe-variable] VARIABLE  Display the given variable's documentation and value.
+\\[where-is] COMMAND   Display which keystrokes invoke the given command (where-is).
+\\[display-local-help]           Display any available local help at point in the echo area.
+
+\\[about-emacs]         Information about Emacs.
+\\[describe-copying]         Emacs copying permission (GNU General Public License).
+\\[view-emacs-debugging]         Instructions for debugging GNU Emacs.
+\\[view-external-packages]         External packages and information about Emacs.
+\\[view-emacs-FAQ]         Emacs FAQ.
 C-m         How to order printed Emacs manuals.
 C-n         News of recent Emacs changes.
-C-o         Emacs ordering and distribution information.
-C-p         Info about known Emacs problems.
-C-s         Search forward \"help window\".
-C-t         Emacs TODO list.
-C-w         Information on absence of warranty for GNU Emacs."
+\\[describe-distribution]         Emacs ordering and distribution information.
+\\[view-emacs-problems]         Info about known Emacs problems.
+\\[search-forward-help-for-help]         Search forward \"help window\".
+\\[view-emacs-todo]         Emacs TODO list.
+\\[describe-no-warranty]         Information on absence of warranty for GNU Emacs."
   help-map)
 
 \f
@@ -492,6 +489,15 @@ view-lossage
 \f
 ;; Key bindings
 
+(defun help--key-description-fontified (keys &optional prefix)
+  "Like `key-description' but add face for \"*Help*\" buffers."
+  ;; We add both the `font-lock-face' and `face' properties here, as this
+  ;; seems to be the only way to get this to work reliably in any
+  ;; buffer.
+  (propertize (key-description keys prefix)
+              'font-lock-face 'help-key-binding
+              'face 'help-key-binding))
+
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
 The keys are displayed in order of precedence.
@@ -511,7 +517,6 @@ describe-bindings
     (with-current-buffer (help-buffer)
       (describe-buffer-bindings buffer prefix))))
 
-;; This function used to be in keymap.c.
 (defun describe-bindings-internal (&optional menus prefix)
   "Show a list of all defined keys, and their definitions.
 We put that list in a buffer, and display the buffer.
@@ -559,7 +564,8 @@ where-is
       (let* ((remapped (command-remapping symbol))
 	     (keys (where-is-internal
 		    symbol overriding-local-map nil nil remapped))
-	     (keys (mapconcat 'key-description keys ", "))
+             (keys (mapconcat #'help--key-description-fontified
+                              keys ", "))
 	     string)
 	(setq string
 	      (if insert
@@ -587,11 +593,11 @@ where-is
   nil)
 
 (defun help-key-description (key untranslated)
-  (let ((string (key-description key)))
+  (let ((string (help--key-description-fontified key)))
     (if (or (not untranslated)
 	    (and (eq (aref untranslated 0) ?\e) (not (eq (aref key 0) ?\e))))
 	string
-      (let ((otherstring (key-description untranslated)))
+      (let ((otherstring (help--key-description-fontified untranslated)))
 	(if (equal string otherstring)
 	    string
 	  (format "%s (translated from %s)" string otherstring))))))
@@ -979,7 +985,7 @@ substitute-command-keys
   "Substitute key descriptions for command names in STRING.
 Each substring of the form \\\\=[COMMAND] is replaced by either a
 keystroke sequence that invokes COMMAND, or \"M-x COMMAND\" if COMMAND
-is not on any keys.
+is not on any keys.  Keybindings will use the face `help-key-binding'.
 
 Each substring of the form \\\\={MAPVAR} is replaced by a summary of
 the value of MAPVAR as a keymap.  This summary is similar to the one
@@ -999,7 +1005,7 @@ substitute-command-keys
 output.
 
 Return the original STRING if no substitutions are made.
-Otherwise, return a new string (without any text properties)."
+Otherwise, return a new string."
   (when (not (null string))
     ;; KEYMAP is either nil (which means search all the active
     ;; keymaps) or a specified local map (which means search just that
@@ -1053,12 +1059,15 @@ substitute-command-keys
                                 (where-is-internal fun keymap t))))
                   (if (not key)
                       ;; Function is not on any key.
-                      (progn (insert "M-x ")
-                             (goto-char (+ end-point 3))
-                             (delete-char 1))
+                      (progn
+                        (insert (propertize "M-x "
+                                            'face 'help-key-binding
+                                            'font-lock-face 'help-key-binding))
+                        (goto-char (+ end-point 3))
+                        (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (key-description key)))))
+                    (insert (help--key-description-fontified key)))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
@@ -1172,7 +1181,7 @@ describe-map-tree
                           (concat title
                                   (if prefix
                                       (concat " Starting With "
-                                              (key-description prefix)))
+                                              (help--key-description-fontified prefix)))
                                   ":\n"))
                       "key             binding\n"
                       "---             -------\n")))
@@ -1228,6 +1237,8 @@ help--describe-command
                                              (= help--previous-description-column 32)))
                                     32)
                                    (t 16))))
+    ;; Insert tab without face to avoid using the `help-keymap' face.
+    (insert (propertize "\t" 'face nil 'font-lock-face nil))
     (indent-to description-column 1)
     (setq help--previous-description-column description-column)
     (cond ((symbolp definition)
@@ -1240,6 +1251,8 @@ help--describe-command
 
 (defun help--describe-translation (definition)
   ;; Converted from describe_translation in keymap.c.
+  ;; Insert tab without face to avoid using the `help-keymap' face.
+  (insert (propertize "\t" 'face nil 'font-lock-face nil))
   (indent-to 16 1)
   (cond ((symbolp definition)
          (insert (symbol-name definition) "\n"))
@@ -1351,9 +1364,9 @@ describe-map
               (setq end (caar vect))))
           ;; Now START .. END is the range to describe next.
           ;; Insert the string to describe the event START.
-          (insert (key-description (vector start) prefix))
+          (insert (help--key-description-fontified (vector start) prefix))
           (when (not (eq start end))
-            (insert " .. " (key-description (vector end) prefix)))
+            (insert " .. " (help--key-description-fontified (vector end) prefix)))
           ;; Print a description of the definition of this character.
           ;; Called function will take care of spacing out far enough
           ;; for alignment purposes.
@@ -1420,7 +1433,7 @@ describe-map
 ;;             (setq first nil))
 ;;           (when (and prefix (> (length prefix) 0))
 ;;             (insert (format "%s" prefix)))
-;;           (insert (key-description (vector start-idx) prefix))
+;;           (insert (help--key-description-fontified (vector start-idx) prefix))
 ;;           ;; Find all consecutive characters or rows that have the
 ;;           ;; same definition.
 ;;           (while (equal (keymap--get-keyelt (aref vector (1+ idx)) nil)
@@ -1433,7 +1446,7 @@ describe-map
 ;;             (insert " .. ")
 ;;             (when (and prefix (> (length prefix) 0))
 ;;               (insert (format "%s" prefix)))
-;;             (insert (key-description (vector idx) prefix)))
+;;             (insert (help--key-description-fontified (vector idx) prefix)))
 ;;           (if transl
 ;;               (help--describe-translation definition)
 ;;             (help--describe-command definition))
@@ -1924,6 +1937,8 @@ help-command-error-confusable-suggestions
 (add-function :after command-error-function
               #'help-command-error-confusable-suggestions)
 
+(define-obsolete-function-alias 'help-for-help-internal #'help-for-help "28.1")
+
 \f
 (provide 'help)
 
diff --git a/lisp/isearch.el b/lisp/isearch.el
index e7926ac08c..943e24aa56 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -460,11 +460,11 @@ isearch-help-map
 (make-help-screen isearch-help-for-help-internal
   (purecopy "Type a help option: [bkm] or ?")
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
-\(Type \\<help-map>\\[help-quit] to exit the Help command.)
+\(Type \\<isearch-help-map>\\[help-quit] to exit the Help command.)
 
-b           Display all Isearch key bindings.
-k KEYS      Display full documentation of Isearch key sequence.
-m           Display documentation of Isearch mode.
+\\[isearch-describe-bindings]           Display all Isearch key bindings.
+\\[isearch-describe-key] KEYS      Display full documentation of Isearch key sequence.
+\\[isearch-describe-mode]           Display documentation of Isearch mode.
 
 You can't type here other help keys available in the global help map,
 but outside of this help window when you type them in Isearch mode,
diff --git a/lisp/tooltip.el b/lisp/tooltip.el
index 8e00aa5c2a..af3b86bba7 100644
--- a/lisp/tooltip.el
+++ b/lisp/tooltip.el
@@ -248,7 +248,12 @@ tooltip-show
 	    (setf (alist-get 'border-color params) fg))
 	  (when (stringp bg)
 	    (setf (alist-get 'background-color params) bg))
-	  (x-show-tip (propertize text 'face 'tooltip)
+          ;; Use non-nil APPEND argument below to avoid overriding any
+          ;; faces used in our TEXT.  Among other things, this allows
+          ;; tooltips to use the `help-key-binding' face used in
+          ;; `substitute-command-keys' substitutions.
+          (add-face-text-property 0 (length text) 'tooltip t text)
+          (x-show-tip text
 		      (selected-frame)
 		      params
 		      tooltip-hide-delay
diff --git a/src/keymap.c b/src/keymap.c
index 782931fadf..e38c9b908a 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2846,6 +2846,23 @@ DEFUN ("describe-vector", Fdescribe_vector, Sdescribe_vector, 1, 2, 0,
   return unbind_to (count, Qnil);
 }
 
+static Lisp_Object fontify_key_properties;
+
+static Lisp_Object
+describe_key_maybe_fontify (Lisp_Object str, Lisp_Object prefix,
+				   bool keymap_p)
+{
+  Lisp_Object key_desc = Fkey_description (str, prefix);
+
+  if (keymap_p)
+    return Fadd_text_properties (make_fixnum (0),
+				 make_fixnum (SCHARS (key_desc)),
+				 fontify_key_properties,
+				 key_desc);
+  else
+    return key_desc;
+}
+
 DEFUN ("help--describe-vector", Fhelp__describe_vector, Shelp__describe_vector, 7, 7, 0,
        doc: /* Insert in the current buffer a description of the contents of VECTOR.
 Call DESCRIBER to insert the description of one value found in VECTOR.
@@ -3021,7 +3038,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
       if (!NILP (elt_prefix))
 	insert1 (elt_prefix);
 
-      insert1 (Fkey_description (kludge, prefix));
+      insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 
       /* Find all consecutive characters or rows that have the same
 	 definition.  But, if VECTOR is a char-table, we had better
@@ -3071,7 +3088,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
 	  if (!NILP (elt_prefix))
 	    insert1 (elt_prefix);
 
-	  insert1 (Fkey_description (kludge, prefix));
+	  insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 	}
 
       /* Print a description of the definition of this character.
@@ -3200,6 +3217,12 @@ syms_of_keymap (void)
   staticpro (&where_is_cache);
   staticpro (&where_is_cache_keymaps);
 
+  DEFSYM (Qfont_lock_face, "font-lock-face");
+  DEFSYM (Qhelp_key_binding, "help-key-binding");
+  staticpro (&fontify_key_properties);
+  fontify_key_properties = Fcons (Qfont_lock_face,
+				  Fcons (Qhelp_key_binding, Qnil));
+
   defsubr (&Skeymapp);
   defsubr (&Skeymap_parent);
   defsubr (&Skeymap_prompt);
-- 
2.30.1

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 5 Mar 2021 13:28:57 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> > This would take care of the conflicting colors, but that's not the
> > original problem which caused us to talk about tooltips.  The original
> > problem was that someone could customize the help-key-binding face to
> > specify size as well.  What do you see then?
> 
> It works as expected also when you specify :height.

"As expected" meaning what in this case?  Does the different size show
or doesn't it?

> > This should have a comment explaining why we use a non-nil APPEND
> > argument.
> 
> Fixed in the attached.

Thanks.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> It works as expected also when you specify :height.
>
> "As expected" meaning what in this case?  Does the different size show
> or doesn't it?

The font size is different, yes.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 5 Mar 2021 14:39:01 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> It works as expected also when you specify :height.
> >
> > "As expected" meaning what in this case?  Does the different size show
> > or doesn't it?
> 
> The font size is different, yes.

Do we want that to happen in tooltips?

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> The font size is different, yes.
>
> Do we want that to happen in tooltips?

I think so, yes.  If the user has specified :height and we otherwise
respect this face, then why shouldn't we respect also that?

(But the use-case sounds a bit unusual to me, judging by the themes I've
seen: :height is usually changed only for headlines and the like, not
for "body" text.)

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 5 Mar 2021 15:43:15 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> The font size is different, yes.
> >
> > Do we want that to happen in tooltips?
> 
> I think so, yes.  If the user has specified :height and we otherwise
> respect this face, then why shouldn't we respect also that?

It makes the tooltip height larger than usual, doesn't it?  If so, I
think we should at least have that mentioned in the doc string of the
face.

> (But the use-case sounds a bit unusual to me, judging by the themes I've
> seen: :height is usually changed only for headlines and the like, not
> for "body" text.)

It could be changed indirectly via the font.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> It makes the tooltip height larger than usual, doesn't it?  If so, I
> think we should at least have that mentioned in the doc string of the
> face.

OK, we can add a note to that effect to the `help-key-binding'
docstring.

>> (But the use-case sounds a bit unusual to me, judging by the themes I've
>> seen: :height is usually changed only for headlines and the like, not
>> for "body" text.)
>
> It could be changed indirectly via the font.

Oh, right.  Hmm.

Testing this, I'm seeing that the entire tooltip increase in size if I
do something like:

    (add-to-list 'default-frame-alist '(font . "Ubuntu Mono-20"))

Which I guess is expected since `tooltip' inherits `variable-pitch' that
inherits `default'.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 511 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> It makes the tooltip height larger than usual, doesn't it?  If so, I
>> think we should at least have that mentioned in the doc string of the
>> face.
>
> OK, we can add a note to that effect to the `help-key-binding'
> docstring.

Here's an updated patch.  The changes from the previous patch are all in
the definition of the `help-key-binding' face.

Let me know if there is anything else to change before this can go in.

[-- Attachment #2: 0001-Add-new-face-help-key-binding-for-keybindings-in-hel.patch --]
[-- Type: text/x-diff, Size: 34062 bytes --]

From 420c077c2e52bae87008987cfc8bc025f48e8fb4 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Wed, 24 Feb 2021 01:18:13 +0100
Subject: [PATCH] Add new face 'help-key-binding' for keybindings in help

* lisp/faces.el (help-key-binding): New face.
* lisp/help.el
(help-for-help): Rename from 'help-for-help-internal'.  Use
'substitute-command-keys' syntax.
(help): Make into alias for 'help-for-help'.
(help-for-help-internal): Make into obsolete alias for
'help-for-help'.
(help--key-description-fontified): New function to add the
'help-key-binding' face.
(help-key-description, substitute-command-keys)
(describe-map-tree, help--describe-command)
(help--describe-translation, describe-map):
* lisp/help-fns.el (help-fns--key-bindings, describe-mode):
Use above new function.
* lisp/isearch.el (isearch-help-for-help-internal): Use
`substitute-command-keys' syntax.
* lisp/help-macro.el (make-help-screen): Use
'substitute-command-keys' and 'help--key-description-fontified'.
Simplify.
* src/keymap.c (describe_key_maybe_fontify): New function to add
the 'help-key-binding' face to keybindings.
(describe_vector): Use above new keybinding.
(syms_of_keymap) <Qfont_lock_face, Qhelp_key_binding>: New
DEFSYMs.
(fontify_key_properties): New static variable.
* lisp/tooltip.el (tooltip-show): Avoid overriding faces in
specified tooltip text.
---
 etc/NEWS           |   3 +
 lisp/faces.el      |  18 ++++
 lisp/help-fns.el   |  21 +++--
 lisp/help-macro.el | 223 ++++++++++++++++++++++-----------------------
 lisp/help.el       | 139 +++++++++++++++-------------
 lisp/isearch.el    |   8 +-
 lisp/tooltip.el    |   7 +-
 src/keymap.c       |  27 +++++-
 8 files changed, 256 insertions(+), 190 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 6b4456e3de..5482321f49 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -914,6 +914,9 @@ skipped.
 
 ** Help
 
+---
+*** Keybindings in 'help-mode' use the new `help-key-binding' face.
+
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
diff --git a/lisp/faces.el b/lisp/faces.el
index 90f11bbe3b..cc4c84a5c6 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -2815,6 +2815,24 @@ help-argument-name
   "Face to highlight argument names in *Help* buffers."
   :group 'help)
 
+(defface help-key-binding
+  '((((class color) (min-colors 88)) :foreground "ForestGreen")
+    (((class color) (min-colors 16)) :foreground "green")
+    (((class color) (min-colors 8)) :foreground "green")
+    (((class color grayscale) (background light)) :foreground "grey15")
+    (((class color grayscale) (background dark)) :foreground "grey85")
+    (t :foreground "ForestGreen"))
+  "Face for keybindings in *Help* buffers.
+
+This face is added by `substitute-command-keys', which see.
+
+Note that this face will also be used for key bindings in
+tooltips.  This means that, for example, changing the :height of
+this face will increase the height of any tooltips containing key
+bindings.  See also the face `tooltip'."
+  :version "28.1"
+  :group 'help)
+
 (defface glyphless-char
   '((((type tty)) :inherit underline)
     (((type pc)) :inherit escape-glyph)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 01d3756bf0..c27cdb5aa4 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -466,13 +466,16 @@ help-fns--key-bindings
               ;; If lots of ordinary text characters run this command,
               ;; don't mention them one by one.
               (if (< (length non-modified-keys) 10)
-                  (princ (mapconcat #'key-description keys ", "))
+                  (with-current-buffer standard-output
+                    (insert (mapconcat #'help--key-description-fontified
+                                       keys ", ")))
                 (dolist (key non-modified-keys)
                   (setq keys (delq key keys)))
                 (if keys
-                    (progn
-                      (princ (mapconcat #'key-description keys ", "))
-                      (princ ", and many ordinary text characters"))
+                    (with-current-buffer standard-output
+                      (insert (mapconcat #'help--key-description-fontified
+                                        keys ", "))
+                      (insert ", and many ordinary text characters"))
                   (princ "many ordinary text characters"))))
             (when (or remapped keys non-modified-keys)
               (princ ".")
@@ -1824,10 +1827,12 @@ describe-mode
 	      (save-excursion
 		(re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
                                     nil t)
-		(help-xref-button 1 'help-function-def mode file-name)))))
-	(princ ":\n")
-	(princ (help-split-fundoc (documentation major-mode) nil 'doc))
-        (princ (help-fns--list-local-commands)))))
+                (help-xref-button 1 'help-function-def mode file-name)))))
+        (let ((fundoc (help-split-fundoc (documentation major-mode) nil 'doc)))
+          (with-current-buffer standard-output
+            (insert ":\n")
+            (insert fundoc)
+            (insert (help-fns--list-local-commands)))))))
   ;; For the sake of IELM and maybe others
   nil)
 
diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 791b10a878..74689cb5b4 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -92,119 +92,116 @@ make-help-screen
 with the key sequence that invoked FNAME.
 When FNAME finally does get a command, it executes that command
 and then returns."
-  (let ((doc-fn (intern (concat (symbol-name fname) "-doc"))))
-    `(progn
-       (defun ,doc-fn () ,help-text nil)
-       (defun ,fname ()
-	 "Help command."
-	 (interactive)
-	 (let ((line-prompt
-		(substitute-command-keys ,help-line)))
-	   (when three-step-help
-	     (message "%s" line-prompt))
-	   (let* ((help-screen (documentation (quote ,doc-fn)))
-		  ;; We bind overriding-local-map for very small
-		  ;; sections, *excluding* where we switch buffers
-		  ;; and where we execute the chosen help command.
-		  (local-map (make-sparse-keymap))
-		  (new-minor-mode-map-alist minor-mode-map-alist)
-		  (prev-frame (selected-frame))
-		  config new-frame key char)
-	     (when (string-match "%THIS-KEY%" help-screen)
-	       (setq help-screen
-		     (replace-match (key-description
-				     (substring (this-command-keys) 0 -1))
-				    t t help-screen)))
-	     (unwind-protect
-		 (let ((minor-mode-map-alist nil))
-		   (setcdr local-map ,helped-map)
-		   (define-key local-map [t] 'undefined)
-		   ;; Make the scroll bar keep working normally.
-		   (define-key local-map [vertical-scroll-bar]
-		     (lookup-key global-map [vertical-scroll-bar]))
-		   (if three-step-help
-		       (progn
-			 (setq key (let ((overriding-local-map local-map))
-				     (read-key-sequence nil)))
-			 ;; Make the HELP key translate to C-h.
-			 (if (lookup-key function-key-map key)
-			     (setq key (lookup-key function-key-map key)))
-			 (setq char (aref key 0)))
-		     (setq char ??))
-		   (when (or (eq char ??) (eq char help-char)
-			     (memq char help-event-list))
-		     (setq config (current-window-configuration))
-		     (pop-to-buffer " *Metahelp*" nil t)
-		     (and (fboundp 'make-frame)
-			  (not (eq (window-frame)
-				   prev-frame))
-			  (setq new-frame (window-frame)
-				config nil))
-		     (setq buffer-read-only nil)
-		     (let ((inhibit-read-only t))
-		       (erase-buffer)
-		       (insert help-screen))
-		     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-		       (help-mode)
-		       (setq new-minor-mode-map-alist minor-mode-map-alist))
-		     (goto-char (point-min))
-		     (while (or (memq char (append help-event-list
-						   (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
-				(eq (car-safe char) 'switch-frame)
-				(equal key "\M-v"))
-		       (condition-case nil
-			   (cond
-			    ((eq (car-safe char) 'switch-frame)
-			     (handle-switch-frame char))
-			    ((memq char '(?\C-v ?\s))
-			     (scroll-up))
-			    ((or (memq char '(?\177 ?\M-v delete backspace))
-				 (equal key "\M-v"))
-			     (scroll-down)))
-			 (error nil))
-		       (let ((cursor-in-echo-area t)
-			     (overriding-local-map local-map))
-			 (setq key (read-key-sequence
-				    (format "Type one of the options listed%s: "
-					    (if (pos-visible-in-window-p
-						 (point-max))
-						"" ", or SPACE or DEL to scroll")))
-			       char (aref key 0)))
-
-		       ;; If this is a scroll bar command, just run it.
-		       (when (eq char 'vertical-scroll-bar)
-			 (command-execute (lookup-key local-map key) nil key))))
-		   ;; We don't need the prompt any more.
-		   (message "")
-		   ;; Mouse clicks are not part of the help feature,
-		   ;; so reexecute them in the standard environment.
-		   (if (listp char)
-		       (setq unread-command-events
-			     (cons char unread-command-events)
-			     config nil)
-		     (let ((defn (lookup-key local-map key)))
-		       (if defn
-			   (progn
-			     (when config
-			       (set-window-configuration config)
-			       (setq config nil))
-			     ;; Temporarily rebind `minor-mode-map-alist'
-			     ;; to `new-minor-mode-map-alist' (Bug#10454).
-			     (let ((minor-mode-map-alist new-minor-mode-map-alist))
-			       ;; `defn' must make sure that its frame is
-			       ;; selected, so we won't iconify it below.
-			       (call-interactively defn))
-			     (when new-frame
-			       ;; Do not iconify the selected frame.
-			       (unless (eq new-frame (selected-frame))
-				 (iconify-frame new-frame))
-			       (setq new-frame nil)))
-			 (ding)))))
-	       (when config
-		 (set-window-configuration config))
-	       (when new-frame
-		 (iconify-frame new-frame))
-	       (setq minor-mode-map-alist new-minor-mode-map-alist))))))))
+  `(defun ,fname ()
+     "Help command."
+     (interactive)
+     (let ((line-prompt
+            (substitute-command-keys ,help-line)))
+       (when three-step-help
+         (message "%s" line-prompt))
+       (let* ((help-screen ,help-text)
+              ;; We bind overriding-local-map for very small
+              ;; sections, *excluding* where we switch buffers
+              ;; and where we execute the chosen help command.
+              (local-map (make-sparse-keymap))
+              (new-minor-mode-map-alist minor-mode-map-alist)
+              (prev-frame (selected-frame))
+              config new-frame key char)
+         (when (string-match "%THIS-KEY%" help-screen)
+           (setq help-screen
+                 (replace-match (help--key-description-fontified
+                                 (substring (this-command-keys) 0 -1))
+                                t t help-screen)))
+         (unwind-protect
+             (let ((minor-mode-map-alist nil))
+               (setcdr local-map ,helped-map)
+               (define-key local-map [t] 'undefined)
+               ;; Make the scroll bar keep working normally.
+               (define-key local-map [vertical-scroll-bar]
+                 (lookup-key global-map [vertical-scroll-bar]))
+               (if three-step-help
+                   (progn
+                     (setq key (let ((overriding-local-map local-map))
+                                 (read-key-sequence nil)))
+                     ;; Make the HELP key translate to C-h.
+                     (if (lookup-key function-key-map key)
+                         (setq key (lookup-key function-key-map key)))
+                     (setq char (aref key 0)))
+                 (setq char ??))
+               (when (or (eq char ??) (eq char help-char)
+                         (memq char help-event-list))
+                 (setq config (current-window-configuration))
+                 (pop-to-buffer " *Metahelp*" nil t)
+                 (and (fboundp 'make-frame)
+                      (not (eq (window-frame)
+                               prev-frame))
+                      (setq new-frame (window-frame)
+                            config nil))
+                 (setq buffer-read-only nil)
+                 (let ((inhibit-read-only t))
+                   (erase-buffer)
+                   (insert (substitute-command-keys help-screen)))
+                 (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                   (help-mode)
+                   (setq new-minor-mode-map-alist minor-mode-map-alist))
+                 (goto-char (point-min))
+                 (while (or (memq char (append help-event-list
+                                               (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
+                            (eq (car-safe char) 'switch-frame)
+                            (equal key "\M-v"))
+                   (condition-case nil
+                       (cond
+                        ((eq (car-safe char) 'switch-frame)
+                         (handle-switch-frame char))
+                        ((memq char '(?\C-v ?\s))
+                         (scroll-up))
+                        ((or (memq char '(?\177 ?\M-v delete backspace))
+                             (equal key "\M-v"))
+                         (scroll-down)))
+                     (error nil))
+                   (let ((cursor-in-echo-area t)
+                         (overriding-local-map local-map))
+                     (setq key (read-key-sequence
+                                (format "Type one of the options listed%s: "
+                                        (if (pos-visible-in-window-p
+                                             (point-max))
+                                            "" ", or SPACE or DEL to scroll")))
+                           char (aref key 0)))
+
+                   ;; If this is a scroll bar command, just run it.
+                   (when (eq char 'vertical-scroll-bar)
+                     (command-execute (lookup-key local-map key) nil key))))
+               ;; We don't need the prompt any more.
+               (message "")
+               ;; Mouse clicks are not part of the help feature,
+               ;; so reexecute them in the standard environment.
+               (if (listp char)
+                   (setq unread-command-events
+                         (cons char unread-command-events)
+                         config nil)
+                 (let ((defn (lookup-key local-map key)))
+                   (if defn
+                       (progn
+                         (when config
+                           (set-window-configuration config)
+                           (setq config nil))
+                         ;; Temporarily rebind `minor-mode-map-alist'
+                         ;; to `new-minor-mode-map-alist' (Bug#10454).
+                         (let ((minor-mode-map-alist new-minor-mode-map-alist))
+                           ;; `defn' must make sure that its frame is
+                           ;; selected, so we won't iconify it below.
+                           (call-interactively defn))
+                         (when new-frame
+                           ;; Do not iconify the selected frame.
+                           (unless (eq new-frame (selected-frame))
+                             (iconify-frame new-frame))
+                           (setq new-frame nil)))
+                     (ding)))))
+           (when config
+             (set-window-configuration config))
+           (when new-frame
+             (iconify-frame new-frame))
+           (setq minor-mode-map-alist new-minor-mode-map-alist))))))
 
 (provide 'help-macro)
 
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..50abb28cb1 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -104,8 +104,8 @@ help-map
     (define-key map "R" 'info-display-manual)
     (define-key map "s" 'describe-syntax)
     (define-key map "t" 'help-with-tutorial)
-    (define-key map "w" 'where-is)
     (define-key map "v" 'describe-variable)
+    (define-key map "w" 'where-is)
     (define-key map "q" 'help-quit)
     map)
   "Keymap for characters following the Help key.")
@@ -187,11 +187,8 @@ help-print-return-message
 ;; So keyboard macro definitions are documented correctly
 (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro))
 
-(defalias 'help 'help-for-help-internal)
-;; find-function can find this.
-(defalias 'help-for-help 'help-for-help-internal)
-;; It can't find this, but nobody will look.
-(make-help-screen help-for-help-internal
+(defalias 'help 'help-for-help)
+(make-help-screen help-for-help
   (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
   ;; Don't purecopy this one, because it's not evaluated (it's
   ;; directly used as a docstring in a function definition, so it'll
@@ -199,52 +196,52 @@ 'help-for-help
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
 \(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
 
-a PATTERN   Show commands whose name matches the PATTERN (a list of words
+\\[apropos-command] PATTERN   Show commands whose name matches the PATTERN (a list of words
               or a regexp).  See also the `apropos' command.
-b           Display all key bindings.
-c KEYS      Display the command name run by the given key sequence.
-C CODING    Describe the given coding system, or RET for current ones.
-d PATTERN   Show a list of functions, variables, and other items whose
+\\[describe-bindings]           Display all key bindings.
+\\[describe-key-briefly] KEYS      Display the command name run by the given key sequence.
+\\[describe-coding-system] CODING    Describe the given coding system, or RET for current ones.
+\\[apropos-documentation] PATTERN   Show a list of functions, variables, and other items whose
               documentation matches the PATTERN (a list of words or a regexp).
-e           Go to the *Messages* buffer which logs echo-area messages.
-f FUNCTION  Display documentation for the given function.
-F COMMAND   Show the Emacs manual's section that describes the command.
-g           Display information about the GNU project.
-h           Display the HELLO file which illustrates various scripts.
-i           Start the Info documentation reader: read included manuals.
-I METHOD    Describe a specific input method, or RET for current.
-k KEYS      Display the full documentation for the key sequence.
-K KEYS      Show the Emacs manual's section for the command bound to KEYS.
-l           Show last 300 input keystrokes (lossage).
-L LANG-ENV  Describes a specific language environment, or RET for current.
-m           Display documentation of current minor modes and current major mode,
-              including their special commands.
-n           Display news of recent Emacs changes.
-o SYMBOL    Display the given function or variable's documentation and value.
-p TOPIC     Find packages matching a given topic keyword.
-P PACKAGE   Describe the given Emacs Lisp package.
-r           Display the Emacs manual in Info mode.
-R           Prompt for a manual and then display it in Info mode.
-s           Display contents of current syntax table, plus explanations.
-S SYMBOL    Show the section for the given symbol in the Info manual
+\\[view-echo-area-messages]           Go to the *Messages* buffer which logs echo-area messages.
+\\[describe-function] FUNCTION  Display documentation for the given function.
+\\[Info-goto-emacs-command-node] COMMAND   Show the Emacs manual's section that describes the command.
+\\[describe-gnu-project]           Display information about the GNU project.
+\\[view-hello-file]           Display the HELLO file which illustrates various scripts.
+\\[info]           Start the Info documentation reader: read included manuals.
+\\[describe-input-method] METHOD    Describe a specific input method, or RET for current.
+\\[describe-key] KEYS      Display the full documentation for the key sequence.
+\\[Info-goto-emacs-key-command-node] KEYS      Show the Emacs manual's section for the command bound to KEYS.
+\\[view-lossage]           Show last 300 input keystrokes (lossage).
+\\[describe-language-environment] LANG-ENV  Describes a specific language environment, or RET for current.
+\\[describe-mode]           Display documentation of current minor modes and current major mode,
+             including their special commands.
+\\[view-emacs-news]           Display news of recent Emacs changes.
+\\[describe-symbol] SYMBOL    Display the given function or variable's documentation and value.
+\\[finder-by-keyword] TOPIC     Find packages matching a given topic keyword.
+\\[describe-package] PACKAGE   Describe the given Emacs Lisp package.
+\\[info-emacs-manual]           Display the Emacs manual in Info mode.
+\\[info-display-manual]           Prompt for a manual and then display it in Info mode.
+\\[describe-syntax]           Display contents of current syntax table, plus explanations.
+\\[info-lookup-symbol] SYMBOL    Show the section for the given symbol in the Info manual
               for the programming language used in this buffer.
-t           Start the Emacs learn-by-doing tutorial.
-v VARIABLE  Display the given variable's documentation and value.
-w COMMAND   Display which keystrokes invoke the given command (where-is).
-.           Display any available local help at point in the echo area.
-
-C-a         Information about Emacs.
-C-c         Emacs copying permission (GNU General Public License).
-C-d         Instructions for debugging GNU Emacs.
-C-e         External packages and information about Emacs.
-C-f         Emacs FAQ.
+\\[help-with-tutorial]           Start the Emacs learn-by-doing tutorial.
+\\[describe-variable] VARIABLE  Display the given variable's documentation and value.
+\\[where-is] COMMAND   Display which keystrokes invoke the given command (where-is).
+\\[display-local-help]           Display any available local help at point in the echo area.
+
+\\[about-emacs]         Information about Emacs.
+\\[describe-copying]         Emacs copying permission (GNU General Public License).
+\\[view-emacs-debugging]         Instructions for debugging GNU Emacs.
+\\[view-external-packages]         External packages and information about Emacs.
+\\[view-emacs-FAQ]         Emacs FAQ.
 C-m         How to order printed Emacs manuals.
 C-n         News of recent Emacs changes.
-C-o         Emacs ordering and distribution information.
-C-p         Info about known Emacs problems.
-C-s         Search forward \"help window\".
-C-t         Emacs TODO list.
-C-w         Information on absence of warranty for GNU Emacs."
+\\[describe-distribution]         Emacs ordering and distribution information.
+\\[view-emacs-problems]         Info about known Emacs problems.
+\\[search-forward-help-for-help]         Search forward \"help window\".
+\\[view-emacs-todo]         Emacs TODO list.
+\\[describe-no-warranty]         Information on absence of warranty for GNU Emacs."
   help-map)
 
 \f
@@ -492,6 +489,15 @@ view-lossage
 \f
 ;; Key bindings
 
+(defun help--key-description-fontified (keys &optional prefix)
+  "Like `key-description' but add face for \"*Help*\" buffers."
+  ;; We add both the `font-lock-face' and `face' properties here, as this
+  ;; seems to be the only way to get this to work reliably in any
+  ;; buffer.
+  (propertize (key-description keys prefix)
+              'font-lock-face 'help-key-binding
+              'face 'help-key-binding))
+
 (defun describe-bindings (&optional prefix buffer)
   "Display a buffer showing a list of all defined keys, and their definitions.
 The keys are displayed in order of precedence.
@@ -511,7 +517,6 @@ describe-bindings
     (with-current-buffer (help-buffer)
       (describe-buffer-bindings buffer prefix))))
 
-;; This function used to be in keymap.c.
 (defun describe-bindings-internal (&optional menus prefix)
   "Show a list of all defined keys, and their definitions.
 We put that list in a buffer, and display the buffer.
@@ -559,7 +564,8 @@ where-is
       (let* ((remapped (command-remapping symbol))
 	     (keys (where-is-internal
 		    symbol overriding-local-map nil nil remapped))
-	     (keys (mapconcat 'key-description keys ", "))
+             (keys (mapconcat #'help--key-description-fontified
+                              keys ", "))
 	     string)
 	(setq string
 	      (if insert
@@ -587,11 +593,11 @@ where-is
   nil)
 
 (defun help-key-description (key untranslated)
-  (let ((string (key-description key)))
+  (let ((string (help--key-description-fontified key)))
     (if (or (not untranslated)
 	    (and (eq (aref untranslated 0) ?\e) (not (eq (aref key 0) ?\e))))
 	string
-      (let ((otherstring (key-description untranslated)))
+      (let ((otherstring (help--key-description-fontified untranslated)))
 	(if (equal string otherstring)
 	    string
 	  (format "%s (translated from %s)" string otherstring))))))
@@ -979,7 +985,7 @@ substitute-command-keys
   "Substitute key descriptions for command names in STRING.
 Each substring of the form \\\\=[COMMAND] is replaced by either a
 keystroke sequence that invokes COMMAND, or \"M-x COMMAND\" if COMMAND
-is not on any keys.
+is not on any keys.  Keybindings will use the face `help-key-binding'.
 
 Each substring of the form \\\\={MAPVAR} is replaced by a summary of
 the value of MAPVAR as a keymap.  This summary is similar to the one
@@ -999,7 +1005,7 @@ substitute-command-keys
 output.
 
 Return the original STRING if no substitutions are made.
-Otherwise, return a new string (without any text properties)."
+Otherwise, return a new string."
   (when (not (null string))
     ;; KEYMAP is either nil (which means search all the active
     ;; keymaps) or a specified local map (which means search just that
@@ -1053,12 +1059,15 @@ substitute-command-keys
                                 (where-is-internal fun keymap t))))
                   (if (not key)
                       ;; Function is not on any key.
-                      (progn (insert "M-x ")
-                             (goto-char (+ end-point 3))
-                             (delete-char 1))
+                      (progn
+                        (insert (propertize "M-x "
+                                            'face 'help-key-binding
+                                            'font-lock-face 'help-key-binding))
+                        (goto-char (+ end-point 3))
+                        (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (key-description key)))))
+                    (insert (help--key-description-fontified key)))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
@@ -1172,7 +1181,7 @@ describe-map-tree
                           (concat title
                                   (if prefix
                                       (concat " Starting With "
-                                              (key-description prefix)))
+                                              (help--key-description-fontified prefix)))
                                   ":\n"))
                       "key             binding\n"
                       "---             -------\n")))
@@ -1228,6 +1237,8 @@ help--describe-command
                                              (= help--previous-description-column 32)))
                                     32)
                                    (t 16))))
+    ;; Insert tab without face to avoid using the `help-keymap' face.
+    (insert (propertize "\t" 'face nil 'font-lock-face nil))
     (indent-to description-column 1)
     (setq help--previous-description-column description-column)
     (cond ((symbolp definition)
@@ -1240,6 +1251,8 @@ help--describe-command
 
 (defun help--describe-translation (definition)
   ;; Converted from describe_translation in keymap.c.
+  ;; Insert tab without face to avoid using the `help-keymap' face.
+  (insert (propertize "\t" 'face nil 'font-lock-face nil))
   (indent-to 16 1)
   (cond ((symbolp definition)
          (insert (symbol-name definition) "\n"))
@@ -1351,9 +1364,9 @@ describe-map
               (setq end (caar vect))))
           ;; Now START .. END is the range to describe next.
           ;; Insert the string to describe the event START.
-          (insert (key-description (vector start) prefix))
+          (insert (help--key-description-fontified (vector start) prefix))
           (when (not (eq start end))
-            (insert " .. " (key-description (vector end) prefix)))
+            (insert " .. " (help--key-description-fontified (vector end) prefix)))
           ;; Print a description of the definition of this character.
           ;; Called function will take care of spacing out far enough
           ;; for alignment purposes.
@@ -1420,7 +1433,7 @@ describe-map
 ;;             (setq first nil))
 ;;           (when (and prefix (> (length prefix) 0))
 ;;             (insert (format "%s" prefix)))
-;;           (insert (key-description (vector start-idx) prefix))
+;;           (insert (help--key-description-fontified (vector start-idx) prefix))
 ;;           ;; Find all consecutive characters or rows that have the
 ;;           ;; same definition.
 ;;           (while (equal (keymap--get-keyelt (aref vector (1+ idx)) nil)
@@ -1433,7 +1446,7 @@ describe-map
 ;;             (insert " .. ")
 ;;             (when (and prefix (> (length prefix) 0))
 ;;               (insert (format "%s" prefix)))
-;;             (insert (key-description (vector idx) prefix)))
+;;             (insert (help--key-description-fontified (vector idx) prefix)))
 ;;           (if transl
 ;;               (help--describe-translation definition)
 ;;             (help--describe-command definition))
@@ -1924,6 +1937,8 @@ help-command-error-confusable-suggestions
 (add-function :after command-error-function
               #'help-command-error-confusable-suggestions)
 
+(define-obsolete-function-alias 'help-for-help-internal #'help-for-help "28.1")
+
 \f
 (provide 'help)
 
diff --git a/lisp/isearch.el b/lisp/isearch.el
index e7926ac08c..943e24aa56 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -460,11 +460,11 @@ isearch-help-map
 (make-help-screen isearch-help-for-help-internal
   (purecopy "Type a help option: [bkm] or ?")
   "You have typed %THIS-KEY%, the help character.  Type a Help option:
-\(Type \\<help-map>\\[help-quit] to exit the Help command.)
+\(Type \\<isearch-help-map>\\[help-quit] to exit the Help command.)
 
-b           Display all Isearch key bindings.
-k KEYS      Display full documentation of Isearch key sequence.
-m           Display documentation of Isearch mode.
+\\[isearch-describe-bindings]           Display all Isearch key bindings.
+\\[isearch-describe-key] KEYS      Display full documentation of Isearch key sequence.
+\\[isearch-describe-mode]           Display documentation of Isearch mode.
 
 You can't type here other help keys available in the global help map,
 but outside of this help window when you type them in Isearch mode,
diff --git a/lisp/tooltip.el b/lisp/tooltip.el
index 8e00aa5c2a..af3b86bba7 100644
--- a/lisp/tooltip.el
+++ b/lisp/tooltip.el
@@ -248,7 +248,12 @@ tooltip-show
 	    (setf (alist-get 'border-color params) fg))
 	  (when (stringp bg)
 	    (setf (alist-get 'background-color params) bg))
-	  (x-show-tip (propertize text 'face 'tooltip)
+          ;; Use non-nil APPEND argument below to avoid overriding any
+          ;; faces used in our TEXT.  Among other things, this allows
+          ;; tooltips to use the `help-key-binding' face used in
+          ;; `substitute-command-keys' substitutions.
+          (add-face-text-property 0 (length text) 'tooltip t text)
+          (x-show-tip text
 		      (selected-frame)
 		      params
 		      tooltip-hide-delay
diff --git a/src/keymap.c b/src/keymap.c
index 782931fadf..e38c9b908a 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2846,6 +2846,23 @@ DEFUN ("describe-vector", Fdescribe_vector, Sdescribe_vector, 1, 2, 0,
   return unbind_to (count, Qnil);
 }
 
+static Lisp_Object fontify_key_properties;
+
+static Lisp_Object
+describe_key_maybe_fontify (Lisp_Object str, Lisp_Object prefix,
+				   bool keymap_p)
+{
+  Lisp_Object key_desc = Fkey_description (str, prefix);
+
+  if (keymap_p)
+    return Fadd_text_properties (make_fixnum (0),
+				 make_fixnum (SCHARS (key_desc)),
+				 fontify_key_properties,
+				 key_desc);
+  else
+    return key_desc;
+}
+
 DEFUN ("help--describe-vector", Fhelp__describe_vector, Shelp__describe_vector, 7, 7, 0,
        doc: /* Insert in the current buffer a description of the contents of VECTOR.
 Call DESCRIBER to insert the description of one value found in VECTOR.
@@ -3021,7 +3038,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
       if (!NILP (elt_prefix))
 	insert1 (elt_prefix);
 
-      insert1 (Fkey_description (kludge, prefix));
+      insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 
       /* Find all consecutive characters or rows that have the same
 	 definition.  But, if VECTOR is a char-table, we had better
@@ -3071,7 +3088,7 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
 	  if (!NILP (elt_prefix))
 	    insert1 (elt_prefix);
 
-	  insert1 (Fkey_description (kludge, prefix));
+	  insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 	}
 
       /* Print a description of the definition of this character.
@@ -3200,6 +3217,12 @@ syms_of_keymap (void)
   staticpro (&where_is_cache);
   staticpro (&where_is_cache_keymaps);
 
+  DEFSYM (Qfont_lock_face, "font-lock-face");
+  DEFSYM (Qhelp_key_binding, "help-key-binding");
+  staticpro (&fontify_key_properties);
+  fontify_key_properties = Fcons (Qfont_lock_face,
+				  Fcons (Qhelp_key_binding, Qnil));
+
   defsubr (&Skeymapp);
   defsubr (&Skeymap_parent);
   defsubr (&Skeymap_prompt);
-- 
2.30.1

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 6 Mar 2021 11:32:45 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> > OK, we can add a note to that effect to the `help-key-binding'
> > docstring.
> 
> Here's an updated patch.  The changes from the previous patch are all in
> the definition of the `help-key-binding' face.
> 
> Let me know if there is anything else to change before this can go in.

Thanks, I see only minor nits, this can go in once they are taken care
of.

> +*** Keybindings in 'help-mode' use the new `help-key-binding' face.

I think this should mention substitute-command-keys, and say that any
text that is run through that function will be propertized.  I'd also
mention the effect on tooltips there.

> +(defface help-key-binding
> +  '((((class color) (min-colors 88)) :foreground "ForestGreen")
> +    (((class color) (min-colors 16)) :foreground "green")
> +    (((class color) (min-colors 8)) :foreground "green")

The last 2 lines are unnecessary: the TTY color translation will do
that automatically.

> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -104,8 +104,8 @@ help-map
>      (define-key map "R" 'info-display-manual)
>      (define-key map "s" 'describe-syntax)
>      (define-key map "t" 'help-with-tutorial)
> -    (define-key map "w" 'where-is)
>      (define-key map "v" 'describe-variable)
> +    (define-key map "w" 'where-is)
>      (define-key map "q" 'help-quit)

Why the change in the order?

>                        ;; Function is not on any key.
> -                      (progn (insert "M-x ")
> -                             (goto-char (+ end-point 3))
> -                             (delete-char 1))
> +                      (progn
> +                        (insert (propertize "M-x "
> +                                            'face 'help-key-binding
> +                                            'font-lock-face 'help-key-binding))

Why are we fontifying "M-x" here?

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, I see only minor nits, this can go in once they are taken care
> of.

Thank you for reviewing the patch.

>> +*** Keybindings in 'help-mode' use the new `help-key-binding' face.
>
> I think this should mention substitute-command-keys, and say that any
> text that is run through that function will be propertized.  I'd also
> mention the effect on tooltips there.

How about this:

*** Keybindings in 'help-mode' use the new 'help-key-binding' face.
This face is added by 'substitute-command-keys' to any "\[command]"
substitution.  The return value of that function should consequently
be assumed to be a propertized string.

Note that the new face will also be used in tooltips.  When using the
GTK toolkit, this is only true if 'x-gtk-use-system-tooltips' is t.

>> --- a/lisp/help.el
>> +++ b/lisp/help.el
>> @@ -104,8 +104,8 @@ help-map
>>      (define-key map "R" 'info-display-manual)
>>      (define-key map "s" 'describe-syntax)
>>      (define-key map "t" 'help-with-tutorial)
>> -    (define-key map "w" 'where-is)
>>      (define-key map "v" 'describe-variable)
>> +    (define-key map "w" 'where-is)
>>      (define-key map "q" 'help-quit)
>
> Why the change in the order?

It's just to make them alphabetical.  If it is too minor, I can leave it
out.

>> +                        (insert (propertize "M-x "
>> +                                            'face 'help-key-binding
>> +                                            'font-lock-face 'help-key-binding))
>
> Why are we fontifying "M-x" here?

I understand "M-x" to be part of the keybinding for that command, so I
think it makes sense to use the same face for that part too.  IOW,
rather than fontifying only "apropos" in "M-x apropos" we fontify the
whole string.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 6 Mar 2021 22:03:05 -0500
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> >> +*** Keybindings in 'help-mode' use the new `help-key-binding' face.
> >
> > I think this should mention substitute-command-keys, and say that any
> > text that is run through that function will be propertized.  I'd also
> > mention the effect on tooltips there.
> 
> How about this:
> 
> *** Keybindings in 'help-mode' use the new 'help-key-binding' face.
> This face is added by 'substitute-command-keys' to any "\[command]"
> substitution.  The return value of that function should consequently
> be assumed to be a propertized string.
> 
> Note that the new face will also be used in tooltips.  When using the
> GTK toolkit, this is only true if 'x-gtk-use-system-tooltips' is t.

SGTM, thanks.

> >> --- a/lisp/help.el
> >> +++ b/lisp/help.el
> >> @@ -104,8 +104,8 @@ help-map
> >>      (define-key map "R" 'info-display-manual)
> >>      (define-key map "s" 'describe-syntax)
> >>      (define-key map "t" 'help-with-tutorial)
> >> -    (define-key map "w" 'where-is)
> >>      (define-key map "v" 'describe-variable)
> >> +    (define-key map "w" 'where-is)
> >>      (define-key map "q" 'help-quit)
> >
> > Why the change in the order?
> 
> It's just to make them alphabetical.

That's what I thought, but then "q" is out of order, isn't it?

> >> +                        (insert (propertize "M-x "
> >> +                                            'face 'help-key-binding
> >> +                                            'font-lock-face 'help-key-binding))
> >
> > Why are we fontifying "M-x" here?
> 
> I understand "M-x" to be part of the keybinding for that command, so I
> think it makes sense to use the same face for that part too.  IOW,
> rather than fontifying only "apropos" in "M-x apropos" we fontify the
> whole string.

I'm not sure it's a good idea.  "M-x foobar" is not a key sequence in
the sense we use it for this feature, I think.  This feature is not
about displaying any key sequence in any context, it's about
displaying them in the context of help-related text.

But I have no strong opinions here.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> It's just to make them alphabetical.
>
> That's what I thought, but then "q" is out of order, isn't it?

Sure.  I left it as it seemed to have been intentionally placed at the
end -- the quit command is "special".  But I don't have any strong
preferences here, so please let me know if you want something changed.

> I'm not sure it's a good idea.  "M-x foobar" is not a key sequence in
> the sense we use it for this feature, I think.  This feature is not
> about displaying any key sequence in any context, it's about
> displaying them in the context of help-related text.

My thinking here is that the face should separate "anything that the
user could type to run a command" from the surrounding body text.  In
this sense, there is no strong difference between an unbound command and
an actual keybinding.  It just seems more helpful.

I don't see any obvious problems with this approach, but perhaps there
is something that I'm overlooking.

BTW, there was a bug in the above code where only the "M-x" part was
fontified, now fixed:

modified   lisp/help.el
@@ -1056,11 +1056,12 @@ substitute-command-keys
                                 (where-is-internal fun keymap t))))
                   (if (not key)
                       ;; Function is not on any key.
-                      (progn
-                        (insert (propertize "M-x "
-                                            'face 'help-key-binding
-                                            'font-lock-face 'help-key-binding))
+                      (let ((op (point)))
+                        (insert "M-x ")
                         (goto-char (+ end-point 3))
+                        (add-text-properties op (point)
+                                             '( face help-key-binding
+                                                font-lock-face
help-key-binding))
                         (delete-char 1))

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 7 Mar 2021 02:26:27 -0500
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> It's just to make them alphabetical.
> >
> > That's what I thought, but then "q" is out of order, isn't it?
> 
> Sure.  I left it as it seemed to have been intentionally placed at the
> end -- the quit command is "special".  But I don't have any strong
> preferences here, so please let me know if you want something changed.

Up to you, it's really a nit that isn't worth arguing about.

> > I'm not sure it's a good idea.  "M-x foobar" is not a key sequence in
> > the sense we use it for this feature, I think.  This feature is not
> > about displaying any key sequence in any context, it's about
> > displaying them in the context of help-related text.
> 
> My thinking here is that the face should separate "anything that the
> user could type to run a command" from the surrounding body text.  In
> this sense, there is no strong difference between an unbound command and
> an actual keybinding.  It just seems more helpful.
> 
> I don't see any obvious problems with this approach, but perhaps there
> is something that I'm overlooking.
> 
> BTW, there was a bug in the above code where only the "M-x" part was
> fontified, now fixed:

Fine with me, thanks.

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

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 628 bytes --]

> +(defface help-key-binding
> +  '((((class color) (min-colors 88)) :foreground "ForestGreen")
> +    (((class color) (min-colors 16)) :foreground "green")
> +    (((class color) (min-colors 8)) :foreground "green")
> +    (((class color grayscale) (background light)) :foreground "grey15")
> +    (((class color grayscale) (background dark)) :foreground "grey85")
> +    (t :foreground "ForestGreen"))
> +  "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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: help-key-binding-background-grey.patch --]
[-- Type: text/x-diff, Size: 992 bytes --]

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.
 
 This face is added by `substitute-command-keys', which see.

[-- Attachment #3: Type: text/plain, Size: 198 bytes --]


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

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.  :-(

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

[Juri Linkov]

>>  (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).

I completely agree.  I retained "grey85" that was used for foreground,
but it's not suitable for background.  But OTOH, "grey95" is almost
indistinguishable from the default white background.

GitHub and GitLab use "grey90" for light and "grey25" for dark,
so I changed now accordingly.

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

These faces look nice on a terminal.

> 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.)

When trying to use the style :background "grey90"
:box (:line-width 2 :style released-button)
the look is much nicer, but at the cost of wasting more vertical space
for higher lines.

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

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> I completely agree.  I retained "grey85" that was used for foreground,
> but it's not suitable for background.  But OTOH, "grey95" is almost
> indistinguishable from the default white background.

The change is fine, but I have a nit/question:

On my screen grey95 is clearly distinguishable while grey90 is too dark
for comfort.  You report something quite different from that, which
makes me think that this is perhaps not simply down to taste or
mere subjective opinion.

Could this be associated with things like differences in luminosity of
our physical monitors, brightness/contrast settings, X gamma settings
and what have you?

Is there a way to find an objective measure to decide the better default
here?  Or should we just make both of us slightly (un)?happy by setting
the color to e.g. grey92, assuming that the mean between our findings is
the most scientific we can hope to get and will work somewhat okay-ish
everywhere, and call it a day?

> GitHub and GitLab use "grey90" for light and "grey25" for dark,
> so I changed now accordingly.

BTW, where do you find "grey90"?  They seem to use a lighter background
than that on the pages I've been looking at.

Here I see #fafbfc for keys, which is between gray98 and gray99, with an
added outline:

https://docs.github.com/en/github/getting-started-with-github/keyboard-shortcuts

Here I see #f0f0f0 for keys, which is gray94, with no added outline:

https://docs.gitlab.com/ee/user/shortcuts.html

> When trying to use the style :background "grey90"
> :box (:line-width 2 :style released-button)
> the look is much nicer, but at the cost of wasting more vertical space
> for higher lines.

The look of that is not too bad.  It looks slightly dated perhaps (the
latest trend is to keep things flat rather than fake 3D) but at least it
is extremely clear.  It is arguably a more user-friendly choice.

I'm not sure that I notice any wasted vertical pixels (we are talking 1
or 2 of them or something like that, right?) but I didn't measure it.

(This would likely look even better if we could allow for a pixel or two
of vertical space between the keys to allow them more space to breathe.
But I can't find any way to specify something like that, so perhaps that
would require some C level changes so perhaps we don't want to go to
those lengths.  And if really want to dive in the deep end, I'd also
throw in some padding and rounded corners...)

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

[Juri Linkov]

>> I completely agree.  I retained "grey85" that was used for foreground,
>> but it's not suitable for background.  But OTOH, "grey95" is almost
>> indistinguishable from the default white background.
>
> The change is fine, but I have a nit/question:
>
> On my screen grey95 is clearly distinguishable while grey90 is too dark
> for comfort.  You report something quite different from that, which
> makes me think that this is perhaps not simply down to taste or
> mere subjective opinion.

When the contrast with the default background is too low, then users
will miss the highlighting, so when the user doesn't see that it has
a different color then it will look as if there is no highlighting at all.
But when it's slightly darker, then I see no problem for users.
So it seems better to have a slightly darker color than to let users
miss highlighting.

To decide what would be a good default, you need to take into accounts
opinions of the majority of users, but also possible problems
that the default could cause to the minority of users.

> Could this be associated with things like differences in luminosity of
> our physical monitors, brightness/contrast settings, X gamma settings
> and what have you?

Maybe, I tried grey95, but when the prompt us at the bottom of the screen:

  foo changed on disk; really edit the buffer? (y, n, r or C-h) 

highlighting of single letters is indistinguishable from the background.

> Is there a way to find an objective measure to decide the better default
> here?  Or should we just make both of us slightly (un)?happy by setting
> the color to e.g. grey92, assuming that the mean between our findings is
> the most scientific we can hope to get and will work somewhat okay-ish
> everywhere, and call it a day?

With grey92 the situation is slightly better.

>> GitHub and GitLab use "grey90" for light and "grey25" for dark,
>> so I changed now accordingly.
>
> BTW, where do you find "grey90"?  They seem to use a lighter background
> than that on the pages I've been looking at.

I deduced this color approximately because on github repos
shades of gray are achieved using transparency.

> Here I see #fafbfc for keys, which is between gray98 and gray99, with an
> added outline:
>
> https://docs.github.com/en/github/getting-started-with-github/keyboard-shortcuts

Indeed, with a border, it's hard to miss highlighting.

> Here I see #f0f0f0 for keys, which is gray94, with no added outline:
>
> https://docs.gitlab.com/ee/user/shortcuts.html

Here there is no border, so they need to use darker colors,
darker than gray95.

So please decide what the default color would be more preferable:
with a border a lighter color could be used, without a border
a darker is needed.

>> When trying to use the style :background "grey90"
>> :box (:line-width 2 :style released-button)
>> the look is much nicer, but at the cost of wasting more vertical space
>> for higher lines.
>
> The look of that is not too bad.  It looks slightly dated perhaps (the
> latest trend is to keep things flat rather than fake 3D) but at least it
> is extremely clear.  It is arguably a more user-friendly choice.

Then it's possible to use flat with rounded borders, without 3D effect.

> I'm not sure that I notice any wasted vertical pixels (we are talking 1
> or 2 of them or something like that, right?) but I didn't measure it.

2 pixels (top and bottom) for line-width 1, 4 pixels for line-width 2.
Especially undesirable when this will increase the height of the minibuffer.

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

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> When the contrast with the default background is too low, then users
> will miss the highlighting, so when the user doesn't see that it has
> a different color then it will look as if there is no highlighting at all.

Yes, we definitely want to avoid that situation.

> But when it's slightly darker, then I see no problem for users.
> So it seems better to have a slightly darker color than to let users
> miss highlighting.
>
> To decide what would be a good default, you need to take into accounts
> opinions of the majority of users, but also possible problems
> that the default could cause to the minority of users.

Good, I think we agree on the principles.

The problem I have, and again that's just with my combination of eyes
and monitor, I find it hard to read when the background is too dark.

I suspect that my screen is simply darker than yours for some reason.
(Or my eyes are less sensitive to light, if that's a thing.)

> Maybe, I tried grey95, but when the prompt us at the bottom of the screen:
>
>   foo changed on disk; really edit the buffer? (y, n, r or C-h)
>
> highlighting of single letters is indistinguishable from the background.

This confirms that our situations are indeed different.

>> Here I see #fafbfc for keys, which is between gray98 and gray99, with an
>> added outline:
>>
>> https://docs.github.com/en/github/getting-started-with-github/keyboard-shortcuts
>
> Indeed, with a border, it's hard to miss highlighting.
[...]
> Then it's possible to use flat with rounded borders, without 3D effect.

What do you think of something like:

     :background "grey92" :foreground "DarkBlue"
     :box (:line-width 1 :color "grey80"))

On my screen, this is legible.  The DarkBlue and border makes it at the
same time stand out as highlighted.

I'm very open to another color (or indeed none at all, but it stands out
a bit more to me with something lighter than #000).  For me the DarkBlue
is very subtle, and my wife tells me the same (using her own set of
eyes, but my monitor).

If it doesn't work very well in your situation, could you propose
something which does?  Maybe we can tweak it so it is acceptable (or
even good) for us both, and then hope for the best.  With a bit of luck,
we are both close to the extreme ends of the spectrum here.  This
assumption could of course be wildly inaccurate, but then we can only
hope that someone protests.

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

[Juri Linkov]

> What do you think of something like:
>
>      :background "grey92" :foreground "DarkBlue"
>      :box (:line-width 1 :color "grey80"))
>
> On my screen, this is legible.  The DarkBlue and border makes it at the
> same time stand out as highlighted.

This looks nice.  I suppose DarkBlue is intended to make it look more
like a link when help-link-key-to-documentation is non-nil?

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

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  larsi@gnus.org,  emacs-devel@gnu.org
> Date: Wed, 10 Mar 2021 21:50:51 +0200
> 
> > What do you think of something like:
> >
> >      :background "grey92" :foreground "DarkBlue"
> >      :box (:line-width 1 :color "grey80"))
> >
> > On my screen, this is legible.  The DarkBlue and border makes it at the
> > same time stand out as highlighted.

Doesn't using :box cause a small 2-pixel rise of the mode line?  If it
does, that could be regarded as annoyance by some users, because the
text above the mode line might scroll.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Doesn't using :box cause a small 2-pixel rise of the mode line?  If it
> does, that could be regarded as annoyance by some users, because the
> text above the mode line might scroll.

Yes, it does.  Thanks for pointing this out.

It is indeed a slight annoyance once you notice it.  (But I don't see
any scrolling, so I guess this depends on things like window size and
font size?)

Is there anything we could do to avoid this if we use :box?  Is it
annoying enough to avoid :box completely?

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

[Stefan Monnier]

> Is there anything we could do to avoid this if we use :box?  Is it
> annoying enough to avoid :box completely?

For the modeline, the solution was to use a negative width for the box.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 10 Mar 2021 22:09:43 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org, larsi@gnus.org,
>  Juri Linkov <juri@linkov.net>
> 
> > Is there anything we could do to avoid this if we use :box?  Is it
> > annoying enough to avoid :box completely?
> 
> For the modeline, the solution was to use a negative width for the box.
                                                       ^^^^^
You meant "height", right?

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

[Stefan Monnier]

>> > Is there anything we could do to avoid this if we use :box?  Is it
>> > annoying enough to avoid :box completely?
>> For the modeline, the solution was to use a negative width for the box.
>                                                        ^^^^^
> You meant "height", right?

I think I actually meant "thickness" (regardless of orientation), but
yes, the issue is clearly with the vertical size rather than the
horizontal one, sorry.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 11 Mar 2021 08:25:40 -0500
> Cc: larsi@gnus.org, juri@linkov.net, stefan@marxist.se, emacs-devel@gnu.org
> 
> >> For the modeline, the solution was to use a negative width for the box.
> >                                                        ^^^^^
> > You meant "height", right?
> 
> I think I actually meant "thickness" (regardless of orientation), but
> yes, the issue is clearly with the vertical size rather than the
> horizontal one, sorry.

AFAIR, the :box attribute can be asked to use one thickness in the
horizontal dimension and another in the vertical one.

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

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Is there anything we could do to avoid this if we use :box?  Is it
>> annoying enough to avoid :box completely?
>
> For the modeline, the solution was to use a negative width for the box.

Thanks, that fixes the issue with the resizing minibuffer.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 10 Mar 2021 18:46:01 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Doesn't using :box cause a small 2-pixel rise of the mode line?  If it
> > does, that could be regarded as annoyance by some users, because the
> > text above the mode line might scroll.
> 
> Yes, it does.  Thanks for pointing this out.
> 
> It is indeed a slight annoyance once you notice it.  (But I don't see
> any scrolling, so I guess this depends on things like window size and
> font size?)

The scrolling will happen when both of the following conditions are
true:

 . point is on the last line of the bottom-most window
 . the enlarged mini-window makes that last line only partially visible

> Is there anything we could do to avoid this if we use :box?

Stefan answered that, not sure if you will like the looks of the
result.

> Is it annoying enough to avoid :box completely?

IMO, it depends on the frequency of the occurrence.  It was enough for
me to customize eldoc face to use :underline instead of :bold, because
the latter would cause a similar effect.  But that's my level of
annoyance; others might feel differently.  So perhaps advertise the
way to avoid that by customizing the face, and then let's see how many
complaints we get from users who track the master branch.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Is it annoying enough to avoid :box completely?
>
> IMO, it depends on the frequency of the occurrence.  It was enough for
> me to customize eldoc face to use :underline instead of :bold, because
> the latter would cause a similar effect.  But that's my level of
> annoyance; others might feel differently.  So perhaps advertise the
> way to avoid that by customizing the face, and then let's see how many
> complaints we get from users who track the master branch.

I was able to avoid any vertical resizing using the advice from Stefan M.
So I pushed the following change to master:

modified   lisp/faces.el
@@ -2816,8 +2816,12 @@ help-argument-name
   :group 'help)

 (defface help-key-binding
-  '((((class color) (min-colors 88) (background light)) :background "grey90")
-    (((class color) (min-colors 88) (background dark)) :background "grey25")
+  '((((class color) (min-colors 88) (background light))
+     :background "grey92" :foreground "DarkBlue"
+     :box (:line-width (1 . -1) :color "grey80"))
+    (((class color) (min-colors 88) (background dark))
+     :background "grey23" :foreground "LightBlue"
+     :box (:line-width (1 . -1) :color "grey35"))
     (((class color grayscale) (background light)) :background "grey90")
     (((class color grayscale) (background dark)) :background "grey25")

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 13 Mar 2021 08:27:05 -0600
> Cc: larsi@gnus.org, juri@linkov.net, emacs-devel@gnu.org
> 
> I was able to avoid any vertical resizing using the advice from Stefan M.
> So I pushed the following change to master:
> 
> modified   lisp/faces.el
> @@ -2816,8 +2816,12 @@ help-argument-name
>    :group 'help)
> 
>  (defface help-key-binding
> -  '((((class color) (min-colors 88) (background light)) :background "grey90")
> -    (((class color) (min-colors 88) (background dark)) :background "grey25")
> +  '((((class color) (min-colors 88) (background light))
> +     :background "grey92" :foreground "DarkBlue"
> +     :box (:line-width (1 . -1) :color "grey80"))
> +    (((class color) (min-colors 88) (background dark))
> +     :background "grey23" :foreground "LightBlue"
> +     :box (:line-width (1 . -1) :color "grey35"))
>      (((class color grayscale) (background light)) :background "grey90")
>      (((class color grayscale) (background dark)) :background "grey25")

Thanks, but such non-trivial stuff should always be accompanied by a
comment to explain why we do that.  I added such a comment in this
case, but please in the future make sure to leave a comment.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, but such non-trivial stuff should always be accompanied by a
> comment to explain why we do that.  I added such a comment in this
> case, but please in the future make sure to leave a comment.

Will do, thanks.

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

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

>> What do you think of something like:
>>
>>      :background "grey92" :foreground "DarkBlue"
>>      :box (:line-width 1 :color "grey80"))
>>
>> On my screen, this is legible.  The DarkBlue and border makes it at the
>> same time stand out as highlighted.
>
> This looks nice.

Great, thanks.

> I suppose DarkBlue is intended to make it look more like a link when
> help-link-key-to-documentation is non-nil?

Something like that, yes.

Mostly I just wanted to make it brighter without making it more grey,
i.e. "highlight" it more.  Blue seemed a non-opinionated choice, as we
already have some blue in the help buffer, and yes it also makes sense
due to the planned linking.

But this choice of colour is 100 % open for discussion, so feel free to
suggest something better if you prefer.  There is no strong need to use
blue, I think; we could have some other convention.

(We should probably avoid having our help buffers light up like a
Christmas tree, though.  And every "new" colour arguably takes us
further down that slippery slope.  Which doesn't stop us from adding
them, of course, but we should do it a bit carefully.)

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

[Juri Linkov]

>> I suppose DarkBlue is intended to make it look more like a link when
>> help-link-key-to-documentation is non-nil?
>
> Something like that, yes.
>
> Mostly I just wanted to make it brighter without making it more grey,
> i.e. "highlight" it more.  Blue seemed a non-opinionated choice, as we
> already have some blue in the help buffer, and yes it also makes sense
> due to the planned linking.

Now that we have a clearly visible border, it's possible to use
the background that you proposed earlier - grey95 that looks nicer
when there is already heavy highlighting with a border and blue foreground.

BTW, after the recent change of adding a border to widget-field,
its border is indistinguishable from the background color.
It would help to make the border color slightly darker, e.g. gray70.

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

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> Now that we have a clearly visible border, it's possible to use
> the background that you proposed earlier - grey95 that looks nicer
> when there is already heavy highlighting with a border and blue foreground.

OK, I'll look into it.  Thanks.

> BTW, after the recent change of adding a border to widget-field,
> its border is indistinguishable from the background color.
> It would help to make the border color slightly darker, e.g. gray70.

Yes, it achieves something more akin to a shading than a distinct
border.  The idea was to "subtly" make it stand out more as an editable
field.  But perhaps a distinct border would be better for that purpose?

Looking at Material design, they have a very nice and clear look for
their input fields:

    https://material.io/components/text-fields

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

[Dmitry Gutov]

On 15.03.2021 11:19, Juri Linkov wrote:
> Now that we have a clearly visible border, it's possible to use
> the background that you proposed earlier - grey95 that looks nicer
> when there is already heavy highlighting with a border and blue foreground.

+1

Either way, good job making key sequences stand out better and look more 
"fresh".

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

[Drew Adams]

> 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

Why just a face, at all?  Why not a _link_ to
help for the key sequence?

(And we already have code that does that.  Why
reinvent the wheel, giving it sharp corners?)

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> Why just a face, at all?  Why not a _link_ to
> help for the key sequence?

Yes, why not?

> (And we already have code that does that.  Why
> reinvent the wheel, giving it sharp corners?)

You forgot to attach the patch.

But in any case, a) this is not helpful and b) what "re-invented wheel"
are you talking about?  Do you perhaps mean a "wheel" that does this:

@@ -1065,7 +1073,11 @@ substitute-command-keys
                         (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (help--key-description-fontified key)))))
+                    (insert (if (functionp fun)
+                                (make-text-button key nil
+                                                  'type 'help-function
+                                                  'help-args (list fun)))
+                              (help--key-description-fontified key)))))))

Does that code look correct to you?

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

[Juri Linkov]

>> Why just a face, at all?  Why not a _link_ to
>> help for the key sequence?
>
> Yes, why not?

It would be nice to keep the current face 'help-key-binding'
even after adding links.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 839 bytes --]

Juri Linkov <juri@linkov.net> writes:

> It would be nice to keep the current face 'help-key-binding'
> even after adding links.

Yes, as it happens that is exactly what I'm currently experimenting
with.  See the attached patch if you want to try it out; I think the
effect is quite nice.

But I'm seeing bootstrap problems if I flip the new option here to t, so
we couldn't use it as the default in its current form.

[The problem is that the button type `help-function' is defined in
help-mode.el, but that file is not autoloaded (and help.el is).  There
are several ways to fix it, but I haven't yet had time to think about
which is better.  (For example, we could force the option to nil during
bootstrap.  Or we could just move the button definitions into its own
file or into help.el to make sure they are there during bootstrap.) ]

[-- Attachment #2: 0001-Add-new-option-help-link-key-to-documentation.patch --]
[-- Type: text/x-diff, Size: 3243 bytes --]

From 937e2ed9d7b5a1a43f199c8342ed9ee2aaa7cac8 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 5 Mar 2021 02:49:07 +0100
Subject: [PATCH] Add new option help-link-key-to-documentation

* lisp/help.el (help-link-key-to-documentation): New option.
(substitute-command-keys): Add link from keys to the command they
are bound to if above new option is non-nil.  (Bug#8951)
* etc/NEWS: Announce the new option.
---
 etc/NEWS          |  7 +++++++
 lisp/help-mode.el |  7 +++++++
 lisp/help.el      | 14 +++++++++++++-
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index ce337e7517..4c3f2418a3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -928,6 +928,13 @@ be assumed to be a propertized string.
 Note that the new face will also be used in tooltips.  When using the
 GTK toolkit, this is only true if 'x-gtk-use-system-tooltips' is t.
 
+---
+*** New user option `help-link-key-to-documentation'.
+When this option is non-nil, key bindings displayed in the *Help*
+buffer will be linked to the documentation for the command they are
+bound to.  Note that this does not affect listings of key bindings and
+functions.
+
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index c7eaae5feb..7691002f7f 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -321,6 +321,13 @@ 'help-news
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+;;;###autoload
+(defun help-mode--add-function-link (str fun)
+  (make-text-button (copy-sequence str) nil
+                    'type 'help-function
+                    'help-args (list fun)))
+
 \f
 (defvar bookmark-make-record-function)
 
diff --git a/lisp/help.el b/lisp/help.el
index 94073e5730..cc624d5737 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -978,6 +978,14 @@ lookup-minor-mode-from-indicator
     result))
 
 \f
+(defcustom help-link-key-to-documentation nil
+  "Non-nil means to link keys to their command in *Help* buffers.
+This affects \\\\=\\[command] substitutions in documentation
+strings done by `substitute-command-keys'.  "
+  :type 'boolean
+  :version "28.1"
+  :group 'help)
+
 (defun substitute-command-keys (string)
   "Substitute key descriptions for command names in STRING.
 Each substring of the form \\\\=[COMMAND] is replaced by either a
@@ -1065,7 +1073,11 @@ substitute-command-keys
                         (delete-char 1))
                     ;; Function is on a key.
                     (delete-char (- end-point (point)))
-                    (insert (help--key-description-fontified key)))))
+                    (let ((key (help--key-description-fontified key)))
+                      (insert (if (and help-link-key-to-documentation
+                                       (functionp fun))
+                                  (help-mode--add-function-link key fun)
+                                key))))))
                ;; 1D. \{foo} is replaced with a summary of the keymap
                ;;            (symbol-value foo).
                ;;     \<foo> just sets the keymap used for \[cmd].
-- 
2.30.1

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

[Juri Linkov]

>> It would be nice to keep the current face 'help-key-binding'
>> even after adding links.
>
> Yes, as it happens that is exactly what I'm currently experimenting
> with.  See the attached patch if you want to try it out; I think the
> effect is quite nice.

Thanks, I tested your patch and everything is nice.

> But I'm seeing bootstrap problems if I flip the new option here to t, so
> we couldn't use it as the default in its current form.
>
> [The problem is that the button type `help-function' is defined in
> help-mode.el, but that file is not autoloaded (and help.el is).  There
> are several ways to fix it, but I haven't yet had time to think about
> which is better.  (For example, we could force the option to nil during
> bootstrap.  Or we could just move the button definitions into its own
> file or into help.el to make sure they are there during bootstrap.) ]

Enabling it by default would be nice too if you will find a solution for
bootstraping problem.  Here's what it looks like when trying to bootstrap:

  ELC      emacs-lisp/autoload.elc
Debugger entered--Lisp error: (void-function help-mode--add-function-link)
  (help-mode--add-function-link key fun)
  ...
  substitute-command-keys("Memory exhausted--use \\[save-some-buffers] then ex...")
  ...
  command-line()

So either the option should be disabled or the function be available
during bootstrap.

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

[Drew Adams]

> (defface help-key-binding '((t :foreground "RoyalBlue3"))

IMO, that's too close to link color, which is "blue1".

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

[martin rudalics]

 > 2. M-: (insert (propertize "foo" 'help-echo "foo \\[forward-line]")) RET
 >
 > No visible effect on the tooltip --with-x-toolkit={gtk,lucid,athena,no}.

It should work with 'x-show-tip'.

martin

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 23 Feb 2021 19:40:07 -0600
> Cc: emacs-devel@gnu.org
> 
> --- a/src/keymap.c
> +++ b/src/keymap.c
> @@ -3021,7 +3021,10 @@ describe_vector (Lisp_Object vector, Lisp_Object prefix, Lisp_Object args,
>        if (!NILP (elt_prefix))
>  	insert1 (elt_prefix);
>  
> -      insert1 (Fkey_description (kludge, prefix));
> +      Lisp_Object desc = Fkey_description (kludge, prefix);
> +      if (keymap_p)
> +	desc = CALLN (Fpropertize, desc, Qfont_lock_face, Qhelp_key_binding);
> +      insert1 (desc);

Using Fpropertize here is suboptimal: it does several thing you don't
need when calling it from C, including consing a new string, which is
just a waste of cycles.

Please use Fadd_text_properties instead.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Using Fpropertize here is suboptimal: it does several thing you don't
> need when calling it from C, including consing a new string, which is
> just a waste of cycles.
>
> Please use Fadd_text_properties instead.

How's this?

diff --git a/src/keymap.c b/src/keymap.c
index 782931fadf..e38c9b908a 100644
--- a/src/keymap.c
+++ b/src/keymap.c
@@ -2846,6 +2846,23 @@ DEFUN ("describe-vector", Fdescribe_vector,
Sdescribe_vector, 1, 2, 0,
   return unbind_to (count, Qnil);
 }

+static Lisp_Object fontify_key_properties;
+
+static Lisp_Object
+describe_key_maybe_fontify (Lisp_Object str, Lisp_Object prefix,
+				   bool keymap_p)
+{
+  Lisp_Object key_desc = Fkey_description (str, prefix);
+
+  if (keymap_p)
+    return Fadd_text_properties (make_fixnum (0),
+				 make_fixnum (SCHARS (key_desc)),
+				 fontify_key_properties,
+				 key_desc);
+  else
+    return key_desc;
+}
+
 DEFUN ("help--describe-vector", Fhelp__describe_vector,
Shelp__describe_vector, 7, 7, 0,
        doc: /* Insert in the current buffer a description of the
contents of VECTOR.
 Call DESCRIBER to insert the description of one value found in VECTOR.
@@ -3021,7 +3038,7 @@ describe_vector (Lisp_Object vector, Lisp_Object
prefix, Lisp_Object args,
       if (!NILP (elt_prefix))
 	insert1 (elt_prefix);

-      insert1 (Fkey_description (kludge, prefix));
+      insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));

       /* Find all consecutive characters or rows that have the same
 	 definition.  But, if VECTOR is a char-table, we had better
@@ -3071,7 +3088,7 @@ describe_vector (Lisp_Object vector, Lisp_Object
prefix, Lisp_Object args,
 	  if (!NILP (elt_prefix))
 	    insert1 (elt_prefix);

-	  insert1 (Fkey_description (kludge, prefix));
+	  insert1 (describe_key_maybe_fontify (kludge, prefix, keymap_p));
 	}

       /* Print a description of the definition of this character.
@@ -3200,6 +3217,12 @@ syms_of_keymap (void)
   staticpro (&where_is_cache);
   staticpro (&where_is_cache_keymaps);

+  DEFSYM (Qfont_lock_face, "font-lock-face");
+  DEFSYM (Qhelp_key_binding, "help-key-binding");
+  staticpro (&fontify_key_properties);
+  fontify_key_properties = Fcons (Qfont_lock_face,
+				  Fcons (Qhelp_key_binding, Qnil));
+
   defsubr (&Skeymapp);
   defsubr (&Skeymap_parent);
   defsubr (&Skeymap_prompt);

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 24 Feb 2021 19:56:00 -0600
> Cc: larsi@gnus.org, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Using Fpropertize here is suboptimal: it does several thing you don't
> > need when calling it from C, including consing a new string, which is
> > just a waste of cycles.
> >
> > Please use Fadd_text_properties instead.
> 
> How's this?

LGTM, thanks.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 06:06:58 -0600
> 
> One of the usability complaints I've heard is that `help-for-help'
> (`C-h C-h') could be better organized.  I also think some colors could
> really help in making it easier to navigate.
> 
> I have attached a rough draft for what an improved version of might look
> like.  It would be great to get some feedback.

Please explain the rationale for the order.  It is different from the
order in the manual and in the menus, so we should at least discuss
it, and that needs some rationale.

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> Please explain the rationale for the order.  It is different from the
> order in the manual and in the menus, so we should at least discuss
> it, and that needs some rationale.

Agreed, the order is important - should be
considered carefully.

(I don't have any suggestions about that,
at least not yet.)

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Please explain the rationale for the order.  It is different from the
> order in the manual and in the menus, so we should at least discuss
> it, and that needs some rationale.

This was mostly to give a quick example of how it could look.
Sorry for not being more clear.

I agree that we need to think seriously about what the best ordering is,
also compared to the manual.

If the general direction here is okay, I will provide a full proposal,
including thinking through the order.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 12:48:20 -0600
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Please explain the rationale for the order.  It is different from the
> > order in the manual and in the menus, so we should at least discuss
> > it, and that needs some rationale.
> 
> This was mostly to give a quick example of how it could look.
> Sorry for not being more clear.

Ah, okay.  You said you didn't care for the current order, so I
thought the order you suggested was based on some principles yhou
could describe.

> I agree that we need to think seriously about what the best ordering is,
> also compared to the manual.
> 
> If the general direction here is okay, I will provide a full proposal,
> including thinking through the order.

If the order is not the aspect you wanted us to consider, then which
aspects are?  I admit that I didn't give a thought to any other
aspects yet.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Ah, okay.  You said you didn't care for the current order, so I
> thought the order you suggested was based on some principles yhou
> could describe.
>
> If the order is not the aspect you wanted us to consider, then which
> aspects are?  I admit that I didn't give a thought to any other
> aspects yet.

Well, it is roughly, but only very roughly here, based on an idea to put
more important things higher up.  (The thing that makes it "rough" is
that I didn't think through carefully the exact ordering that makes
sense.)  This goes for both the sections and the commands themselves.

Today we just have them in alphabetical order.

In the final section (currently named "Other") I'm not sure we can find
an "order of importance".  Whereas `describe-function' clearly is more
important `describe-local-help'.

I think it would be useful also to get feedback on introducing titled
sections, and the overall visual appearance (including coloring the
keybindings).

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 14:04:51 -0600
> Cc: emacs-devel@gnu.org
> 
> > If the order is not the aspect you wanted us to consider, then which
> > aspects are?  I admit that I didn't give a thought to any other
> > aspects yet.
> 
> Well, it is roughly, but only very roughly here, based on an idea to put
> more important things higher up.  (The thing that makes it "rough" is
> that I didn't think through carefully the exact ordering that makes
> sense.)  This goes for both the sections and the commands themselves.

So it _is_ about the order.  But then I think we should discuss the
underlying principles, and then order the commands accordingly.

The rationale for the order in the manual was to show the discovery
commands first, and the commands for focused help later.

> I think it would be useful also to get feedback on introducing titled
> sections, and the overall visual appearance (including coloring the
> keybindings).

If the aggregation is meaningful, I think having sections should be a
no-brainer.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> So it _is_ about the order.  But then I think we should discuss the
> underlying principles, and then order the commands accordingly.
>
> The rationale for the order in the manual was to show the discovery
> commands first, and the commands for focused help later.

To be honest, I didn't yet think very hard about this problem.  But
sure, we can discuss it.  Any suggestions or ideas are welcome.

My preliminary thinking here is that we should probably start with
something like `describe-mode' and perhaps `describe-bindings' -- things
that are about the basic commands to find help about the task that the
user is engaged in right now.  Maybe together with `describe-key', and
`describe-command'.

Ideally, we would just copy the ordering in the manual.  It would save a
lot of work.  But the Info node `(emacs) Help' puts the Emacs FAQ and
`C-h p' very early, even before `describe-mode'.  I don't think that is
exactly what we want for the `help-for-help'.

So we probably need to think a bit more about this, and how that screen
will be used.

>> I think it would be useful also to get feedback on introducing titled
>> sections, and the overall visual appearance (including coloring the
>> keybindings).
>
> If the aggregation is meaningful, I think having sections should be a
> no-brainer.

That is good to know, thanks.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 17:27:51 -0600
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So it _is_ about the order.  But then I think we should discuss the
> > underlying principles, and then order the commands accordingly.
> >
> > The rationale for the order in the manual was to show the discovery
> > commands first, and the commands for focused help later.
> 
> To be honest, I didn't yet think very hard about this problem.  But
> sure, we can discuss it.  Any suggestions or ideas are welcome.
> 
> My preliminary thinking here is that we should probably start with
> something like `describe-mode' and perhaps `describe-bindings' -- things
> that are about the basic commands to find help about the task that the
> user is engaged in right now.  Maybe together with `describe-key', and
> `describe-command'.

Since there can be different use cases, and each one could favor a
different order, perhaps we should precede a short guide to the list?
Like

  If you look for some feature, try "discovery" group.
  If you look for documentation of a command or a variable or a mode,
  try ...

etc.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 2617 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> If the general direction here is okay, I will provide a full proposal,
> including thinking through the order.

Please find attached an updated proposal.

My overarching goal here has been to design this as an _overview_ of
_important_ and _non-obvious_ information.

This is a summary of the changes:

- Added sections.

- Drastically shortened descriptions of the command.

- Changed ordering to be roughly based on: order of importance, logical
  grouping of related items, and the Emacs manual.

- Removed the indication about which commands will show a prompt.
  [Rationale: I find that information overly pedantic, messy and fully
  redundant; it will either be obvious from context or, at the very
  least, when invoking a given help command.]

I'm not sure what is considered a large attachment these days, so I
posted a screenshot at some image host:

    https://i.imgur.com/Cv67yUN.png

To facilitate the discussion, I have also pasted below the plain text of
the help buffer.  The patch is attached below.


(Type SPC or DEL to scroll, or q to exit.)

Getting Help

   m	Help for current minor and major modes and their commands
   b	Show all key bindings
   k	Show help for key
   c	Show help for key briefly
   w	Show which key runs a given command

   a	Search for commands (see also M-x apropos)
   d	Search documentation of functions, variables, and other items
   f	Show help for function
   o	Show help for function or variable
   v	Show help for variable

Info Manuals

   r	Show Emacs manual
   F	Show Emacs manual section for command
   K	Show Emacs manual section for command bound to key
   i	Show all included manuals
   R	Show given manual
   S	Find symbol in Info manual for current programming language

Misc Help

   p	Search for packages matching topic
   P	Describe Emacs Lisp package
   e	Show recent messages
   g	Show information about the GNU project
   l	Show last 300 input keystrokes (lossage)
   s	Show current syntax table
   .	Show local help at point
   t	Start the Emacs tutorial

Help Files

   C-a	About Emacs
   C-c	Emacs copying permission (GNU General Public License)
   C-d	Debugging GNU Emacs
   C-e	External packages
   C-f	Emacs FAQ
   C-m	Order printed Emacs manuals
   C-n	News of recent Emacs changes
   C-o	Emacs ordering and distribution information
   C-p	Known Emacs problems
   C-t	Emacs TODO
   C-w	Information on absence of warranty for GNU Emacs

Language Help

   C	Describe coding system
   I	Describe input method
   L	Describe language environment
   h	Display the HELLO file illustrating various scripts

[-- Attachment #2: 0001-Improved-help-for-help.patch --]
[-- Type: text/x-diff, Size: 10793 bytes --]

From 2aca7dd78785574d233103bf90e0ac474c1881c5 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Mon, 8 Mar 2021 06:40:08 +0100
Subject: [PATCH] Improved help-for-help

---
 lisp/help-macro.el |   9 ++-
 lisp/help.el       | 156 +++++++++++++++++++++++++++++++--------------
 2 files changed, 114 insertions(+), 51 deletions(-)

diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 72371a8727..22e1181fee 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -132,7 +132,7 @@ make-help-screen
                (when (or (eq char ??) (eq char help-char)
                          (memq char help-event-list))
                  (setq config (current-window-configuration))
-                 (pop-to-buffer " *Metahelp*" nil t)
+                 (pop-to-buffer " *Help Overview*" nil t)
                  (and (fboundp 'make-frame)
                       (not (eq (window-frame)
                                prev-frame))
@@ -166,7 +166,12 @@ make-help-screen
                                 (format "Type one of the options listed%s: "
                                         (if (pos-visible-in-window-p
                                              (point-max))
-                                            "" ", or SPACE or DEL to scroll")))
+                                            ""
+                                          (concat  ", or "
+                                                   (help--key-description-fontified "\s") ; SPC
+                                                   " or "
+                                                   (help--key-description-fontified "\d") ; DEL
+                                                   " to scroll"))))
                            char (aref key 0)))
 
                    ;; If this is a scroll bar command, just run it.
diff --git a/lisp/help.el b/lisp/help.el
index d4be9aa720..5c4dff06b7 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -187,58 +187,116 @@ help-print-return-message
 ;; So keyboard macro definitions are documented correctly
 (fset 'defining-kbd-macro (symbol-function 'start-kbd-macro))
 
+\f
+;;; Help for help.  (a.k.a. `C-h C-h')
+
+(defface help-for-help-header '((t :height 1.26))
+  "Face used for headers in the `help-for-help' buffer."
+  :group 'help)
+
+(defface help-for-help-binding-argument '((t :foreground "PaleGreen3"))
+  "Face used for headers in the `help-for-help' buffer."
+  :group 'help)
+
+(defun help--for-help-make-commands (commands)
+  "Create commands for `help-for-help' screen from COMMANDS."
+  (mapconcat
+   (lambda (cmd)
+     (if (listp cmd)
+         (let ((name (car cmd)) (arg (cadr cmd)) (desc (caddr cmd)))
+           (concat
+            "   "
+            (if (string-match (rx string-start "C-" word string-end) name)
+                ;; `help--key-description-fontified' would convert "C-m" to
+                ;; "RET" so we can't use it here.
+                (propertize name 'face 'help-key-binding)
+              (concat "\\[" name "]"))
+            ;; (if arg
+            ;;     (concat " " (propertize arg 'face 'help-for-help-binding-argument))
+            ;;   "")
+            (propertize "\t" 'display '(space :align-to 8))
+            desc))
+       ""))
+   commands "\n"))
+
+(defun help--for-help-make-sections (sections)
+  "Create sections for `help-for-help' screen from SECTIONS."
+  (mapconcat
+   (lambda (section)
+     (let ((title (car section)) (commands (cdr section)))
+       (concat
+        "\n\n"
+        (propertize (car section) 'face 'help-for-help-header)
+        "\n\n"
+        (help--for-help-make-commands commands))))
+   sections ""))
+
 (defalias 'help 'help-for-help)
 (make-help-screen help-for-help
   (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
-  "You have typed %THIS-KEY%, the help character.  Type a Help option:
-\(Use SPC or DEL to scroll through this text.  Type \\<help-map>\\[help-quit] to exit the Help command.)
-
-\\[apropos-command] PATTERN   Show commands whose name matches the PATTERN (a list of words
-              or a regexp).  See also \\[apropos].
-\\[describe-bindings]           Display all key bindings.
-\\[describe-key-briefly] KEYS      Display the command name run by the given key sequence.
-\\[describe-coding-system] CODING    Describe the given coding system, or RET for current ones.
-\\[apropos-documentation] PATTERN   Show a list of functions, variables, and other items whose
-              documentation matches the PATTERN (a list of words or a regexp).
-\\[view-echo-area-messages]           Go to the *Messages* buffer which logs echo-area messages.
-\\[describe-function] FUNCTION  Display documentation for the given function.
-\\[Info-goto-emacs-command-node] COMMAND   Show the Emacs manual's section that describes the command.
-\\[describe-gnu-project]           Display information about the GNU project.
-\\[view-hello-file]           Display the HELLO file which illustrates various scripts.
-\\[info]           Start the Info documentation reader: read included manuals.
-\\[describe-input-method] METHOD    Describe a specific input method, or RET for current.
-\\[describe-key] KEYS      Display the full documentation for the key sequence.
-\\[Info-goto-emacs-key-command-node] KEYS      Show the Emacs manual's section for the command bound to KEYS.
-\\[view-lossage]           Show last 300 input keystrokes (lossage).
-\\[describe-language-environment] LANG-ENV  Describe a specific language environment, or RET for current.
-\\[describe-mode]           Display documentation of current minor modes and current major mode,
-             including their special commands.
-\\[view-emacs-news]           Display news of recent Emacs changes.
-\\[describe-symbol] SYMBOL    Display the given function or variable's documentation and value.
-\\[finder-by-keyword] TOPIC     Find packages matching a given topic keyword.
-\\[describe-package] PACKAGE   Describe the given Emacs Lisp package.
-\\[info-emacs-manual]           Display the Emacs manual in Info mode.
-\\[info-display-manual]           Prompt for a manual and then display it in Info mode.
-\\[describe-syntax]           Display contents of current syntax table, plus explanations.
-\\[info-lookup-symbol] SYMBOL    Show the section for the given symbol in the Info manual
-              for the programming language used in this buffer.
-\\[help-with-tutorial]           Start the Emacs learn-by-doing tutorial.
-\\[describe-variable] VARIABLE  Display the given variable's documentation and value.
-\\[where-is] COMMAND   Display which keystrokes invoke the given command (where-is).
-\\[display-local-help]           Display any available local help at point in the echo area.
-
-\\[about-emacs]         Information about Emacs.
-\\[describe-copying]         Emacs copying permission (GNU General Public License).
-\\[view-emacs-debugging]         Instructions for debugging GNU Emacs.
-\\[view-external-packages]         External packages and information about Emacs.
-\\[view-emacs-FAQ]         Emacs FAQ.
-C-m         How to order printed Emacs manuals.
-C-n         News of recent Emacs changes.
-\\[describe-distribution]         Emacs ordering and distribution information.
-\\[view-emacs-problems]         Info about known Emacs problems.
-\\[search-forward-help-for-help]         Search forward \"help window\".
-\\[view-emacs-todo]         Emacs TODO list.
-\\[describe-no-warranty]         Information on absence of warranty for GNU Emacs."
+  (concat
+   "\(Type "
+   (help--key-description-fontified "\s") ; SPC
+   " or "
+   (help--key-description-fontified "\d") ; DEL
+   " to scroll, or \\<help-map>\\[help-quit] to exit.)"
+   (help--for-help-make-sections
+    '(("Getting Help"
+       ("describe-mode" nil
+        "Help for current minor and major modes and their commands")
+       ("describe-bindings" nil "Show all key bindings")
+       ("describe-key" "KEYS" "Show help for key")
+       ("describe-key-briefly" "KEYS" "Show help for key briefly")
+       ("where-is" "COMMAND" "Show which key runs a given command")
+       ""
+       ("apropos-command" "PATTERN"
+        "Search for commands (see also \\[apropos])")
+       ("apropos-documentation" "PATTERN"
+        "Search documentation of functions, variables, and other items")
+       ("describe-function" "FUNCTION" "Show help for function")
+       ("describe-symbol" "SYMBOL" "Show help for function or variable")
+       ("describe-variable" "VARIABLE" "Show help for variable"))
+      ("Info Manuals"
+       ("info-emacs-manual" nil "Show Emacs manual")
+       ("Info-goto-emacs-command-node" "COMMAND"
+        "Show Emacs manual section for command")
+       ("Info-goto-emacs-key-command-node" "KEYS"
+        "Show Emacs manual section for command bound to key")
+       ("info" nil "Show all included manuals")
+       ("info-display-manual" "MANUAL" "Show given manual")
+       ("info-lookup-symbol" "SYMBOL"
+        "Find symbol in Info manual for current programming language"))
+      ("Misc Help"
+       ("finder-by-keyword" "TOPIC" "Search for packages matching topic")
+       ("describe-package" "PACKAGE" "Describe Emacs Lisp package")
+       ("view-echo-area-messages" nil "Show recent messages")
+       ("describe-gnu-project" nil "Show information about the GNU project")
+       ("view-lossage" nil "Show last 300 input keystrokes (lossage)")
+       ;; ("view-emacs-news" nil "Show recent Emacs changes") ; duplicate
+       ("describe-syntax" nil "Show current syntax table")
+       ("display-local-help" nil "Show local help at point")
+       ("help-with-tutorial" nil
+        "Start the Emacs tutorial"))
+      ("Help Files"
+       ("about-emacs" nil "About Emacs")
+       ("describe-copying" nil
+        "Emacs copying permission (GNU General Public License)")
+       ("view-emacs-debugging" nil "Debugging GNU Emacs")
+       ("view-external-packages" nil "External packages")
+       ("view-emacs-FAQ" nil "Emacs FAQ")
+       ("C-m" nil "Order printed Emacs manuals")
+       ("C-n" nil "News of recent Emacs changes")
+       ("describe-distribution" nil
+        "Emacs ordering and distribution information")
+       ("view-emacs-problems" nil "Known Emacs problems")
+       ("view-emacs-todo" nil "Emacs TODO")
+       ("describe-no-warranty" nil
+        "Information on absence of warranty for GNU Emacs"))
+      ("Language Help"
+       ("describe-coding-system" "CODING" "Describe coding system")
+       ("describe-input-method" "METHOD" "Describe input method")
+       ("describe-language-environment" "LANG-ENV" "Describe language environment")
+       ("view-hello-file" nil "Display the HELLO file illustrating various scripts")))))
   help-map)
 
 \f
-- 
2.30.1

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> https://i.imgur.com/Cv67yUN.png

There are no doubt other things to be said about this.

But for one thing, IMO:

It's not helpful to provide short descriptions
(OK) but no links to the help for each key (KO).
We have that help; we can link to it; but you
choose not to.  Why?

Coloring the keys, especially in a context
where they're well separated from the other
text, helps nothing.

It actually hurts - it can give the impression
there's something going on there - e.g., a link
or a button.  You even chose blue (like a link)
and a box (like a button).  If ever there was
gratuitous - even misleading - coloring, this
is it.

(I'm assuming those colored keys are not links.
If they are links, then they should appear like
other links in Emacs.)

It's not hard or tricky to put links on keys.
You prefer your action-less coloring.  A pity.
So be it.

Is this the way we are going to show keys in
*Help* from now on - boxed blue text?  I, for
one, hope not.  Even aside from the coloring
being gratuitous and misleading, it also makes
the keys more difficult to read.  A trifecta.

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 5365 bytes --]

> https://i.imgur.com/Cv67yUN.png

FWIW -

I'm in favor of having top-level summary help for a
feature - help that's organized into groups such as
what you've now proposed for `help-for-help' (aka
`C-h C-h').

I've long done that for some of my libraries, using
such organized Help as mode help (`C-h m').

And I've used such organization for `C-h C-h' at
least since 1999, with minor updates - see attached
screenshot.

I've also added links on key descriptions.  I think
they help a lot.  I'm not in favor of just coloring
keys as you've proposed, as I've said before - it's
better to link them to their full help, IMO.

Yes, one can do what the `C-h C-h' instructions say:
"type a help option...".

But you can also click key-description links to get
full help on a key.  IOW, the display is part of a
dialog, yes, but you can also use it like an ordinary
*Help* buffer.

Just what organization should be used is a separate
question.  What I wanted to say is: 

1. I agree that grouping helps.
2. I've long done that for `C-h C-h'.
3. I propose help links on keys (not just action-less
   colored text).

Here's a plain text version of what the screenshot shows:
_____

This is the Emacs ‘help-command’, accessible via ‘C-h’.
Type a help option (below) now, for help on a particular topic.
Use ‘SPC’ or ‘DEL’ to scroll this text.  Type ‘q’ to exit Help.
(A "command" is any function that you can execute via ‘M-x’.)

LEARNING EMACS
--------------
t:   Start a tutorial for learning Emacs.
C-f: Explain frequently asked Emacs questions.

COMMONLY USED
-------------
RET: Help about a key sequence or something you click with the mouse.
a:   Show commands that match a regular expression (regexp).
b:   Show current key bindings: keyboard, menu bar, and mouse.
c:   Show the doc for an Emacs command.
f:   Show the doc for an Emacs function.
F:   Open the Emacs manual for an Emacs command.
i:   Enter ‘Info’, to browse manuals, including Emacs and Emacs Lisp.
k:   Describes the command bound to keyboard/menu/mouse sequence.
K:   Open the Emacs manual for a keyboard/menu/mouse sequence.
m:   Describe the current major and minor modes.
o:   Show an Emacs user option’s value and documentation.
v:   Show an Emacs variable’s value and documentation.

MORE ADVANCED HELP
------------------
d:   Show Emacs functions and variables whose doc matches a regexp.
l:   Show what you just typed (last 100 keystrokes & mouse actions).
n:   Describe what’s new in this Emacs release.
p:   Find Emacs-Lisp libraries that match a topic.
s:   Describe the current syntax table.
S:   Find a symbol in the manual for the current buffer’s language.
u:   Find a topic in the Unix manual.
w:   Identify a keyboard/menu/mouse sequence that invokes a command.
C-a: Show Emacs functions and variables that match a regexp.
C-c: Identify the command bound to a keyboard/menu/mouse sequence.
C-l: Show the path name to an Emacs library.
C-o: Show value and doc for an Emacs user option of a given type.
M-o: Pop to Help buffer or back to the buffer that sent you to Help.
C-M-a: Show the tags matched by a given string.
g:   Show information about the GNU project.
C-w: Show information about the absence of a warranty.
M-c: Show the GNU Emacs General Public License.
M-x describe-distribution: Show Emacs ordering information.

INTERNATIONAL
-------------
C:   Describe a coding system.
h    Display the HELLO file, which illustrates scripts and languages.
I:   Describe an input method.
L:   Describe a language environment.
_____


> (Type SPC or DEL to scroll, or q to exit.)
> 
> Getting Help
> 
>    m	Help for current minor and major modes and their commands
>    b	Show all key bindings
>    k	Show help for key
>    c	Show help for key briefly
>    w	Show which key runs a given command
> 
>    a	Search for commands (see also M-x apropos)
>    d	Search documentation of functions, variables, and other items
>    f	Show help for function
>    o	Show help for function or variable
>    v	Show help for variable
> 
> Info Manuals
> 
>    r	Show Emacs manual
>    F	Show Emacs manual section for command
>    K	Show Emacs manual section for command bound to key
>    i	Show all included manuals
>    R	Show given manual
>    S	Find symbol in Info manual for current programming language
> 
> Misc Help
> 
>    p	Search for packages matching topic
>    P	Describe Emacs Lisp package
>    e	Show recent messages
>    g	Show information about the GNU project
>    l	Show last 300 input keystrokes (lossage)
>    s	Show current syntax table
>    .	Show local help at point
>    t	Start the Emacs tutorial
> 
> Help Files
> 
>    C-a	About Emacs
>    C-c	Emacs copying permission (GNU General Public License)
>    C-d	Debugging GNU Emacs
>    C-e	External packages
>    C-f	Emacs FAQ
>    C-m	Order printed Emacs manuals
>    C-n	News of recent Emacs changes
>    C-o	Emacs ordering and distribution information
>    C-p	Known Emacs problems
>    C-t	Emacs TODO
>    C-w	Information on absence of warranty for GNU Emacs
> 
> Language Help
> 
>    C	Describe coding system
>    I	Describe input method
>    L	Describe language environment
>    h	Display the HELLO file illustrating various scripts

[-- Attachment #2: throw-help-for-help.png --]
[-- Type: image/png, Size: 105549 bytes --]

RE: [External] : Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> I've also added links on key descriptions.  I think
> they help a lot.  I'm not in favor of just coloring
> keys as you've proposed, as I've said before - it's
> better to link them to their full help, IMO.

I have posted a patch to add such links.  Did you not see it?

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> > I've also added links on key descriptions.  I think
> > they help a lot.  I'm not in favor of just coloring
> > keys as you've proposed, as I've said before - it's
> > better to link them to their full help, IMO.
> 
> I have posted a patch to add such links.  Did you not see it?

No, I didn't check your patch.

It's not hard to put links on key descriptions.  I've
been doing that for a long time; I've suggested it for
Emacs more than once; and I pointed you to it recently.
It was a good idea many moon ago, and it still is.

What's unfortunate is to not adopt the appearance of
Emacs links.  You've provided various other appearances
for key-description links so far.  None of them (AFAIK)
are what links look like in Emacs generally (which is
also what links look like by default in most browsers
and so on).  Why is that?  No answer so far, AFAICT.

And if a user wants to change link appearance in
general that's easy to do: just customize face `link'.
Now, I suppose they'll need to customize more than one
face (?).
___

It's also unfortunate, IMO, to not handle sexps in
*Help* the same way we handle them in Lisp comments
and in *Info*: using `...'.

Occam, reuse, principle of least-surprise, etc., all
argue against multiplying appearances like that.  And
in Emacs that also means multiplying behaviors to
learn and keep track of.

When linked, `...' tells you not only that there's
a link, but that the thing quoted is code - a sexp.
When you drop that `...' envelope you stop conveying
that info.  Lossy, not helpful.

All in the name of what?  Supposed "nicer", "cleaner"
appearance, is all we've heard as a reason.

Much technical doc uses a fixed-pitch font for code
and variable-pitch for ordinary text.  Emacs has long
used `...' for code and not had to deal with both
fixed and variable pitch in the same doc/help.

That's not only a fine approach; it's versatile.  It
works with plain-text or fancy.  It's easy to
recognize, font-lock, search, and process by code.

Sometimes what exists already and has long been
practiced is better than what someone dreams up as
an improvement.

A good thing about free software is that anyone can
have new ideas and implement them - things that might
eventually prove, in practice, to be improvements.

What's not so good is when, instead of that happening
in 3rd-party code and being progressively taken up by
users, we get changes to Emacs itself because someone
considers her idea to be a general improvement.

Instead of trial and potential adoption over time, we
get changes in vanilla Emacs behavior or appearance.
That's too bad, IMHO.

At least, please make such changes optional and opt-in.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> If the general direction here is okay, I will provide a full proposal,
>> including thinking through the order.
>
> Please find attached an updated proposal.
>
> My overarching goal here has been to design this as an _overview_ of
> _important_ and _non-obvious_ information.
>
> This is a summary of the changes:
>
> - Added sections.
>
> - Drastically shortened descriptions of the command.
>
> - Changed ordering to be roughly based on: order of importance, logical
>   grouping of related items, and the Emacs manual.
>
> - Removed the indication about which commands will show a prompt.
>   [Rationale: I find that information overly pedantic, messy and fully
>   redundant; it will either be obvious from context or, at the very
>   least, when invoking a given help command.]
>
> I'm not sure what is considered a large attachment these days, so I
> posted a screenshot at some image host:
>
>     https://i.imgur.com/Cv67yUN.png
>
> To facilitate the discussion, I have also pasted below the plain text of
> the help buffer.  The patch is attached below.

There have been no further comments here within 4 weeks.

I intend to finish this up and push this to master in the next couple of
days.  Please send any further comments soon, or we will have to
consider them after this lands on master.  Thanks in advance.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Wed, 7 Apr 2021 10:18:23 -0500
> Cc: emacs-devel@gnu.org
> 
> I intend to finish this up and push this to master in the next couple of
> days.  Please send any further comments soon, or we will have to
> consider them after this lands on master.  Thanks in advance.

You mean, comments to the one and only patch you posted?  I have some:

> -                 (pop-to-buffer " *Metahelp*" nil t)
> +                 (pop-to-buffer " *Help Overview*" nil t)

The change in the buffer's name is gratuitous, so I'd prefer not doing
that.  Who knows what 3rd-party packages or user-local commands could
depend on that?

> +(defface help-for-help-binding-argument '((t :foreground "PaleGreen3"))
> +  "Face used for headers in the `help-for-help' buffer."
> +  :group 'help)

Is this a good face definition for all the supported terminals and
both the light and dark backgrounds?  IMO, it looks too pale on the
default light background in a GUI session, at least.  And green shade
is a strange color for this purpose anyway.

> +    '(("Getting Help"

I'd use something like "Describe and Find Commands, Keys, Functions".

> +      ("Info Manuals"

Just "Manuals" is better, IMO: newbies don't necessarily know what is
"Info".

> +       ("Info-goto-emacs-key-command-node" "KEYS"
> +        "Show Emacs manual section for command bound to key")
                                      ^^^^^^^^^^^^^^^^^^^^^^^^
"for a key sequence" is better, IMO.

> +       ("info" nil "Show all included manuals")

That's inaccurate.  "Show top-level menu of all installed manuals",
perhaps?

> +       ("info-display-manual" "MANUAL" "Show given manual")

"given"? by whom?  How about "Read a specific manual"?

> +       ("info-lookup-symbol" "SYMBOL"
> +        "Find symbol in Info manual for current programming language"))

"Show description of symbol in pertinent manual"

> +      ("Misc Help"

"Other Help commands"

> +      ("Help Files"

"Misc"

> +      ("Language Help"

"I18n Help"

Thanks.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> +       ("info-lookup-symbol" "SYMBOL"
>> +        "Find symbol in Info manual for current programming language"))
>
> "Show description of symbol in pertinent manual"

FWIW, the docstring of info-lookup-symbol uses the term
"relevant manual"

>> +      ("Language Help"
>
> "I18n Help"

The section heading of the help-for-help command should not
use an arcane abbreviation like "I18n".  I prefer "Language"
or if you must, "Internationalization".

-- 

Howard

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Wed, 07 Apr 2021 18:54:33 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> +       ("info-lookup-symbol" "SYMBOL"
> >> +        "Find symbol in Info manual for current programming language"))
> >
> > "Show description of symbol in pertinent manual"
> 
> FWIW, the docstring of info-lookup-symbol uses the term
> "relevant manual"

Yes, I considered that alternative.  But IMO "relevant" is a
problematic word.

> >> +      ("Language Help"
> >
> > "I18n Help"
> 
> The section heading of the help-for-help command should not
> use an arcane abbreviation like "I18n".  I prefer "Language"
> or if you must, "Internationalization".

I thought i18n is a widely known terminology, but if I'm mistaken,
then Internationalization is indeed the next best alternatives, IMO.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> > "Show description of symbol in pertinent manual"
>>
>> FWIW, the docstring of info-lookup-symbol uses the term
>> "relevant manual"
>
> Yes, I considered that alternative.  But IMO "relevant" is a
> problematic word.

I found an interesting discussion online suggesting that the only
difference is that "pertinent" is stronger than "relevant":

https://english.stackexchange.com/questions/211792/pertinent-versus-relevant-whats-the-usage-difference

I'm not sure it matters much which one we use.  I slightly prefer
"relevant" as it is the more common word (and therefore easier to
understand for non-native speakers of English), but I'm fine with
"pertinent" too.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 2505 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> I intend to finish this up and push this to master in the next couple of
>> days.  Please send any further comments soon, or we will have to
>> consider them after this lands on master.  Thanks in advance.
>
> You mean, comments to the one and only patch you posted?  I have some:

It was the second one I posted here, but yes.  You are replying to the
correct patch.

I'll need to look over the faces, but I did not do that yet.  I'll send
an updated patch in the next couple of days.

I have made the suggested changes in all cases where I don't comment
below:

>> +    '(("Getting Help"
>
> I'd use something like "Describe and Find Commands, Keys, Functions".

That's fine, but it is a bit long.  I suggest "Basic Help" here, which
contrasts nicely against the other headings.  (Please see the attached
screenshot.)

>> +       ("info" nil "Show all included manuals")
>
> That's inaccurate.  "Show top-level menu of all installed manuals",
> perhaps?

(Just to point out that the old text also said "included" but you are
correct that "installed" is more precise.)

Do we need to speak of "top-level menu", or can we get away with the
shorter "Show all installed manuals"?

Also, Howard Melman pointed out that "Info" is actually the mnemonic for
"i" here so perhaps we should actually speak of info here (even though
we don't do it in the headline)?  IOW, how about "Show all installed
Info manuals"?

(BTW, I think we should generally avoid using the "menu" terminology to
mean something other than top menus (i.e. `menu-bar-mode').  I know we
do it in many places in Emacs, but I find it unfortunate and confusing.)

>> +      ("Misc Help"
>
> "Other Help commands"
>
>> +      ("Help Files"
>
> "Misc"
>
>> +      ("Language Help"
>
> "I18n Help"

I'm basically fine with all that, but just to point out that we have in
the Info manual these sections:

* Language Help::       Help relating to international language support.
* Misc Help::           Other help commands.
* Help Files::          Commands to display auxiliary help files.

I am also not sure that "I18n" is clear to all our users, in particular
non-programmers.  It is clear from context of course, but some users
might find the abbreviation cryptic.  Perhaps "Internationalization" is
better, if a bit long.

> Thanks.

Thanks a lot for your detailed comments.  As I said in my reply to
Howard, please bare with me as I try to take all comments into account
and work out a coherent whole.

[-- Attachment #2: help-for-help2.png --]
[-- Type: image/png, Size: 151226 bytes --]

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 8 Apr 2021 08:35:06 -0500
> Cc: emacs-devel@gnu.org
> 
> >> +    '(("Getting Help"
> >
> > I'd use something like "Describe and Find Commands, Keys, Functions".
> 
> That's fine, but it is a bit long.

Why is it a problem to be long?

> I suggest "Basic Help" here, which contrasts nicely against the
> other headings.  (Please see the attached screenshot.)

Both "getting Help" and "Basic Help" is too general to be useful, IMO.

> >> +       ("info" nil "Show all included manuals")
> >
> > That's inaccurate.  "Show top-level menu of all installed manuals",
> > perhaps?
> 
> (Just to point out that the old text also said "included" but you are
> correct that "installed" is more precise.)
> 
> Do we need to speak of "top-level menu", or can we get away with the
> shorter "Show all installed manuals"?

But "show a manual" could be interpreted as displaying the contents of
that manual, in which case "show all manuals" makes no sense.  What
that "shows" is a menu, not the manuals.  If you want, you could use
"show the list of manuals", but I felt that "menu" is more accurate,
as it hints that the user could select one of those manuals from that
menu.

> Also, Howard Melman pointed out that "Info" is actually the mnemonic for
> "i" here so perhaps we should actually speak of info here (even though
> we don't do it in the headline)?  IOW, how about "Show all installed
> Info manuals"?

I think I explained elsewhere why I think using "Info" in that screen
is not the best idea: newbies won't know what that means.

> (BTW, I think we should generally avoid using the "menu" terminology to
> mean something other than top menus (i.e. `menu-bar-mode').  I know we
> do it in many places in Emacs, but I find it unfortunate and confusing.)

But it _is_ a menu, albeit not a drop-down menu.  It says "Menu" right
there at the beginning, and explains how to select a manual from the
menu.  So the user who selects that command will see immediately that
a menu is indeed displayed.

> >> +      ("Misc Help"
> >
> > "Other Help commands"
> >
> >> +      ("Help Files"
> >
> > "Misc"
> >
> >> +      ("Language Help"
> >
> > "I18n Help"
> 
> I'm basically fine with all that, but just to point out that we have in
> the Info manual these sections:
> 
> * Language Help::       Help relating to international language support.
> * Misc Help::           Other help commands.
> * Help Files::          Commands to display auxiliary help files.

Node names (as opposed to names of the corresponding sections) are not
a recommended source of good names: they are selected for brevity, and
thus frequently sacrifice accuracy and expressive power.  The
section's name in the first case is more reasonable: "Help for
International Language Support".  (Although "international language"
sounds awkward to me.)

> I am also not sure that "I18n" is clear to all our users, in particular
> non-programmers.  It is clear from context of course, but some users
> might find the abbreviation cryptic.  Perhaps "Internationalization" is
> better, if a bit long.

"Internationalization" is fine.

Thanks.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> >> +    '(("Getting Help"
>> >
>> > I'd use something like "Describe and Find Commands, Keys, Functions".
>>
>> That's fine, but it is a bit long.
>
> Why is it a problem to be long?

Keeping it short is in line with common recommendations in UIX design,
which strongly favours simplicity, in order not to burden the mental
bandwidth of users with irrelevant detail.

Having a long headline here weighs the entire screen down, makes it
harder to read and more intimidating.

> Both "getting Help" and "Basic Help" is too general to be useful, IMO.

Things will be clear from context.  No one risks being confused by
"Basic Help" or "Getting Help".

The main purpose is to give a quick overview of the most commonly used
commands.  "Most Commonly Used Help Commands" is more accurate but too
pedantic.

>> Do we need to speak of "top-level menu", or can we get away with the
>> shorter "Show all installed manuals"?
>
> But "show a manual" could be interpreted as displaying the contents of
> that manual, in which case "show all manuals" makes no sense.

I don't see how anyone could take "show all manuals" as meaning anything
other than some kind of _list_ of manuals.  How else would they be
shown?

And if a user runs the command they will immediately see that they can
indeed also select a manual.  So I think the risk of confusion here is
low.

That said, this is not something I feel is very important.  We can go
with your preference if you feel strongly about it.

> I think I explained elsewhere why I think using "Info" in that screen
> is not the best idea: newbies won't know what that means.

You did explain it, yes, but in a different context.  The argument is
different here as there is a mnemonic involved.  The other drawback I
see is that we miss an opportunity to educate our users in the existence
of Info.

That said, I'm fine with leaving it out, as long as we are conscious of
the considerations involved.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 8 Apr 2021 08:27:02 -0700
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> >> +    '(("Getting Help"
> >> >
> >> > I'd use something like "Describe and Find Commands, Keys, Functions".
> >>
> >> That's fine, but it is a bit long.
> >
> > Why is it a problem to be long?
> 
> Keeping it short is in line with common recommendations in UIX design,
> which strongly favours simplicity, in order not to burden the mental
> bandwidth of users with irrelevant detail.

We are talking about short but inaccurate vs longer but more
accurate.  I agree that, all the rest being equal, the shorter the
better, but that's not our case here.

> Having a long headline here weighs the entire screen down, makes it
> harder to read and more intimidating.

I think you exaggerate here a bit.

> > Both "getting Help" and "Basic Help" is too general to be useful, IMO.
> 
> Things will be clear from context.  No one risks being confused by
> "Basic Help" or "Getting Help".

If they will be clear from context, then they are redundant, IMO.

> The main purpose is to give a quick overview of the most commonly used
> commands.

Exactly.  And too-general headings aren't useful for the overview,
because they require one to read what's under them to understand.

> >> Do we need to speak of "top-level menu", or can we get away with the
> >> shorter "Show all installed manuals"?
> >
> > But "show a manual" could be interpreted as displaying the contents of
> > that manual, in which case "show all manuals" makes no sense.
> 
> I don't see how anyone could take "show all manuals" as meaning anything
> other than some kind of _list_ of manuals.

Well, I did.

> How else would they be shown?

"They" being the manuals?  The top-level Info menu doesn't show any
manuals, it only shows their names.

> That said, this is not something I feel is very important.  We can go
> with your preference if you feel strongly about it.

I don't feel strong about it.  You asked for a review, and I provided
one.

Thanks.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> >> Do we need to speak of "top-level menu", or can we get away with the
>> >> shorter "Show all installed manuals"?
>> >
>> > But "show a manual" could be interpreted as displaying the contents of
>> > that manual, in which case "show all manuals" makes no sense.
>> 
>> I don't see how anyone could take "show all manuals" as meaning anything
>> other than some kind of _list_ of manuals.
>
> Well, I did.
>
>> How else would they be shown?
>
> "They" being the manuals?  The top-level Info menu doesn't show any
> manuals, it only shows their names.
>
>> That said, this is not something I feel is very important.  We can go
>> with your preference if you feel strongly about it.
>
> I don't feel strong about it.  You asked for a review, and I provided
> one.

FWIW I don't think the current description is accurate. At
least for me in Emacs 27, C-h i is bound to the command
info.

If there is no *info* buffer it opens info showing what it
calls the Info Directory which (again in info terminology,
for better or worse) is "a menu which leads to all the nodes
that exist" and which "lists all the manuals and other Info
documents that are, or could be, installed on your system".

But if there is a buffer showing an info node, C-h i will
take you to that buffer and not to the list of all manuals.
And I don't believe the command even takes any kind of
argument to take you to the info directory if a node is
open.  (I use d after C-h i if that's what I want.)

I think these are more accurate options:

i	Open Info (read all manuals)
i	Show Info documentation (read all manuals)
i	Show Info documentation (read installed manuals)
i	Show Info documentation browser (read all manuals)

I'm not sure which of these I prefer but I think they're all
better than what you currently have.  They include the
mnemonic "info", accurately describe what the command does
in all circumstances, and are understandable in plain
language for the newbie.

-- 

Howard

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> We are talking about short but inaccurate vs longer but more
> accurate.  I agree that, all the rest being equal, the shorter the
> better, but that's not our case here.

I might have found a compromise that could work:

    "Commands, Keys and Functions"

It is basically the same as "Describe and Find Commands, Keys,
Functions", only shorter.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 8 Apr 2021 15:52:51 -0700
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > We are talking about short but inaccurate vs longer but more
> > accurate.  I agree that, all the rest being equal, the shorter the
> > better, but that's not our case here.
> 
> I might have found a compromise that could work:
> 
>     "Commands, Keys and Functions"

Fine with me, thanks.

Re: Proposal for an improved `help-for-help'

[Alan Mackenzie]

Hello, Emacs.

On Thu, Apr 08, 2021 at 08:35:06 -0500, Stefan Kangas wrote:
> Eli Zaretskii <eliz@gnu.org> writes:

[ .... ]

> * Language Help::       Help relating to international language support.

This has kind of grated with me for some while.  It feels like
"international" is being used as a euphemism for "foreign".  If we
really mean "foreign" that is what we should write.

Some of the languages we support are NOT international, but pertain to
just one nation.

As a suggestion, how about writing "non-English" in place of
"international".  That is surely what is meant.  After all English _is_
an international language, along with Spanish, French, .....

[ .... ]

> > Thanks.

> Thanks a lot for your detailed comments.  As I said in my reply to
> Howard, please bare with me as I try to take all comments into account
> and work out a coherent whole.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 08.04.2021 17:08, Alan Mackenzie wrote:
> It feels like
> "international" is being used as a euphemism for "foreign".  If we
> really mean "foreign" that is what we should write.

"foreign" implies a specific point of reference.

What's foreign to you may not be foreign to me, or some other user.

Re: Proposal for an improved `help-for-help'

[Alan Mackenzie]

Hello, Dmitry.

On Thu, Apr 08, 2021 at 17:50:45 +0300, Dmitry Gutov wrote:
> On 08.04.2021 17:08, Alan Mackenzie wrote:
> > It feels like
> > "international" is being used as a euphemism for "foreign".  If we
> > really mean "foreign" that is what we should write.

> "foreign" implies a specific point of reference.

So does "international", used as it is here.

> What's foreign to you may not be foreign to me, or some other user.

That's precisely my point.  Writing "international" when "foreign" is
meant, as it seems to be in this context, does not make it better.  I
think it makes it worse - as well as the "preferred" specific point of
reference, we also have the euphemism.

My suggested replacement was "non-English", which is precisely what is
meant.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Thu, 8 Apr 2021 15:02:47 +0000
> Cc: Stefan Kangas <stefan@marxist.se>, Eli Zaretskii <eliz@gnu.org>,
>   emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > "foreign" implies a specific point of reference.
> 
> So does "international", used as it is here.

Really?  I though i18n, l10n, and the like are established terminology
nowadays.  For example:

  https://docs.microsoft.com/en-us/windows/win32/intl/international-support

There's also "multilingual" and m17n, but I thought it was less known.
However, maybe we should consider something like "Multilingual Help"?

Re: Proposal for an improved `help-for-help'

[Alan Mackenzie]

On Thu, Apr 08, 2021 at 18:15:13 +0300, Eli Zaretskii wrote:
> > Date: Thu, 8 Apr 2021 15:02:47 +0000
> > Cc: Stefan Kangas <stefan@marxist.se>, Eli Zaretskii <eliz@gnu.org>,
> >   emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > "foreign" implies a specific point of reference.

> > So does "international", used as it is here.

International means "between nations", as in an "international
conference", an "internation railway line", .....  It does not mean
"foreign" or "Non-USA".

> Really?  I though i18n, l10n, and the like are established terminology
> nowadays.

Yes, they are correct usage.  "Internationalisation" means "make
something usable in lots of nations".

For example:

>   https://docs.microsoft.com/en-us/windows/win32/intl/international-support

That usage means "foreign", i.e. "non-USA".  It is not intended to
support people who work in two or more nations, for example.

Surely we can do better than Microsoft, here.

> There's also "multilingual" and m17n, but I thought it was less known.
> However, maybe we should consider something like "Multilingual Help"?

Why?  Nobody wants "multilingual help" - at least not usually.  We each
seek help in, if possible, our own language.  We're not talking about
helping people who speak several languages, or for translation services,
we're talking about help in languages which aren't English.  Why can't
we just say that?

We can't hide for long that the single "native" language in Emacs is
(American) English.  Why should we try?  What's wrong with
"Non-English"?  It says exactly what's meant, and surely is unlikely to
cause offence.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Thu, 8 Apr 2021 15:45:51 +0000
> Cc: dgutov@yandex.ru, stefan@marxist.se, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > Really?  I though i18n, l10n, and the like are established terminology
> > nowadays.
> 
> Yes, they are correct usage.  "Internationalisation" means "make
> something usable in lots of nations".

So where's the problem with using it in this case?

> For example:
> 
> >   https://docs.microsoft.com/en-us/windows/win32/intl/international-support
> 
> That usage means "foreign", i.e. "non-USA".  It is not intended to
> support people who work in two or more nations, for example.
> 
> Surely we can do better than Microsoft, here.

Reality check: MS-Windows had i18n features and Unicode support long
before any other OS did.

> > There's also "multilingual" and m17n, but I thought it was less known.
> > However, maybe we should consider something like "Multilingual Help"?
> 
> Why?  Nobody wants "multilingual help" - at least not usually.  We each
> seek help in, if possible, our own language.

That's too close to casuistics for my palate, sorry.  So  I will bow
out of this part of the thread.  I still stand by my recommendations.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

FYI, other than the text of C-h i I talked about in another
message I like this iteration of this.  Two small comments:

Now that Other Help Commands has two "groupings" if you'd
like to prioritize packages as you said, you could put the
tutorial line at the top of the second grouping and
prioritize both.

C-h g seems to me like it belongs better in the Misc section
(in the 3rd grouping).  It would be the only non-control key
there (presumably because C-g isn't available) but it seems
the better logical positioning for what it does (and it does
make it stand out a little bit).

Actually, here's another option for the grouping the Misc
section.  Use the same ordering as found in the about screen
(I'm not sure if this changed in Emacs 28 from 27).  Also,
you can put the C-e binding with the other package
commands.  So I think something like this works pretty well:

C-f	Emacs FAQ
C-n	News of recent changes
C-p	Known problems
C-d	Debugging Emacs
C-t	Emacs TODO

C-a	About Emacs
g	Show information about the GNU project
C-w	Information on absence of warranty
C-c	Emacs copy permission (GNU General Public License)
C-o	Emacs ordering and distribution information
C-m	Order printed manuals

-- 

Howard

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

> Actually, here's another option for the grouping the Misc
> section.  Use the same ordering as found in the about screen
> (I'm not sure if this changed in Emacs 28 from 27).  Also,
> you can put the C-e binding with the other package
> commands.  So I think something like this works pretty well:

Thanks, I've now adjusted it along the lines you suggest with some minor
adjustments.

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

Some more comments on your last screenshot:

A nitpick: I would add a comma after "to search" on the first line.

About the "language" section, on a second thought I'm not quite sure 
anymore that "language" is the most appropriate word here.  It is about 
character sets and how encoding and decoding happens: how Emacs encodes 
and decodes text files, and how users can use various coding systems to 
input characters that are not present on their keyboard (mathematical 
symbols, phonetic alphabet, foreign language characters, ...).  So I would 
suggest something like "Help about Character Codings".  Sure, that sounds 
very technical, but these help commands are indeed very technical.

I would put "Describe input method" as the first entry there, it's the one 
users will most likely want/need to use.

And I would perhaps move the "Show current syntax table" in that section, 
above the "Display the HELLO file".

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Gregory Heytings <gregory@heytings.org> writes:

> Some more comments on your last screenshot:
>
> A nitpick: I would add a comma after "to search" on the first line.

Fixed.

> I would put "Describe input method" as the first entry there, it's the one
> users will most likely want/need to use.

OK, I'll take your word for it.

(I never use this stuff so I'm particularly happy for this feedback.)

> And I would perhaps move the "Show current syntax table" in that section,
> above the "Display the HELLO file".

Hmm, but that has nothing to do with i18n, does it?

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>> I would put "Describe input method" as the first entry there, it's the 
>> one users will most likely want/need to use.
>
> OK, I'll take your word for it.
>
> (I never use this stuff so I'm particularly happy for this feedback.)
>

I'd suggest you try it, it's a very nice feature of Emacs.  C-x C-m C-\, 
select TeX (for example), and type \alpha, \beta, \gamma.

>> And I would perhaps move the "Show current syntax table" in that 
>> section, above the "Display the HELLO file".
>
> Hmm, but that has nothing to do with i18n, does it?
>

It's not strictly speaking a help command about character codings indeed, 
but it's about how Emacs handles characters, so it's much closer to 
character codings than to the help commands in the "other help commands" 
section.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Gregory Heytings <gregory@heytings.org> writes:

>>> And I would perhaps move the "Show current syntax table" in that
>>> section, above the "Display the HELLO file".
>>
>> Hmm, but that has nothing to do with i18n, does it?
>>
>
> It's not strictly speaking a help command about character codings
> indeed, but it's about how Emacs handles characters, so it's much
> closer to character codings than to the help commands in the "other
> help commands" section.

I agree.

-- 

Howard

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> There have been no further comments here within 4 weeks.
> 
> I intend to finish this up and push this to master in the next couple of
> days.  Please send any further comments soon, or we will have to
> consider them after this lands on master.

I sent quite a few comments.  Why ask for further
comments and intend to just push otherwise, if you
haven't taken previous comments into consideration,
which seems to have been the case?

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>
> There have been no further comments here within 4 weeks.
>
> I intend to finish this up and push this to master in the next couple of 
> days.  Please send any further comments soon, or we will have to 
> consider them after this lands on master.  Thanks in advance.
>

A few comments:

Your patch breaks search-forward-help-for-help, in which the " *Metahelp*" 
buffer name is hardcoded.

I would add "C-s to search, " after "to scroll,".

I find the last section name "Language Help" unclear.

I would add "(see also M-x list-packages)" after "External packages".

Why did you put a blank line between where-is and apropos-command?

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>> There have been no further comments here within 4 weeks.
>> 
>> I intend to finish this up and push this to master in the next couple 
>> of days.  Please send any further comments soon, or we will have to 
>> consider them after this lands on master.  Thanks in advance.
>
> A few comments:
>
> Your patch breaks search-forward-help-for-help, in which the " 
> *Metahelp*" buffer name is hardcoded.
>
> I would add "C-s to search, " after "to scroll,".
>
> I find the last section name "Language Help" unclear.
>
> I would add "(see also M-x list-packages)" after "External packages".
>
> Why did you put a blank line between where-is and apropos-command?
>

Another small comment: your patch adds two warnings to the build process:

In help--for-help-make-commands:
help.el:206:27: Warning: Unused lexical variable `arg'
In help--for-help-make-sections:
help.el:225:13: Warning: Unused lexical variable `title'

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Gregory Heytings <gregory@heytings.org> writes:

> A few comments:

Thanks for your detailed response.

> Your patch breaks search-forward-help-for-help, in which the " *Metahelp*"
> buffer name is hardcoded.

Yes, I have reverted that part (Eli commented the same thing).

> I would add "C-s to search, " after "to scroll,".

IMO that command is less useful now that this screen is not a wall of
text, so I'd rather avoid that verbosity.

> I find the last section name "Language Help" unclear.

This is the same name as the section `(emacs) Language Help'.

FWIW, I personally find it's clear from context, but if you have an
equally short alternative, I'm all ears.  (And perhaps we should then
also update the Info manual accordingly.)

> I would add "(see also M-x list-packages)" after "External packages".

This is a good idea, I think.

> Why did you put a blank line between where-is and apropos-command?

The intention is to divide this into two subgroups.

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>> I would add "C-s to search, " after "to scroll,".
>
> IMO that command is less useful now that this screen is not a wall of 
> text, so I'd rather avoid that verbosity.
>

The text, even with sections and a nicer formatting, is still rather long, 
and IMO isearch is very useful there.  I remember that I found the fact 
that there was no way to search that buffer rather frustrating when I 
started using Emacs, it just kept disappearing no matter what I did.

Moreover with just "(Type SPC ... or q to exit.)" it looks like these are 
the only options, where in fact a fourth key (and AFAIK only a fourth key) 
is defined.

>> I find the last section name "Language Help" unclear.
>
> This is the same name as the section `(emacs) Language Help'.
>
> FWIW, I personally find it's clear from context, but if you have an 
> equally short alternative, I'm all ears.  (And perhaps we should then 
> also update the Info manual accordingly.)
>

Equally short will be difficult ;-)  The section title of the Emacs manual 
is "Help for International Language Support", I would suggest 
"International Languages Help" or "Help for International Languages".

>> Why did you put a blank line between where-is and apropos-command?
>
> The intention is to divide this into two subgroups.
>

Okay, then I suggest dividing other sections into subgroups, to make the 
blocks less intimidating:

pPel / tgs.

C-a C-e C-f C-n / C-d C-m C-p C-t / C-c C-o C-w

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Gregory Heytings <gregory@heytings.org> writes:

> The text, even with sections and a nicer formatting, is still rather long,
> and IMO isearch is very useful there.  I remember that I found the fact
> that there was no way to search that buffer rather frustrating when I
> started using Emacs, it just kept disappearing no matter what I did.

The problem is arguably that this help screen is modal, but I tried and
"C-s" actually doesn't weigh this down too much.  So I've added it now.

> Equally short will be difficult ;-)  The section title of the Emacs manual
> is "Help for International Language Support", I would suggest
> "International Languages Help" or "Help for International Languages".

OK, I'll take this into account, thanks.  See also Eli's reply.

>>> Why did you put a blank line between where-is and apropos-command?
>>
>> The intention is to divide this into two subgroups.
>>
>
> Okay, then I suggest dividing other sections into subgroups, to make the
> blocks less intimidating:
>
> pPel / tgs.

Good idea, I went here with: "tpPg / els."

> C-a C-e C-f C-n / C-d C-m C-p C-t / C-c C-o C-w

Yes, that's better.

Re: Proposal for an improved `help-for-help'

[Juri Linkov]

>> I'm not sure what is considered a large attachment these days, so I
>> posted a screenshot at some image host:
>>
>>     https://i.imgur.com/Cv67yUN.png
>
> There have been no further comments here within 4 weeks.

With this the keys in the Help buffer have the same style as on Wikipedia,
for example: https://en.wikipedia.org/wiki/Control_key#Table_of_examples

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> Stefan Kangas <stefan@marxist.se> writes:
>>
>>> If the general direction here is okay, I will provide a full proposal,
>>> including thinking through the order.
>>
>> Please find attached an updated proposal.
>>
>> My overarching goal here has been to design this as an _overview_ of
>> _important_ and _non-obvious_ information.
>>
>> This is a summary of the changes:
>>
>> - Added sections.
>>
>> - Drastically shortened descriptions of the command.
>>
>> - Changed ordering to be roughly based on: order of importance, logical
>>   grouping of related items, and the Emacs manual.
>>
>> - Removed the indication about which commands will show a prompt.
>>   [Rationale: I find that information overly pedantic, messy and fully
>>   redundant; it will either be obvious from context or, at the very
>>   least, when invoking a given help command.]
>>
>> I'm not sure what is considered a large attachment these days, so I
>> posted a screenshot at some image host:
>>
>>     https://i.imgur.com/Cv67yUN.png
>>
>> To facilitate the discussion, I have also pasted below the plain text of
>> the help buffer.  The patch is attached below.
>
> There have been no further comments here within 4 weeks.
>
> I intend to finish this up and push this to master in the next couple of
> days.  Please send any further comments soon, or we will have to
> consider them after this lands on master.  Thanks in advance.

That was 2 weeks ago.  Based on the feedback I received at the time, I
have now pushed my final version of this patch to master.

There is of course still time for further tweaks before Emacs 28.
I invite anyone to report bugs in case they can see any opportunities
for improving this.  (Feel free to CC me if you do as I'm currently not
subscribed to the bug list.)

Thank you to everyone who contributed to the discussion!

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 24 Apr 2021 08:21:49 -0500
> Cc: emacs-devel@gnu.org
> 
> That was 2 weeks ago.  Based on the feedback I received at the time, I
> have now pushed my final version of this patch to master.

That triggers a byte-compilation warning here:

  In help--for-help-make-sections:
  help.el:221:13: Warning: Unused lexical variable `title'

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 24.04.2021 16:21, Stefan Kangas wrote:

> That was 2 weeks ago.  Based on the feedback I received at the time, I
> have now pushed my final version of this patch to master.
> 
> There is of course still time for further tweaks before Emacs 28.
> I invite anyone to report bugs in case they can see any opportunities
> for improving this.  (Feel free to CC me if you do as I'm currently not
> subscribed to the bug list.)

Just checked it out. It's a significant improvement, thank you.

Two notes:

- I have 'C-h C-a' rebound to 'apropos' instead of 'apropos-command' 
locally. As a result, help-for-help shows 'M-x apropos-commnad' in the 
first column and (see also 'a') later.

The regression is that the previous version printed

   M-x apropos-command PATTERN

followed by 3 spaces, whereas the new one prints
   M-x apropos-commandTABSearch for commands (see also a)

and for some reason TAB is printed with zero width.

It's a minor thing, to be honest.

- Not a regression, old problem:

Instructions say "Type ..., or SPC or DEL to scroll".

But DEL here is actually <backspace>. If I just press Delete on the 
keyboard, help-for-help exits instead of scrolling.

And the target audience of help-for-help is probably at least as 
ignorant as myself about the difference between DEL and Delete.

Perhaps the easiest fix would be to handle Delete same as Backspace here.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 24.04.2021 16:21, Stefan Kangas wrote:
>
>> That was 2 weeks ago.  Based on the feedback I received at the time, I
>> have now pushed my final version of this patch to master.
>>
>> There is of course still time for further tweaks before Emacs 28.
>> I invite anyone to report bugs in case they can see any opportunities
>> for improving this.  (Feel free to CC me if you do as I'm currently not
>> subscribed to the bug list.)
>
> Just checked it out. It's a significant improvement, thank you.
>
> Two notes:
>
> - I have 'C-h C-a' rebound to 'apropos' instead of 'apropos-command'
> locally. As a result, help-for-help shows 'M-x apropos-commnad' in the
> first column and (see also 'a') later.
>
> The regression is that the previous version printed
>
>    M-x apropos-command PATTERN
>
> followed by 3 spaces, whereas the new one prints
>    M-x apropos-commandTABSearch for commands (see also a)
>
> and for some reason TAB is printed with zero width.
>
> It's a minor thing, to be honest.

I can reproduce that here.

The easiest way of fixing it is to change the separator to "\s\t"
instead of just "\t".  It would be slightly less clean I guess, but
since the screen is modal I suppose most people will never notice the
difference.  WDYT?

> - Not a regression, old problem:
>
> Instructions say "Type ..., or SPC or DEL to scroll".
>
> But DEL here is actually <backspace>. If I just press Delete on the
> keyboard, help-for-help exits instead of scrolling.
>
> And the target audience of help-for-help is probably at least as
> ignorant as myself about the difference between DEL and Delete.

As you say, this is an old problem.  For example `C-h k <backspace>'
here gives a help screen that cryptically says "DEL (translated from
<backspace>)".  I suppose most users have no idea what that means, other
than some vague notion that "DEL is clearly just the same as backspace".

I would prefer that <backspace> would just be printed as such,
everywhere.  I'm guessing there are historical reasons for why this
isn't already the case.  It would be great if we could fix this.

> Perhaps the easiest fix would be to handle Delete same as Backspace here.

Yes, that could alleviate the problem in this particular case.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 24 Apr 2021 18:48:00 -0500
> Cc: emacs-devel@gnu.org
> 
> > And the target audience of help-for-help is probably at least as
> > ignorant as myself about the difference between DEL and Delete.
> 
> As you say, this is an old problem.  For example `C-h k <backspace>'
> here gives a help screen that cryptically says "DEL (translated from
> <backspace>)".  I suppose most users have no idea what that means, other
> than some vague notion that "DEL is clearly just the same as backspace".

I don't see any good way around this.  This is basic Emacs
terminology, for which we did everything we could to document and
clearly explain what we mean.  Users should master this terminology as
soon as they can, exactly as they need to know what is a "window", a
"buffer", and "yank".  The tutorial introduces this terminology,
including the relation to <Backspace>, for this very reason.

> I would prefer that <backspace> would just be printed as such,
> everywhere.

You can't, because not every keyboard has that key.  And because users
still can confuse that with the BS (a.k.a. "C-h") key.  And because we
have normal-erase-is-backspace-mode.

> > Perhaps the easiest fix would be to handle Delete same as Backspace here.
> 
> Yes, that could alleviate the problem in this particular case.

Please don't, that would be a horribly wrong change.  Like making C-f
move backwards.

(Sometimes I wish there were some things in Emacs that would be
considered immutable, to the degree that even talking about changing
them is unimaginable.  Unrealistic, I know, but one can hope.)

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> I don't see any good way around this.  This is basic Emacs
> terminology, for which we did everything we could to document and
> clearly explain what we mean.

The way I see around it is to change that terminology.

>> I would prefer that <backspace> would just be printed as such,
>> everywhere.
>
> You can't, because not every keyboard has that key.  And because users
> still can confuse that with the BS (a.k.a. "C-h") key.

I note that any keyboard I have ever seen or used has had a backspace
key.  It is of course not interesting to me what exact control codes
that key has been sending on various machines over the years.  When
pressed, it has erased text backwards.

Most other software seems to handle such keys gracefully and
transparently.  Why can't we?

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 25 Apr 2021 04:30:04 -0500
> Cc: dgutov@yandex.ru, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I don't see any good way around this.  This is basic Emacs
> > terminology, for which we did everything we could to document and
> > clearly explain what we mean.
> 
> The way I see around it is to change that terminology.

So that everyone who used Emacs until now will have to re-learn?

When I see DEL mentioned in the Emacs documentation, I immediately
know what key that alludes to.  How would you propose to change the
documentation while letting veteran users still understand it quickly
and unequivocally?

> > You can't, because not every keyboard has that key.  And because users
> > still can confuse that with the BS (a.k.a. "C-h") key.
> 
> I note that any keyboard I have ever seen or used has had a backspace
> key.  It is of course not interesting to me what exact control codes
> that key has been sending on various machines over the years.  When
> pressed, it has erased text backwards.

But it doesn't always erase backward, it sometimes _moves_ backward.

Besides, what exactly is your proposal?  Backspace vs DEL is not the
only such issue: we have RET vs Enter (how many keyboards did you see
with a key labeled "RET"?).  And on my keyboard (and most probably on
yours as well) I have a key labeled "Delete" and another one labeled
"Del" -- how do we make sure users will not be confused by that?
There's also Tab the function key vs TAB the ASCII control character
-- are we going to make that distinction explicit as well?

This deceptively "simple" issue is full of difficulties and underwater
rocks.  At the time, it took several non-trivial iterations to get the
text in the manual about that as clear and descriptive as it is.  If
you are serious with your suggestion, please propose how to treat this
complex issue in its entirety; it isn't enough to say let's replace
DEL with Backspace.

> Most other software seems to handle such keys gracefully and
> transparently.  Why can't we?

I think we already do.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I note that any keyboard I have ever seen or used has had a backspace
>> key.  It is of course not interesting to me what exact control codes
>> that key has been sending on various machines over the years.  When
>> pressed, it has erased text backwards.
>
> But it doesn't always erase backward, it sometimes _moves_ backward.

I don't understand what you mean here.  Perhaps we use different
terminology.  What I mean is that if point is on X in "fooX", I press
backspace and end up with "foX".  This is true for any machine I have
used, and I suspect that is the case for most people.

> Besides, what exactly is your proposal?  Backspace vs DEL is not the
> only such issue: we have RET vs Enter (how many keyboards did you see
> with a key labeled "RET"?).  And on my keyboard (and most probably on
> yours as well) I have a key labeled "Delete" and another one labeled
> "Del" -- how do we make sure users will not be confused by that?
> There's also Tab the function key vs TAB the ASCII control character
> -- are we going to make that distinction explicit as well?

Please forgive for speaking frankly, but I think this is all a bit of a
mess.  Other software I use don't have any problem with any of this:
backspace is backspace, delete is delete, return is return, etc.

I do appreciate that there are historical reasons, the question of
different keyboards, terminals, features that no one else has, and what
have you.  But to me, as an end-user, it looks like a very complicated
tapestry for a couple of keys that no one else seems to be struggling
with.

And in this case it boils down to the unfortunate situation that
"backspace" is described as "DEL" in our documentation.

(With regards to a numerical "DEL" key, it's been a while since I had a
key like that.  But I guess my very informally expressed expectation is
that it should do the same thing in Emacs as it does in e.g. Firefox.)

> This deceptively "simple" issue is full of difficulties and underwater
> rocks.  At the time, it took several non-trivial iterations to get the
> text in the manual about that as clear and descriptive as it is.  If
> you are serious with your suggestion, please propose how to treat this
> complex issue in its entirety; it isn't enough to say let's replace
> DEL with Backspace.

I appreciate the hard work that went into this, of course.  I'll put
looking into this properly on my list of things to work on.  I am
currently already spread too thin with my many Emacs ideas, so I can't
promise to look into this any time soon, unfortunately.

(I'm also not so sure I am not already in over my head here.  :-))

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 25 Apr 2021 06:49:46 -0500
> Cc: dgutov@yandex.ru, emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> I note that any keyboard I have ever seen or used has had a backspace
> >> key.  It is of course not interesting to me what exact control codes
> >> that key has been sending on various machines over the years.  When
> >> pressed, it has erased text backwards.
> >
> > But it doesn't always erase backward, it sometimes _moves_ backward.
> 
> I don't understand what you mean here.  Perhaps we use different
> terminology.  What I mean is that if point is on X in "fooX", I press
> backspace and end up with "foX".  This is true for any machine I have
> used, and I suspect that is the case for most people.

In which major mode(s)?

What does Backspace do in Info, for example?

> > Besides, what exactly is your proposal?  Backspace vs DEL is not the
> > only such issue: we have RET vs Enter (how many keyboards did you see
> > with a key labeled "RET"?).  And on my keyboard (and most probably on
> > yours as well) I have a key labeled "Delete" and another one labeled
> > "Del" -- how do we make sure users will not be confused by that?
> > There's also Tab the function key vs TAB the ASCII control character
> > -- are we going to make that distinction explicit as well?
> 
> Please forgive for speaking frankly, but I think this is all a bit of a
> mess.  Other software I use don't have any problem with any of this:
> backspace is backspace, delete is delete, return is return, etc.

Other software doesn't need to deal with all the different kinds of
terminals and keyboard drivers that Emacs tries to handle in a unified
manner.

> I do appreciate that there are historical reasons, the question of
> different keyboards, terminals, features that no one else has, and what
> have you.  But to me, as an end-user, it looks like a very complicated
> tapestry for a couple of keys that no one else seems to be struggling
> with.

Complex problems rarely if ever have simple solutions, and if they do,
those simple solutions are at best only 85% correct.  In most cases,
there's no easy way around complexity.  Therefore, the fact that the
solution is complex is not necessarily an indication that it is wrong
or sub-optimal.

> And in this case it boils down to the unfortunate situation that
> "backspace" is described as "DEL" in our documentation.

DEL is not a key, it is a character, ASCII 127.  By default, the
Backspace function key has the same effect as ASCII 127.

> I appreciate the hard work that went into this, of course.  I'll put
> looking into this properly on my list of things to work on.  I am
> currently already spread too thin with my many Emacs ideas, so I can't
> promise to look into this any time soon, unfortunately.
> 
> (I'm also not so sure I am not already in over my head here.  :-))

I know the feeling.  Don't give up, at least not yet.

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> > > I don't see any good way around this.  This is basic Emacs
> > > terminology, for which we did everything we could to document and
> > > clearly explain what we mean.
> >
> > The way I see around it is to change that terminology.
> 
> So that everyone who used Emacs until now will have to re-learn?
> 
> When I see DEL mentioned in the Emacs documentation, I immediately
> know what key that alludes to.  How would you propose to change the
> documentation while letting veteran users still understand it quickly
> and unequivocally?
> 
> > > You can't, because not every keyboard has that key.
> > > And because users still can confuse that with the BS
> > > (a.k.a. "C-h") key.
> >
> > I note that any keyboard I have ever seen or used has had a backspace
> > key.  It is of course not interesting to me what exact control codes
> > that key has been sending on various machines over the years.  When
> > pressed, it has erased text backwards.
> 
> But it doesn't always erase backward, it sometimes _moves_ backward.
> 
> Besides, what exactly is your proposal?  Backspace vs DEL is not the
> only such issue: we have RET vs Enter (how many keyboards did you see
> with a key labeled "RET"?).  And on my keyboard (and most probably on
> yours as well) I have a key labeled "Delete" and another one labeled
> "Del" -- how do we make sure users will not be confused by that?
> There's also Tab the function key vs TAB the ASCII control character
> -- are we going to make that distinction explicit as well?
> 
> This deceptively "simple" issue is full of difficulties and underwater
> rocks.  At the time, it took several non-trivial iterations to get the
> text in the manual about that as clear and descriptive as it is.  If
> you are serious with your suggestion, please propose how to treat this
> complex issue in its entirety; it isn't enough to say let's replace
> DEL with Backspace.
> 
> > Most other software seems to handle such keys gracefully and
> > transparently.  Why can't we?
> 
> I think we already do.

I agree with Eli on this.

However, it's true that many new users nowadays have no clue
about ASCII control characters, nor do they necessarily get
the relation, in Emacs, between characters and keys.

The "solution" is _not_ to change Emacs terminology or its
representation of such chars and keys.

To address that ignorance, we might consider adding a node
to the Emacs manual that addresses it explicitly, head-on.

Emacs users can benefit from learning about ASCII control
chars, including NUL, DEL, TAB, CR (RET), LF, FF, BS, BEL,
and ESC.

Also useful: knowing corresponding names C-@ (C-SPC, C-?),
C-i, C-m, C-j, C-l, C-h, C-g, and C-[.

Whether users learn all such names is not so important.
But knowing the names DEL, TAB, and RET is useful.
Likewise, C-i, C-m, and C-j.

And especially, being generally aware of Emacs's use of
control chars, and that multiple representations/names
are used, and that there is a wider legacy around this -
all of that is helpful.

Obtaining some awareness of this can even be an "Aha!"
moment, clarifying some of what might otherwise seem
arcane - much like learning about key-binding mnemonics
(<modifier>-[fbnposraedk]) can help provide perspective.

A node dedicated to this might clear up or prevent some
confusion, as well as make Emacs help/doc more helpful.

Likewise, relations between chars and keys that have
similar names, which sometimes might have similar
behavior (TAB, <tab>) but sometimes can instead be
faux amis (DEL, <delete> <backspace>).  Such confusion
can perhaps be addressed in the same place (node).
___

IMO, this (from SK) is misguided and really misses the
point, but it points out the disconnect we're having:

 "Other software I use don't have any problem with any
  of this: backspace is backspace, delete is delete,
  return is return, etc.

  I do appreciate that there are historical reasons, the
  question of different keyboards, terminals, features
  that no one else has, and what have you.  But to me,
  as an end-user, it looks like a very complicated
  tapestry for a couple of keys that no one else seems
  to be struggling with."

History is not what it's about, though history can also
provide some useful perspective.  These are not just
legacy artifacts.  They're living, useful correspondences.
Think about that the next time you use `C-q C-j' or `C-i'.
___

https://en.wikipedia.org/wiki/Control_character

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 10:26, Eli Zaretskii wrote:
>>> Perhaps the easiest fix would be to handle Delete same as Backspace here.
>> Yes, that could alleviate the problem in this particular case.
> Please don't, that would be a horribly wrong change. 

I have described an obvious problem: Emacs says press DEL to scroll, the 
user presses Del on their keyboard, and Emacs exits instead.

All that in a Help interface, which is supposed to help newbies. Not 
grizzled veterans.

It's a real problem, if you want people to actually use this feature.

 > Like making C-f move backwards.

If C-f never did anything in a certain interface, and doing this would 
help usability, why not.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 25 Apr 2021 13:20:00 +0300
> 
> On 25.04.2021 10:26, Eli Zaretskii wrote:
> >>> Perhaps the easiest fix would be to handle Delete same as Backspace here.
> >> Yes, that could alleviate the problem in this particular case.
> > Please don't, that would be a horribly wrong change. 
> 
> I have described an obvious problem: Emacs says press DEL to scroll, the 
> user presses Del on their keyboard, and Emacs exits instead.

I'm not opposed to finding a solution, I just don't think blindly
replacing each DEL with Backspace is a good solution.

We could mention Backspace in the text there, or we could add
PgUp/PgDn, for example

> All that in a Help interface, which is supposed to help newbies. Not 
> grizzled veterans.

You may be surprised to learn that I use that command quite often.

And in any case, we are not going to make veterans, grizzled or not,
unlearn what they have learned long ago, I hope.

> It's a real problem, if you want people to actually use this feature.
> 
>  > Like making C-f move backwards.
> 
> If C-f never did anything in a certain interface, and doing this would 
> help usability, why not.

But DEL does do something.  And so does Delete.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 13:38:00 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: stefan@marxist.se, emacs-devel@gnu.org
> 
> We could mention Backspace in the text there, or we could add
> PgUp/PgDn, for example

We could also say that Delete quits, like 'q', to make sure people
understand it isn't DEL.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 13:38, Eli Zaretskii wrote:
>> Cc: emacs-devel@gnu.org
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Sun, 25 Apr 2021 13:20:00 +0300
>>
>> On 25.04.2021 10:26, Eli Zaretskii wrote:
>>>>> Perhaps the easiest fix would be to handle Delete same as Backspace here.
>>>> Yes, that could alleviate the problem in this particular case.
>>> Please don't, that would be a horribly wrong change.
>>
>> I have described an obvious problem: Emacs says press DEL to scroll, the
>> user presses Del on their keyboard, and Emacs exits instead.
> 
> I'm not opposed to finding a solution, I just don't think blindly
> replacing each DEL with Backspace is a good solution.

That's not what I suggested there.

> We could mention Backspace in the text there, or we could add
> PgUp/PgDn, for example

Either/both would be an improvement.

In the graphical Emacs, at least, we could print <backspace> there 
instead of DEL. That should be unambiguous.

>> All that in a Help interface, which is supposed to help newbies. Not
>> grizzled veterans.
> 
> You may be surprised to learn that I use that command quite often.

Not really.

But still, the Help interface shouldn't be primarily targeted at people 
who know most of that stuff already.

I have tried to describe the situation with DEL as I understand it in 
another email, and probably got it only half right. After using Emacs 
for a decade and contributing code for a large part of it.

> And in any case, we are not going to make veterans, grizzled or not,
> unlearn what they have learned long ago, I hope.

Not everything in Emacs is perfect. Sometimes an improvement justifies a 
breaking change.

>> It's a real problem, if you want people to actually use this feature.
>>
>>   > Like making C-f move backwards.
>>
>> If C-f never did anything in a certain interface, and doing this would
>> help usability, why not.
> 
> But DEL does do something.  And so does Delete.

Abort? That isn't really "doing anything".

And aborting is even less semantic for that key than duplicating Backspace.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> We could mention Backspace in the text there, or we could add
>> PgUp/PgDn, for example
>
> Either/both would be an improvement.

I think adding PageUp/PageDown and displaying that is the best idea
here, so I have now done that on master.

This change is orthogonal to which keys we actually show in help, but I
propose suggesting these instead of SPC and DEL.  But I am unsure how to
do that.  In the manual we have:

    ‘C-v’
    ‘<PageDown>’
    ‘<next>’
         Scroll the display one screen forward, and move point onscreen if
         necessary (‘scroll-up-command’).  *Note Scrolling::.

    ‘M-v’
    ‘<PageUp>’
    ‘<prior>’
         Scroll one screen backward, and move point onscreen if necessary
         (‘scroll-down-command’).  *Note Scrolling::.

So there are two symbols for PgUp/PgDn.  If I type `C-h k' followed by
my Page Down key, I see that it is called "<next>" here.  But the
beginner-friendly name for that key would be "<PageDown>".

So does that mean that the below diff correct?  And is there a need to
handle `PageDown' and `PageUp' in addition to `next' and `prior'?


diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 6a0e11574c..663b14d3d1 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -174,9 +174,9 @@ make-help-screen
                                              (point-max))
                                             ""
                                           (concat  ", or "
-
(help--key-description-fontified "\s") ; SPC
+
(help--key-description-fontified (kbd "<PageDown>"))
                                                    " or "
-
(help--key-description-fontified "\d") ; DEL
+
(help--key-description-fontified (kbd "<PageUp>"))
                                                    " to scroll"))))
                            char (aref key 0)))

diff --git a/lisp/help.el b/lisp/help.el
index e143501081..8d6279de8f 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -232,9 +232,9 @@ 'help
   (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.]
C-[cdefmnoptw] or ?")
   (concat
    "\(Type "
-   (help--key-description-fontified "\s") ; SPC
+   (help--key-description-fontified (kbd "<PageDown>"))
    " or "
-   (help--key-description-fontified "\d") ; DEL
+   (help--key-description-fontified (kbd "<PageUp>"))
    " to scroll, "
    (help--key-description-fontified "\C-s")
    " to search, or \\<help-map>\\[help-quit] to exit.)"

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 18:18, Stefan Kangas wrote:
> I think adding PageUp/PageDown and displaying that is the best idea
> here, so I have now done that on master.

I really like using SPC/S-SPC for scrolling.

It also works in other programs (even though Shift-Space rarely shows up 
in any menus or hints), so it should be helpful to support as well.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 25.04.2021 18:18, Stefan Kangas wrote:
>> I think adding PageUp/PageDown and displaying that is the best idea
>> here, so I have now done that on master.
>
> I really like using SPC/S-SPC for scrolling.
>
> It also works in other programs (even though Shift-Space rarely shows up
> in any menus or hints), so it should be helpful to support as well.

I agree it should be added, and as I pointed out in a different reply
that is also more consistent with the binding that already exists in
`special-mode-map'.

However, the `make-help-screen' macro uses (read-key-sequence nil) to
get the key, but when I press S-SPC, that function only returns " ".

So perhaps we need to change `make-help-screen' to use `read-event' or
something?  But that seems like a bigger change than I want to get into
right now just to add this binding.

IOW, if anyone wants to help with this, please go ahead.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 30.04.2021 20:39, Stefan Kangas wrote:

>> I really like using SPC/S-SPC for scrolling.
>>
>> It also works in other programs (even though Shift-Space rarely shows up
>> in any menus or hints), so it should be helpful to support as well.
> 
> I agree it should be added, and as I pointed out in a different reply
> that is also more consistent with the binding that already exists in
> `special-mode-map'.
> 
> However, the `make-help-screen' macro uses (read-key-sequence nil) to
> get the key, but when I press S-SPC, that function only returns " ".

Try (read-key-sequence nil), S-SPC in some special mode buffer like 
Xref, it will return [33554446].

So I think you just need to define that binding in the local map. The 
below works for me (only in graphical Emacs, though). Not sure what to 
do with the magic number.

diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 7fe1fb6c3d..8216ddfeb5 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -112,6 +112,7 @@ make-help-screen
               (let ((minor-mode-map-alist nil))
                 (setcdr local-map ,helped-map)
                 (define-key local-map [t] 'undefined)
+               (define-key local-map (kbd "S-SPC") 'undefined)
                 ;; Make the scroll bar keep working normally.
                 (define-key local-map [vertical-scroll-bar]
                   (lookup-key global-map [vertical-scroll-bar]))
@@ -143,6 +144,7 @@ make-help-screen
                   (goto-char (point-min))
                   (while (or (memq char (append help-event-list
                                                 (cons help-char '( ?? 
?\C-v ?\s ?\177 deletechar backspace vertical-scroll-bar ?\M-v
+                                                                  33554464
                                                                    next 
prior up down))))
                              (eq (car-safe char) 'switch-frame)
                              (equal key "\M-v"))
@@ -152,7 +154,7 @@ make-help-screen
                           (handle-switch-frame char))
                          ((memq char '(?\C-v ?\s next))
                           (scroll-up))
-                        ((or (memq char '(?\177 ?\M-v deletechar 
backspace prior))
+                        ((or (memq char '(?\177 ?\M-v deletechar 
backspace prior 33554464))
                               (equal key "\M-v"))
                           (scroll-down))
                          ((memq char '(down))

Re: Proposal for an improved `help-for-help'

[Stefan Monnier]

> +                                                                  33554464
                                                                     ^^^^^^^^
Aka                                                                   ?\S-\s


        Stefan

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 30.04.2021 23:36, Stefan Monnier wrote:
> Aka                                                                   ?\S-\s

Much better, thanks.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

> So I think you just need to define that binding in the local map. The
> below works for me (only in graphical Emacs, though).

Actually, based on yours and Stefan M's comments, an even simpler patch
worked here.  So I have now installed it on master (commit fb44f897d9).

Please verify that it works for you.  (As usual, "touch lisp/help.el"
first to make sure the macro is re-expanded.)

diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 132530deb3..9461579a99 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -142,7 +142,7 @@ make-help-screen
                    (setq new-minor-mode-map-alist minor-mode-map-alist))
                  (goto-char (point-min))
                  (while (or (memq char (append help-event-list
-                                               (cons help-char '( ??
?\C-v ?\s ?\177 deletechar backspace vertical-scroll-bar ?\M-v
+                                               (cons help-char '( ??
?\C-v ?\s ?\177 deletechar backspace vertical-scroll-bar ?\M-v ?\S-\s

next prior up down))))
                             (eq (car-safe char) 'switch-frame)
                             (equal key "\M-v"))
@@ -152,7 +152,7 @@ make-help-screen
                          (handle-switch-frame char))
                         ((memq char '(?\C-v ?\s next))
                          (scroll-up))
-                        ((or (memq char '(?\177 ?\M-v deletechar
backspace prior))
+                        ((or (memq char '(?\177 ?\M-v deletechar
backspace prior ?\S-\s))
                              (equal key "\M-v"))
                          (scroll-down))
                         ((memq char '(down))

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 02.05.2021 13:23, Stefan Kangas wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
>> So I think you just need to define that binding in the local map. The
>> below works for me (only in graphical Emacs, though).
> 
> Actually, based on yours and Stefan M's comments, an even simpler patch
> worked here.  So I have now installed it on master (commit fb44f897d9).
> 
> Please verify that it works for you.  (As usual, "touch lisp/help.el"
> first to make sure the macro is re-expanded.)

Looks good (and works!). Thank you.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> So does that mean that the below diff correct?  And is there a need to
> handle `PageDown' and `PageUp' in addition to `next' and `prior'?

No replies here, so I have now pushed the below change to master
(commit 04266a2cac).

If this leads to any problems, please reply here or report a bug and put
me on Cc.

> diff --git a/lisp/help-macro.el b/lisp/help-macro.el
> index 6a0e11574c..663b14d3d1 100644
> --- a/lisp/help-macro.el
> +++ b/lisp/help-macro.el
> @@ -174,9 +174,9 @@ make-help-screen
>                                               (point-max))
>                                              ""
>                                            (concat  ", or "
> -                                                   (help--key-description-fontified "\s") ; SPC
> +                                                   (help--key-description-fontified (kbd "<PageDown>"))
>                                                     " or "
> -                                                   (help--key-description-fontified "\d") ; DEL
> +                                                   (help--key-description-fontified (kbd "<PageUp>"))
>                                                     " to scroll"))))
>                             char (aref key 0)))
>
> diff --git a/lisp/help.el b/lisp/help.el
> index e143501081..8d6279de8f 100644
> --- a/lisp/help.el
> +++ b/lisp/help.el
> @@ -232,9 +232,9 @@ 'help
>    (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
>    (concat
>     "\(Type "
> -   (help--key-description-fontified "\s") ; SPC
> +   (help--key-description-fontified (kbd "<PageDown>"))
>     " or "
> -   (help--key-description-fontified "\d") ; DEL
> +   (help--key-description-fontified (kbd "<PageUp>"))
>     " to scroll, "
>     (help--key-description-fontified "\C-s")
>     " to search, or \\<help-map>\\[help-quit] to exit.)"

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>>>> Perhaps the easiest fix would be to handle Delete same as Backspace 
>>>> here.
>>>
>>> Yes, that could alleviate the problem in this particular case.
>>
>> Please don't, that would be a horribly wrong change.
>
> I have described an obvious problem: Emacs says press DEL to scroll, the 
> user presses Del on their keyboard, and Emacs exits instead.
>
> All that in a Help interface, which is supposed to help newbies. Not 
> grizzled veterans.
>
> It's a real problem, if you want people to actually use this feature.
>

What about adding (define-key map [delete] 'scroll-down-command) to 
help-map?

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 12:47:56 +0000
> From: Gregory Heytings <gregory@heytings.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
>  emacs-devel@gnu.org
> 
> 
> >>>> Perhaps the easiest fix would be to handle Delete same as Backspace 
> >>>> here.
> >>>
> >>> Yes, that could alleviate the problem in this particular case.
> >>
> >> Please don't, that would be a horribly wrong change.
> >
> > I have described an obvious problem: Emacs says press DEL to scroll, the 
> > user presses Del on their keyboard, and Emacs exits instead.
> >
> > All that in a Help interface, which is supposed to help newbies. Not 
> > grizzled veterans.
> >
> > It's a real problem, if you want people to actually use this feature.
> 
> What about adding (define-key map [delete] 'scroll-down-command) to 
> help-map?

Isn't that what Dmitry suggested above?

Btw, make-help-screen already seems to recognize the <Delete> key, so
why isn't that already supported?

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 16:05:29 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org, stefan@marxist.se, dgutov@yandex.ru
> 
> > What about adding (define-key map [delete] 'scroll-down-command) to 
> > help-map?
> 
> Isn't that what Dmitry suggested above?
> 
> Btw, make-help-screen already seems to recognize the <Delete> key, so
> why isn't that already supported?

Seems like a regression in Emacs 24.1: in Emacs 23.4 <Delete> scrolls
backward, like DEL.

RE: [External] : Re: Proposal for an improved `help-for-help'

[Drew Adams]

> Seems like a regression in Emacs 24.1: in Emacs 23.4 <Delete> 
> scrolls backward, like DEL.

FWIW, I don't see that on MS Windows with `emacs -Q'.
I don't see it with Emacs 20 through 23 (or later).

If you're talking about modes like Info or Help then
when I hit the key labeled "Delete", which Emacs tells
me is the key <delete> I get an error saying that the
buffer is read-only.

And if I use `C-h k' with that key Emacs tells me:
"C-d (translated from <delete>) runs the command delete-char".
(Emacs 20 doesn't include the parenthetical phrase.)

Likely I've misunderstood what you're saying.

Re: [External] : Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "dgutov@yandex.ru" <dgutov@yandex.ru>,
>         "stefan@marxist.se"
> 	<stefan@marxist.se>,
>         "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> Date: Sun, 25 Apr 2021 16:22:41 +0000
> 
> Likely I've misunderstood what you're saying.

Yes.  I was talking about <Delete> after "C-h C-h".

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>>>>>> Perhaps the easiest fix would be to handle Delete same as Backspace 
>>>>>> here.
>>>>>
>>>>> Yes, that could alleviate the problem in this particular case.
>>>>
>>>> Please don't, that would be a horribly wrong change.
>>>
>>> I have described an obvious problem: Emacs says press DEL to scroll, 
>>> the user presses Del on their keyboard, and Emacs exits instead.
>>>
>>> All that in a Help interface, which is supposed to help newbies. Not 
>>> grizzled veterans.
>>>
>>> It's a real problem, if you want people to actually use this feature.
>>
>> What about adding (define-key map [delete] 'scroll-down-command) to 
>> help-map?
>
> Isn't that what Dmitry suggested above?
>

Whoops, yes, indeed, I wrote too fast.  If that would be a horribly wrong 
change, I'd suggest to bind it to "ignore".  That would at least avoid the 
problem of help screen disappearing when the user presses Del on their 
keyboard.  And they would at the same time become aware of the fact that 
Del on their keyboard is not DEL in Emacs.

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 13:16:33 +0000
> From: Gregory Heytings <gregory@heytings.org>
> Cc: dgutov@yandex.ru, stefan@marxist.se, emacs-devel@gnu.org
> 
> >> What about adding (define-key map [delete] 'scroll-down-command) to 
> >> help-map?
> >
> > Isn't that what Dmitry suggested above?
> 
> Whoops, yes, indeed, I wrote too fast.  If that would be a horribly wrong 
> change

I'm sorry, what I wrote there wasn't meant to call Dmitry's suggestion
"horribly wrong".  Although I realize how it could be easily read that
way, and I'm sorry for not paying attention to that reading.

Here's the relevant part of that exchange:

> > I would prefer that <backspace> would just be printed as such,
> > everywhere.
> 
> You can't, because not every keyboard has that key.  And because users
> still can confuse that with the BS (a.k.a. "C-h") key.  And because we
> have normal-erase-is-backspace-mode.
> 
> > > Perhaps the easiest fix would be to handle Delete same as Backspace here.
> > 
> > Yes, that could alleviate the problem in this particular case.
> 
> Please don't, that would be a horribly wrong change.  Like making C-f
> move backwards.

What I consider to be "horribly wrong" is to replace DEL _everywhere_
by <Backspace>, which was the original suggestion above.  I don't
object to handling <Delete> like DEL in this particular case,
especially since we already did that, since long ago, and it somehow
regressed.

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

[-- Attachment #1: Type: text/plain, Size: 674 bytes --]


>
> What I consider to be "horribly wrong" is to replace DEL _everywhere_ by 
> <Backspace>, which was the original suggestion above.  I don't object to 
> handling <Delete> like DEL in this particular case, especially since we 
> already did that, since long ago,
>

This is what I understood, and why I made the same suggestion.  I couldn't 
believe that binding [delete] to scroll-up-command could be wrong.

>
> and it somehow regressed.
>

It's because the handling of Delete has changed in Emacs 24.  It became 
"deletechar", it was "delete" earlier.  Replacing the two occurrences of 
"delete" by "deletechar" in help-macro.el fixes the regression.  Patch 
attached.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-diff; name=Fix-the-handling-of-the-Delete-key-in-help-screens.patch, Size: 1698 bytes --]

From 5aee3a7ab1433e77a40854c1eca37c49b6b1f9e4 Mon Sep 17 00:00:00 2001
From: Gregory Heytings <gregory@heytings.org>
Date: Sun, 25 Apr 2021 13:30:15 +0000
Subject: [PATCH] Fix the handling of the Delete key in help screens.

lisp/help-macro.el (make-help-screen): Handle the Delete key in help
screens as in Emacs 23 and earlier.
---
 lisp/help-macro.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lisp/help-macro.el b/lisp/help-macro.el
index 96edeaf466..7fc128c73a 100644
--- a/lisp/help-macro.el
+++ b/lisp/help-macro.el
@@ -148,7 +148,7 @@ make-help-screen
                    (setq new-minor-mode-map-alist minor-mode-map-alist))
                  (goto-char (point-min))
                  (while (or (memq char (append help-event-list
-                                               (cons help-char '(?? ?\C-v ?\s ?\177 delete backspace vertical-scroll-bar ?\M-v))))
+                                               (cons help-char '(?? ?\C-v ?\s ?\177 deletechar backspace vertical-scroll-bar ?\M-v))))
                             (eq (car-safe char) 'switch-frame)
                             (equal key "\M-v"))
                    (condition-case nil
@@ -157,7 +157,7 @@ make-help-screen
                          (handle-switch-frame char))
                         ((memq char '(?\C-v ?\s))
                          (scroll-up))
-                        ((or (memq char '(?\177 ?\M-v delete backspace))
+                        ((or (memq char '(?\177 ?\M-v deletechar backspace))
                              (equal key "\M-v"))
                          (scroll-down)))
                      (error nil))
-- 
2.30.2

Re: Proposal for an improved `help-for-help'

[Eli Zaretskii]

> Date: Sun, 25 Apr 2021 13:32:48 +0000
> From: Gregory Heytings <gregory@heytings.org>
> cc: emacs-devel@gnu.org, stefan@marxist.se, dgutov@yandex.ru
> 
> > and it somehow regressed.
> >
> 
> It's because the handling of Delete has changed in Emacs 24.  It became 
> "deletechar", it was "delete" earlier.  Replacing the two occurrences of 
> "delete" by "deletechar" in help-macro.el fixes the regression.  Patch 
> attached.

Thanks, installed.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 16:24, Eli Zaretskii wrote:
> What I consider to be "horribly wrong" is to replace DEL_everywhere_
> by <Backspace>, which was the original suggestion above.  I don't
> object to handling <Delete> like DEL in this particular case,
> especially since we already did that, since long ago, and it somehow
> regressed.

Excellent.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 02:48, Stefan Kangas wrote:

> The easiest way of fixing it is to change the separator to "\s\t"
> instead of just "\t".  It would be slightly less clean I guess, but
> since the screen is modal I suppose most people will never notice the
> difference.  WDYT?

Sure. I don't see a downside.

>> - Not a regression, old problem:
>>
>> Instructions say "Type ..., or SPC or DEL to scroll".
>>
>> But DEL here is actually <backspace>. If I just press Delete on the
>> keyboard, help-for-help exits instead of scrolling.
>>
>> And the target audience of help-for-help is probably at least as
>> ignorant as myself about the difference between DEL and Delete.
> 
> As you say, this is an old problem.  For example `C-h k <backspace>'
> here gives a help screen that cryptically says "DEL (translated from
> <backspace>)".  I suppose most users have no idea what that means, other
> than some vague notion that "DEL is clearly just the same as backspace".
> 
> I would prefer that <backspace> would just be printed as such,
> everywhere.  I'm guessing there are historical reasons for why this
> isn't already the case.  It would be great if we could fix this.

It's an implementation detail which leaks from the terminal keyboard 
support, which only supports a reduced set of keys.

IIUC, DEL is an ASCII code which backspace translates to on the 
terminal. You can also input it in a different way, e.g. by pressing C-? 
(on a terminal).

In a graphical frame, there is also <backspace> event which Emacs 
translates to DEL by default, but one can set different binding for it, 
even though that's inadvisable.

To sum up, there is a technical complexity to that problem, not just 
"old timers will hate change", so I'd leave that to a separate 
discussion, at least. With related <return>/RET and <tab>/TAB 
distinctions that Eli mentioned as well, which have caused their share 
of problems too.

DEL vs Backspace (was: Proposal for an improved `help-for-help')

[Stefan Monnier]

> As you say, this is an old problem.  For example `C-h k <backspace>'
> here gives a help screen that cryptically says "DEL (translated from
> <backspace>)".  I suppose most users have no idea what that means, other
> than some vague notion that "DEL is clearly just the same as backspace".

This is harder to fix, but maybe we should tackle those problem.
Basically, the issue is that we have two different events: the symbol
`backspace` generated under GUIs and the DEL character (aka ^?)
generated under ttys.

The way we unify them is via `function-key-map` which maps `backspace`
to DEL when there's no binding for `backspace`.

Maybe we should inverse this mapping.  Similarly for RET-vs-return and
TAB-vs-tab.

Another benefit in the long run would be to free C-i and C-m for the
users to bind as they please in GUI frames.


        Stefan

Re: DEL vs Backspace

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Maybe we should inverse this mapping.  Similarly for RET-vs-return and
> TAB-vs-tab.
>
> Another benefit in the long run would be to free C-i and C-m for the
> users to bind as they please in GUI frames.

Sounds good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: DEL vs Backspace

[Stefan Monnier]

Lars Ingebrigtsen [2021-04-25 18:49:43] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Maybe we should inverse this mapping.  Similarly for RET-vs-return and
>> TAB-vs-tab.

[ And I forgot to mention ESC-vs-escape in the list.  ]

>> Another benefit in the long run would be to free C-i and C-m for the
>> users to bind as they please in GUI frames.
>
> Sounds good to me.

Note that beside the question of whether we want it or not, there's the
question of how to do it without breaking (too much) existing code and
use cases.

Maybe we could start by adding a DEL => backspace remapping *without*
removing the backspace => DEL remapping?

Still, as modes start changing their keymaps to place bindings on
`backspace` we'll end up with situations where a minor modes has
a mapping for DEL and the major mode has a different mapping for
`backspace` and they'll end up chosen based on the incidental "tty or
GUI?" distinction rather than based on the minor modes bindings's
precedence over major modes's.

This said, such problems already exist since a fair number of modes
mistakently bind commands to `tab` instead of TAB or to `return` instead
of RET, leading to overriding minor-vs-major precedence rules.


        Stefan

Re: DEL vs Backspace

[Dmitry Gutov]

On 25.04.2021 20:25, Stefan Monnier wrote:
> Still, as modes start changing their keymaps to place bindings on
> `backspace` we'll end up with situations where a minor modes has
> a mapping for DEL and the major mode has a different mapping for
> `backspace` and they'll end up chosen based on the incidental "tty or
> GUI?" distinction rather than based on the minor modes bindings's
> precedence over major modes's.

Basically something we've had in the other direction, but ironed out 
over the years (often by having minor modes bind both <tab> and <TAB>).

Perhaps if TAB -> <tab> (and other such translations) were only enabled 
in the terminal, that would remove the incentive to use TAB, DEL and RET 
bindings for this purpose.

But that will only work after the transition period is over.

Re: DEL vs Backspace

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Maybe we could start by adding a DEL => backspace remapping *without*
> removing the backspace => DEL remapping?

Interesting idea.

If I understand you correctly, that would mean something like:

    (define-key function-key-map [?\C-?] [backspace])

And that would allow you to bind keys to `[backspace]' and have them
work also on the terminal?

(The above translation doesn't seem to actually work.  I'm not sure if
I'm doing something wrong, or if this is just not supported.)

> Still, as modes start changing their keymaps to place bindings on
> `backspace` we'll end up with situations where a minor modes has
> a mapping for DEL and the major mode has a different mapping for
> `backspace` and they'll end up chosen based on the incidental "tty or
> GUI?" distinction rather than based on the minor modes bindings's
> precedence over major modes's.

The only idea I have would be to add byte-compiler warnings for
`global-set-key' and `define-key' like:

    Deprecated binding to `"DEL"', use `[backspace]' instead

But perhaps there would still exist reasons why someone would want to
specifically bind "DEL"?

> This said, such problems already exist since a fair number of modes
> mistakently bind commands to `tab` instead of TAB or to `return` instead
> of RET, leading to overriding minor-vs-major precedence rules.

Re: DEL vs Backspace

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 25 Apr 2021 19:45:14 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>, emacs-devel@gnu.org
> 
> > Still, as modes start changing their keymaps to place bindings on
> > `backspace` we'll end up with situations where a minor modes has
> > a mapping for DEL and the major mode has a different mapping for
> > `backspace` and they'll end up chosen based on the incidental "tty or
> > GUI?" distinction rather than based on the minor modes bindings's
> > precedence over major modes's.
> 
> The only idea I have would be to add byte-compiler warnings for
> `global-set-key' and `define-key' like:
> 
>     Deprecated binding to `"DEL"', use `[backspace]' instead

That wasn't Stefan's idea (or if it was, I don't like it).  The
problem is not that DEL is bound, the problem is that DEL and
<Backspace> are bound differently.

We cannot deprecate binding of DEL, because we don't want to break
users of systems where that function key is unavailable (some terminal
emulator comes to mind).

> But perhaps there would still exist reasons why someone would want to
> specifically bind "DEL"?

Certainly: if <Backspace> doesn't exist or isn't supported by the
keyboard.

Re: DEL vs Backspace

[Dmitry Gutov]

On 26.04.2021 14:45, Eli Zaretskii wrote:
>> But perhaps there would still exist reasons why someone would want to
>> specifically bind "DEL"?
> Certainly: if <Backspace> doesn't exist or isn't supported by the
> keyboard.

When function-key-map maps DEL to <backspace>, the user can refer to 
<backspace> in their key mappings, even if that key is absent on the 
keyboard.

Re: DEL vs Backspace

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Maybe we should inverse this mapping.  Similarly for RET-vs-return and
  > > TAB-vs-tab.
  > >
  > > Another benefit in the long run would be to free C-i and C-m for the
  > > users to bind as they please in GUI frames.

  > Sounds good to me.

This might be an improvement.  At the same time, this could easily
break some people's init files in subtle ways, and that could be a real pain.
It might not be obvious what users need to do to fix their configurations.

"Try the change and see if it breaks" is not an adequate way to
evaluate the consequences.  It will take years for users to encounter
this change and discover whether it broke anything.  By that time, the change
will be an "old" change (though not old _for them_).

To properly evaluate this change calls for someone to thoroughly
understand the full set of use cases of rebinding these keys, and
verify that nothing too bad will happen in any of them.  This isn't
impossibly hard, but it requires a substantial amount of careful
thought.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

>> - I have 'C-h C-a' rebound to 'apropos' instead of 'apropos-command'
>> locally. As a result, help-for-help shows 'M-x apropos-commnad' in the
>> first column and (see also 'a') later.
>>
>> The regression is that the previous version printed
>>
>>    M-x apropos-command PATTERN
>>
>> followed by 3 spaces, whereas the new one prints
>>    M-x apropos-commandTABSearch for commands (see also a)
>>
>> and for some reason TAB is printed with zero width.
>>
>> It's a minor thing, to be honest.
>
> I can reproduce that here.
>
> The easiest way of fixing it is to change the separator to "\s\t"
> instead of just "\t".  It would be slightly less clean I guess, but
> since the screen is modal I suppose most people will never notice the
> difference.  WDYT?

I have now pushed this fix to master (commit 2ab8d1ee3b).

Please verify that it works for you.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 27.04.2021 23:56, Stefan Kangas wrote:
> I have now pushed this fix to master (commit 2ab8d1ee3b).
> 
> Please verify that it works for you.

Looks fixed. Thanks!

Re: Proposal for an improved `help-for-help'

[Gregory Heytings]

>
> That was 2 weeks ago.  Based on the feedback I received at the time, I 
> have now pushed my final version of this patch to master.
>
> There is of course still time for further tweaks before Emacs 28. I 
> invite anyone to report bugs in case they can see any opportunities for 
> improving this.  (Feel free to CC me if you do as I'm currently not 
> subscribed to the bug list.)
>
> Thank you to everyone who contributed to the discussion!
>

Thank you, this is very nice!

A small possible improvement, which I hadn't seen earlier: "Show last 300 
input keystrokes" could be improved I think, it's a configurable option. 
So I would either remove the constant "300" (if the precise size of the 
lossage is not important enough to be indicated there), or by using the 
return value of (lossage-size).

Another small possible improvement: add a "\n" at the end of the list, so 
that the cursor does not jump to the end of the line when you reach the 
last item.

Re: Proposal for an improved `help-for-help'

[Juri Linkov]

> A small possible improvement, which I hadn't seen earlier: "Show last 300
> input keystrokes" could be improved I think, it's a configurable option. So
> I would either remove the constant "300" (if the precise size of the
> lossage is not important enough to be indicated there), or by using the
> return value of (lossage-size).

Isn't "300" in the "last 300 input keystrokes (lossage)"
a reference to the last 300 Spartans?

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Gregory Heytings <gregory@heytings.org> writes:

> A small possible improvement, which I hadn't seen earlier: "Show last 300
> input keystrokes" could be improved I think, it's a configurable option.
> So I would either remove the constant "300" (if the precise size of the
> lossage is not important enough to be indicated there), or by using the
> return value of (lossage-size).

Yup, this is new in Emacs 28 and it seems that `help-for-help' was not
updated.  I've changed it to use `lossage-size', mostly because I just
couldn't think of a better wording.

> Another small possible improvement: add a "\n" at the end of the list, so
> that the cursor does not jump to the end of the line when you reach the
> last item.

Done.

Thanks for the suggestions!

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Stefan Kangas <stefan@marxist.se> writes:

> Stefan Kangas <stefan@marxist.se> writes:

I had missed this and it looks great.  I have a few small comments.

> Getting Help
>
>    m	Help for current minor and major modes and their commands

Why not "Show help for" like the others?  Also I'd say
"major and minor" since it shows the major mode first.

>    b	Show all key bindings
>    k	Show help for key
>    c	Show help for key briefly
>    w	Show which key runs a given command
>
>    a	Search for commands (see also M-x apropos)
>    d	Search documentation of functions, variables, and other items

In other places you use the word "help" instead of
"documentation".  I agree "Search documentation" reads
better than "Search help" but by using a different word it
suggests to me that it searches differen text than what is
shown by other help commands.  Maybe "Seach help text" would
be better?

>    f	        Show help for function
>    o	Show help for function or variable

I would move this one either above f or below v.  It seem
odd to me be to placed between them.  

>    v	Show help for variable
>
> Info Manuals
>
>    r	Show Emacs manual
>    F	Show Emacs manual section for command
>    K	Show Emacs manual section for command bound to key
>    i	        Show all included manuals

I feel like the word info should be here, as that's the
mnemonic (not "included").

>    R	Show given manual

Is this a new function in Emacs 28?  I don't see it in Emacs
27.  For w above you say "a given command" maybe these two
should match?

>    S	Find symbol in Info manual for current programming language

With the construction used above for F and K this would
read: "Show current programming language manual section for
symbol"  If that's too long, perhaps those commands should
use this construction with "Find..."

>
> Misc Help
>
>    p	Search for packages matching topic
>    P	Describe Emacs Lisp package
>    e	Show recent messages

I'd like to see word the "echo" in here as the mnemonic. Perhaps
"Show recent messages from the echo area" or "Show recently
echoed messages"

>    g	Show information about the GNU project
>    l		Show last 300 input keystrokes (lossage)
>    s	Show current syntax table
>    .		Show local help at point
>    t		Start the Emacs tutorial

I understand that the tuturial is probably the least used
command here, but I'll make the case that for a new user,
the ones most likely to use C-h C-h, it's perhaps the most
important one.  I'd put it first in this section.

>
> Help Files
>
>    C-a	About Emacs
>    C-c	Emacs copying permission (GNU General Public License)
>    C-d	Debugging GNU Emacs

The "GNU" seems unnecessary here, particularly compared to
the other lines.

>    C-e	External packages
>    C-f	Emacs FAQ
>    C-m	Order printed Emacs manuals
>    C-n	News of recent Emacs changes
>    C-o	Emacs ordering and distribution information
>    C-p	Known Emacs problems
>    C-t	Emacs TODO
>    C-w	Information on absence of warranty for GNU Emacs
>
> Language Help
>
>    C	Describe coding system
>    I		Describe input method
>    L	Describe language environment
>    h	Display the HELLO file illustrating various scripts
>
>

-- 

Howard

Re: Proposal for an improved `help-for-help'

[John Yates]

Meta comment: I find it much easier to internalize
commands for which I am offered an obvious mnemonic.
I do not know if doing so is one of your goals, but
if not might, I suggest it?  That would include using
some form of highlighting to call out the mnemonic.

So, for instance, rather than

  c  Show help for key briefly

This is easier to memorize (and more accurate?)

  c  Echo [c]ommand bound to input event

/john

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

John Yates <john@yates-sheets.org> writes:

> Meta comment: I find it much easier to internalize
> commands for which I am offered an obvious mnemonic.
> I do not know if doing so is one of your goals, but
> if not might, I suggest it?  That would include using
> some form of highlighting to call out the mnemonic.

All things being equal, yes a mnemonic is better.

There are different kinds of balance one can strike in a text like this.
It is not necessarily a very easy text to write, as there are many
variables at play; it needs to be precise, brief, understandable,
skimmable, etc..

I will think a bit about your suggestion, but a priori I would suggest
proceeding along these lines:

1. First, find a working, brief text with the above mentioned qualities.

2. Later, look it all over and see if it is possible to add mnemonics
   if/where they are missing without compromising the other aspects too
   much.

3. Perhaps even stylize the mnemonics (I'd use a subtle color for this).

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

> I had missed this and it looks great.  I have a few small comments.

Thanks!

>> Getting Help
>>
>>    m	Help for current minor and major modes and their commands
>
> Why not "Show help for" like the others?

Basically to keep it short, and I feel it reads better.  I'm not sure
the consistency is overly important here.

Perhaps we should even remove all instances of "Show", as it is fairly
obvious that help commands will show something.

> Also I'd say "major and minor" since it shows the major mode first.

Fixed.

>>    a	Search for commands (see also M-x apropos)
>>    d	Search documentation of functions, variables, and other items
>
> In other places you use the word "help" instead of
> "documentation".  I agree "Search documentation" reads
> better than "Search help" but by using a different word it
> suggests to me that it searches differen text than what is
> shown by other help commands.  Maybe "Seach help text" would
> be better?

I see what you're saying, but OTOH "documentation" is the mnemonic for
"d".  So I'm not sure what's best here.

>>    f	        Show help for function
>>    o	Show help for function or variable
>
> I would move this one either above f or below v.  It seem
> odd to me be to placed between them.

Agreed, changed.

>> Info Manuals
>>
>>    r	Show Emacs manual
>>    F	Show Emacs manual section for command
>>    K	Show Emacs manual section for command bound to key
>>    i	        Show all included manuals
>
> I feel like the word info should be here, as that's the
> mnemonic (not "included").

I'm fine with that.  (Eli has also pointed out it should say "installed"
rather than "included".)

>>    R	Show given manual
>
> Is this a new function in Emacs 28?  I don't see it in Emacs
> 27.  For w above you say "a given command" maybe these two
> should match?

I think it's new, yes.

Eli suggested "Show specified command", which I think is okay.  I'm not
sure they should match as they are far apart, and IMHO they read a bit
better this way.

>>    S	Find symbol in Info manual for current programming language
>
> With the construction used above for F and K this would
> read: "Show current programming language manual section for
> symbol"  If that's too long, perhaps those commands should
> use this construction with "Find..."

Hmm.  I'm not sure we need the consistency, as the "Show" implies that
exactly what you're looking for will always be there: The Emacs Manual
won't go anywhere.

Whereas "Find" implies that we must first see if there even exists any
documentation for this particular symbol/identifier/name.

>> Misc Help
>>
>>    p	Search for packages matching topic
>>    P	Describe Emacs Lisp package
>>    e	Show recent messages
>
> I'd like to see word the "echo" in here as the mnemonic. Perhaps
> "Show recent messages from the echo area" or "Show recently
> echoed messages"

It basically becomes a decision of where to strike the balance between
brevity and mnemonics.

We have below:

>>    l		Show last 300 input keystrokes (lossage)

So I'd suggest: "Show recent messages (from echo area)"

It reads better (and faster), I think.

>>    t		Start the Emacs tutorial
>
> I understand that the tuturial is probably the least used
> command here, but I'll make the case that for a new user,
> the ones most likely to use C-h C-h, it's perhaps the most
> important one.  I'd put it first in this section.

Sure, why not?  My initial concern was that this gives a less prominent
place to Emacs packages, but having tested it I think it is perfectly
okay this way.

>> Help Files
>>
>>    C-a	About Emacs
>>    C-c	Emacs copying permission (GNU General Public License)
>>    C-d	Debugging GNU Emacs
>
> The "GNU" seems unnecessary here, particularly compared to
> the other lines.

The problem is that the license is the "GNU GPL", while the "General
Public License" could refer to anything... I think?  Could we just use
"GNU GPL"?  Perhaps Richard has something to add?

Thanks a lot for these detailed comments.

This is all very subjective, so please bare with me as I'm trying to
take into account all the comments and work out a coherent whole.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Stefan Kangas <stefankangas@gmail.com> writes:

>>> Getting Help
>>>
>>>    m	Help for current minor and major modes and their commands
>>
>> Why not "Show help for" like the others?
>
> Basically to keep it short, and I feel it reads better.  I'm not sure
> the consistency is overly important here.
>
> Perhaps we should even remove all instances of "Show", as it is fairly
> obvious that help commands will show something.

Long ago a technical writer told me of the importance of
consistency in technical writing as opposed to other prose
writing where redundancy is more of an issue.  I agree it's
not critically important here and that there are other
considerations, but I did want to point the inconsistencies
when I saw them.

>>>    a	Search for commands (see also M-x apropos)
>>>    d	Search documentation of functions, variables, and other items
>>
>> In other places you use the word "help" instead of
>> "documentation".  I agree "Search documentation" reads
>> better than "Search help" but by using a different word it
>> suggests to me that it searches differen text than what is
>> shown by other help commands.  Maybe "Seach help text" would
>> be better?
>
> I see what you're saying, but OTOH "documentation" is the mnemonic for
> "d".  So I'm not sure what's best here.

The mnemonic is a good point.  I might go with "help
documentation" or "help docstrings".  If you don't like
either of those, then I'd just leave it as you have it.

>>>    R	Show given manual
>>
>> For w above you say "a given command" maybe these two
>> should match?
>
> Eli suggested "Show specified command", which I think is okay.  I'm not
> sure they should match as they are far apart, and IMHO they read a bit
> better this way.

I prefer the word "specified" too.  I don't think their
distance makes any difference.  I'd used specified in both places.

>>>    S	Find symbol in Info manual for current programming language
>>
>> With the construction used above for F and K this would
>> read: "Show current programming language manual section for
>> symbol"  If that's too long, perhaps those commands should
>> use this construction with "Find..."
>
> Hmm.  I'm not sure we need the consistency, as the "Show" implies that
> exactly what you're looking for will always be there: The Emacs Manual
> won't go anywhere.

It won't, but what you're looking for may not be in it.

> Whereas "Find" implies that we must first see if there even exists any
> documentation for this particular symbol/identifier/name.

I may be wrong, but I think these commands behave the same
way, the difference is in which manuals are checked.

>>> Misc Help
>>>
>>>    p	Search for packages matching topic
>>>    P	Describe Emacs Lisp package
>>>    e	Show recent messages
>>
>> I'd like to see word the "echo" in here as the mnemonic. Perhaps
>> "Show recent messages from the echo area" or "Show recently
>> echoed messages"
>
> It basically becomes a decision of where to strike the balance between
> brevity and mnemonics.
>
> We have below:
>
>>>    l		Show last 300 input keystrokes (lossage)
>
> So I'd suggest: "Show recent messages (from echo area)"
>
> It reads better (and faster), I think.

I agree.

>>> Help Files
>>>
>>>    C-a	About Emacs
>>>    C-c	Emacs copying permission (GNU General Public License)
>>>    C-d	Debugging GNU Emacs
>>
>> The "GNU" seems unnecessary here, particularly compared to
>> the other lines.
>
> The problem is that the license is the "GNU GPL", while the "General
> Public License" could refer to anything... I think?  Could we just use
> "GNU GPL"?  Perhaps Richard has something to add?

I was just referring to it use in "Debugging GNU Emacs".  I
think that should be "Debugging Emacs".  The "GNU" should stay
in "(GNU General Public License)" and also in the warranty
description. 

> Thanks a lot for these detailed comments.

Thanks for your work on this.

> This is all very subjective, so please bare with me as I'm trying to
> take into account all the comments and work out a coherent whole.

Yes and please take my comments as just one person's opinion.

-- 

Howard

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

>>>>    R	Show given manual
>>>
>>> For w above you say "a given command" maybe these two
>>> should match?
>>
>> Eli suggested "Show specified command", which I think is okay.  I'm not
                       ^^^^^^^^^ specific
>> sure they should match as they are far apart, and IMHO they read a bit
>> better this way.
>
> I prefer the word "specified" too.  I don't think their
> distance makes any difference.  I'd used specified in both places.

OK, I'm going with:

    "Show which key runs a specific command"
    "Show a specific manual"

>>>>    S	Find symbol in Info manual for current programming language

Eli suggested "Show description of symbol in pertinent manual".

> I was just referring to it use in "Debugging GNU Emacs".  I
> think that should be "Debugging Emacs".  The "GNU" should stay
> in "(GNU General Public License)" and also in the warranty
> description.

Oh, right.  Yes, that makes more sense; removed.

Re: Proposal for an improved `help-for-help'

[Howard Melman]

Stefan Kangas <stefan@marxist.se> writes:

> I have attached a rough draft for what an improved version of might look
> like.  It would be great to get some feedback.

I think this is a good improvement.  I'd like to see some of
the help text normalized to be more consistent.  Here's an
attempt at that, though it could us another pass too.


Basic Help

m           Display documentation of current major and minor modes and their commands.
x COMMAND   Display documentation of the command.
k KEYS      Display documentation of the key sequence.
f FUNCTION  Display documentation of the function.
v VARIABLE  Display documentation and value of the variable.
o SYMBOL    Display documentation and value of the function or variable.
c KEYS      Display the command name bound to the key sequence.
b           Display all bindings of commands to keys.
w COMMAND   Display which keys are bound to the command.
.           Display any available local help at point.

Documentation

t           Start the Emacs learn-by-doing tutorial.
r           Show the Emacs manual in Info mode.
F COMMAND   Show the Emacs manual's section for the command.
K KEYS      Show the Emacs manual's section for the command bound to KEYS.
i           Show the Info documentation reader listing all available manuals.
S SYMBOL    Show the section of the relevant Info manual for the symbol.

SEARCHING AND PACKAGES

a PATTERN   Show commands whose name matches the PATTERN (a list of words or a regexp).  See also the `apropos' command.
d PATTERN   Show a list of functions, variables, and other items whose documentation matches the PATTERN (a list of words or a regexp).
P PACKAGE   Describe the given Emacs Lisp package.
p TOPIC     Find packages matching a given topic keyword.

OTHER

e           Go to the *Messages* buffer which logs echo-area messages.
l           Show last 300 input keystrokes (lossage).
C CODING    Describe the given coding system, or RET for current ones.
I METHOD    Describe a specific input method, or RET for current.
L LANG-ENV  Describes a specific language environment, or RET for current.
s           Display contents of current syntax table, plus explanations.

g           Display information about the GNU project.
n           Display news of recent Emacs changes.
h           Display the HELLO file which illustrates various scripts.

C-a         Information about Emacs.
C-c         Emacs copying permission (GNU General Public License).
C-d         Instructions for debugging GNU Emacs.
C-e         External packages and information about Emacs.
C-f         Emacs FAQ.
C-m         How to order printed Emacs manuals.
C-n         News of recent Emacs changes.
C-o         Emacs ordering and distribution information.
C-p         Info about known Emacs problems.
C-s         Search forward \"help window\".
C-t         Emacs TODO list.
C-w         Information on absence of warranty for GNU Emacs."


-- 

Howard

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> I have attached a rough draft for what an improved version of might look
>> like.  It would be great to get some feedback.
>
> I think this is a good improvement.  I'd like to see some of
> the help text normalized to be more consistent.  Here's an
> attempt at that, though it could us another pass too.

Yes, I agree it could use some reformulating.  I will have a look at your
suggestions, thanks!

Re: Proposal for an improved `help-for-help'

[Yuri Khan]

On Sun, 21 Feb 2021 at 19:08, Stefan Kangas <stefan@marxist.se> wrote:

> One of the usability complaints I've heard is that `help-for-help'
> (`C-h C-h') could be better organized.  I also think some colors could
> really help in making it easier to navigate.

There is some discussion going in this thread concerning the order and
sectioning. I’d like to make a few usability suggestions, too.

Is there a reason that help-for-help is page-scrollable with
Space/Backspace and C-v/M-v but not PageUp/PageDown, and
line-scrollable with the mouse wheel but not Up/Down arrow keys? A
newcomer will try those and be surprised by the help buffer silently
disappearing.

Shift+Space should probably also act as “scroll a page back” on
terminals where this key is distinguishable.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> Is there a reason that help-for-help is page-scrollable with
> Space/Backspace and C-v/M-v but not PageUp/PageDown, and
> line-scrollable with the mouse wheel but not Up/Down arrow keys? A
> newcomer will try those and be surprised by the help buffer silently
> disappearing.
>
> Shift+Space should probably also act as “scroll a page back” on
> terminals where this key is distinguishable.

I agree with all your points here.  Fixing the above would be a good
improvement on what we have.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Stefan Kangas <stefan@marxist.se> writes:

> Yuri Khan <yuri.v.khan@gmail.com> writes:
>
>> Is there a reason that help-for-help is page-scrollable with
>> Space/Backspace and C-v/M-v but not PageUp/PageDown, and
>> line-scrollable with the mouse wheel but not Up/Down arrow keys? A
>> newcomer will try those and be surprised by the help buffer silently
>> disappearing.

I have now done this on master.

>> Shift+Space should probably also act as “scroll a page back” on
>> terminals where this key is distinguishable.

Is that a common convention?  I'm testing man and less in xterm, and
they don't scroll up on Shift+Space.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 25.04.2021 18:11, Stefan Kangas wrote:
>>> Shift+Space should probably also act as “scroll a page back” on
>>> terminals where this key is distinguishable.
> Is that a common convention?  I'm testing man and less in xterm, and
> they don't scroll up on Shift+Space.
> 

Perhaps not ubiquitous.

I thought it worked in 'less', but apparently misremembered. Neigher 
backspace nor delete do anything in 'less' either, so it's probably not 
the best comparison.

Works in Firefox and Thunderbird, though.

But PgUp/PgDown work in less too, so supporting them should be higher 
priority.

Re: Proposal for an improved `help-for-help'

[Stefan Kangas]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> Is that a common convention?  I'm testing man and less in xterm, and
>> they don't scroll up on Shift+Space.
>
> Perhaps not ubiquitous.
>
> I thought it worked in 'less', but apparently misremembered. Neigher
> backspace nor delete do anything in 'less' either, so it's probably not
> the best comparison.
>
> Works in Firefox and Thunderbird, though.
>
> But PgUp/PgDown work in less too, so supporting them should be higher
> priority.

We also have in `special-mode-map':

DEL             scroll-down-command
S-SPC           scroll-down-command

So I think it makes sense to add it to help-for-help as well.

Re: Proposal for an improved `help-for-help'

[Dmitry Gutov]

On 22.02.2021 12:01, Yuri Khan wrote:
> Is there a reason that help-for-help is page-scrollable with
> Space/Backspace and C-v/M-v but not PageUp/PageDown, and
> line-scrollable with the mouse wheel but not Up/Down arrow keys? A
> newcomer will try those and be surprised by the help buffer silently
> disappearing.
> 
> Shift+Space should probably also act as “scroll a page back” on
> terminals where this key is distinguishable.

Adding PgUp/PgDown and S-SPC support sound like particularly good 
improvements to me as well.