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

[Stefan Kangas <stefan@marxist.se>]

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