unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Proposal for an improved `help-for-help'
@ 2021-02-21 12:06 Stefan Kangas
  2021-02-21 16:46 ` [External] : " Drew Adams
                   ` (4 more replies)
  0 siblings, 5 replies; 188+ messages in thread
From: Stefan Kangas @ 2021-02-21 12:06 UTC (permalink / raw)
  To: emacs-devel

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


^ permalink raw reply related	[flat|nested] 188+ messages in thread

end of thread, other threads:[~2021-05-02 18:57 UTC | newest]

Thread overview: 188+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-21 12:06 Proposal for an improved `help-for-help' Stefan Kangas
2021-02-21 16:46 ` [External] : " Drew Adams
2021-02-21 17:31   ` Stefan Kangas
2021-02-21 18:17     ` Drew Adams
2021-02-21 17:42 ` Lars Ingebrigtsen
2021-02-21 18:18   ` [External] : " Drew Adams
2021-02-21 19:49   ` Stefan Kangas
2021-02-24  1:40   ` Consistent face for keys in *Help* and `substitute-command-keys' Stefan Kangas
2021-02-24  2:24     ` [External] : " Drew Adams
2021-02-24  4:44       ` Stefan Kangas
2021-02-24 22:01         ` Drew Adams
2021-02-25  1:25           ` Stefan Kangas
2021-02-25  6:43             ` Drew Adams
2021-02-25 15:06               ` Eli Zaretskii
2021-02-25 16:22               ` Stefan Kangas
2021-02-24 14:00     ` Basil L. Contovounesios
2021-02-24 16:35       ` Stefan Kangas
2021-02-24 19:09         ` Basil L. Contovounesios
2021-02-25  2:11           ` Stefan Kangas
2021-02-24 14:29     ` Lars Ingebrigtsen
2021-02-24 16:46     ` Eli Zaretskii
2021-02-25  2:26       ` Stefan Kangas
2021-02-25 14:28         ` Eli Zaretskii
2021-02-25 16:45           ` Stefan Kangas
2021-02-25 18:25             ` Eli Zaretskii
2021-02-25 18:48               ` Stefan Kangas
2021-02-25 19:11                 ` Eli Zaretskii
2021-02-25 19:47                   ` Stefan Kangas
2021-02-25 20:32                     ` Eli Zaretskii
2021-03-04  6:24                       ` Stefan Kangas
2021-03-04 14:00                         ` Eli Zaretskii
2021-03-05 16:18                           ` Stefan Kangas
2021-03-05 17:07                             ` [External] : " Drew Adams
2021-03-05 17:58                               ` Stefan Kangas
2021-03-06 16:44                                 ` Drew Adams
2021-03-06 17:04                                   ` Stefan Kangas
2021-03-06 17:39                                     ` Drew Adams
2021-03-05 18:58                             ` Eli Zaretskii
2021-03-05 19:28                               ` Stefan Kangas
2021-03-05 20:15                                 ` Eli Zaretskii
2021-03-05 20:39                                   ` Stefan Kangas
2021-03-05 20:52                                     ` Eli Zaretskii
2021-03-05 21:43                                       ` Stefan Kangas
2021-03-06  7:33                                         ` Eli Zaretskii
2021-03-06 16:25                                           ` Stefan Kangas
2021-03-06 17:32                                             ` Stefan Kangas
2021-03-06 18:28                                               ` Eli Zaretskii
2021-03-07  3:03                                                 ` Stefan Kangas
2021-03-07  6:45                                                   ` Eli Zaretskii
2021-03-07  7:26                                                     ` Stefan Kangas
2021-03-07  7:42                                                       ` Eli Zaretskii
2021-03-08  9:17                                               ` Juri Linkov
2021-03-08 11:10                                                 ` Stefan Kangas
2021-03-08 17:43                                                   ` Juri Linkov
2021-03-10  1:38                                                     ` Stefan Kangas
2021-03-10 17:16                                                       ` Juri Linkov
2021-03-10 19:35                                                         ` Stefan Kangas
2021-03-10 19:50                                                           ` Juri Linkov
2021-03-10 19:59                                                             ` Eli Zaretskii
2021-03-11  0:46                                                               ` Stefan Kangas
2021-03-11  3:09                                                                 ` Stefan Monnier
2021-03-11  6:25                                                                   ` Eli Zaretskii
2021-03-11 13:25                                                                     ` Stefan Monnier
2021-03-11 13:59                                                                       ` Eli Zaretskii
2021-03-13 14:11                                                                   ` Stefan Kangas
2021-03-11  6:05                                                                 ` Eli Zaretskii
2021-03-13 14:27                                                                   ` Stefan Kangas
2021-03-13 15:16                                                                     ` Eli Zaretskii
2021-03-13 15:59                                                                       ` Stefan Kangas
2021-03-11  0:45                                                             ` Stefan Kangas
2021-03-15  9:19                                                               ` Juri Linkov
2021-03-16  2:37                                                                 ` Stefan Kangas
2021-03-16 23:20                                                                 ` Dmitry Gutov
2021-03-08 15:39                                                 ` [External] : " Drew Adams
2021-03-08 16:40                                                   ` Stefan Kangas
2021-03-08 17:43                                                     ` Juri Linkov
2021-03-09  7:38                                                       ` Stefan Kangas
2021-03-09  9:05                                                         ` Juri Linkov
2021-02-25 19:14                 ` Drew Adams
2021-02-25 19:44             ` martin rudalics
2021-02-24 16:51     ` Eli Zaretskii
2021-02-25  1:56       ` Stefan Kangas
2021-02-25 14:24         ` Eli Zaretskii
2021-02-21 17:45 ` Proposal for an improved `help-for-help' Eli Zaretskii
2021-02-21 18:20   ` [External] : " Drew Adams
2021-02-21 18:48   ` Stefan Kangas
2021-02-21 19:19     ` Eli Zaretskii
2021-02-21 20:04       ` Stefan Kangas
2021-02-21 20:16         ` Eli Zaretskii
2021-02-21 23:27           ` Stefan Kangas
2021-02-22 16:12             ` Eli Zaretskii
2021-03-13 16:26     ` Stefan Kangas
2021-03-14  2:37       ` [External] : " Drew Adams
2021-03-14 23:05       ` Drew Adams
2021-03-14 23:53         ` Stefan Kangas
2021-03-15  1:54           ` Drew Adams
2021-04-07 15:18       ` Stefan Kangas
2021-04-07 16:10         ` Eli Zaretskii
2021-04-07 22:54           ` Howard Melman
2021-04-08  7:15             ` Eli Zaretskii
2021-04-08 12:57               ` Stefan Kangas
2021-04-08 13:35           ` Stefan Kangas
2021-04-08 13:50             ` Eli Zaretskii
2021-04-08 15:27               ` Stefan Kangas
2021-04-08 15:34                 ` Eli Zaretskii
2021-04-08 17:16                   ` Howard Melman
2021-04-08 22:52                   ` Stefan Kangas
2021-04-09  6:23                     ` Eli Zaretskii
2021-04-08 14:08             ` Alan Mackenzie
2021-04-08 14:50               ` Dmitry Gutov
2021-04-08 15:02                 ` Alan Mackenzie
2021-04-08 15:15                   ` Eli Zaretskii
2021-04-08 15:45                     ` Alan Mackenzie
2021-04-08 15:51                       ` Eli Zaretskii
2021-04-08 17:55             ` Howard Melman
2021-04-09 15:42               ` Stefan Kangas
2021-04-08 18:48             ` Gregory Heytings
2021-04-08 23:23               ` Stefan Kangas
2021-04-08 23:35                 ` Gregory Heytings
2021-04-08 23:41                   ` Howard Melman
2021-04-07 16:42         ` [External] : " Drew Adams
2021-04-07 18:33         ` Gregory Heytings
2021-04-07 19:50           ` Gregory Heytings
2021-04-07 22:56           ` Stefan Kangas
2021-04-07 23:26             ` Gregory Heytings
2021-04-08 12:42               ` Stefan Kangas
2021-04-07 19:55         ` Juri Linkov
2021-04-24 13:21         ` Stefan Kangas
2021-04-24 13:27           ` Eli Zaretskii
2021-04-24 16:44           ` Dmitry Gutov
2021-04-24 23:48             ` Stefan Kangas
2021-04-25  7:26               ` Eli Zaretskii
2021-04-25  9:30                 ` Stefan Kangas
2021-04-25 10:25                   ` Eli Zaretskii
2021-04-25 11:49                     ` Stefan Kangas
2021-04-25 12:14                       ` Eli Zaretskii
2021-04-25 16:26                     ` [External] : " Drew Adams
2021-04-25 10:20                 ` Dmitry Gutov
2021-04-25 10:38                   ` Eli Zaretskii
2021-04-25 10:46                     ` Eli Zaretskii
2021-04-25 11:23                     ` Dmitry Gutov
2021-04-25 15:18                       ` Stefan Kangas
2021-04-25 15:28                         ` Dmitry Gutov
2021-04-30 17:39                           ` Stefan Kangas
2021-04-30 20:02                             ` Dmitry Gutov
2021-04-30 20:36                               ` Stefan Monnier
2021-04-30 22:09                                 ` Dmitry Gutov
2021-05-02 10:23                               ` Stefan Kangas
2021-05-02 18:57                                 ` Dmitry Gutov
2021-04-30 17:34                         ` Stefan Kangas
2021-04-25 12:47                   ` Gregory Heytings
2021-04-25 13:05                     ` Eli Zaretskii
2021-04-25 13:09                       ` Eli Zaretskii
2021-04-25 16:22                         ` [External] : " Drew Adams
2021-04-25 16:30                           ` Eli Zaretskii
2021-04-25 13:16                       ` Gregory Heytings
2021-04-25 13:24                         ` Eli Zaretskii
2021-04-25 13:32                           ` Gregory Heytings
2021-04-25 13:44                             ` Eli Zaretskii
2021-04-25 13:58                           ` Dmitry Gutov
2021-04-25 11:12               ` Dmitry Gutov
2021-04-25 15:47               ` DEL vs Backspace (was: Proposal for an improved `help-for-help') Stefan Monnier
2021-04-25 16:49                 ` DEL vs Backspace Lars Ingebrigtsen
2021-04-25 17:25                   ` Stefan Monnier
2021-04-25 17:50                     ` Dmitry Gutov
2021-04-26  0:45                     ` Stefan Kangas
2021-04-26 11:45                       ` Eli Zaretskii
2021-04-26 11:48                         ` Dmitry Gutov
2021-04-26  4:41                   ` Richard Stallman
2021-04-27 20:56               ` Proposal for an improved `help-for-help' Stefan Kangas
2021-04-27 23:15                 ` Dmitry Gutov
2021-04-24 17:18           ` Gregory Heytings
2021-04-24 20:32             ` Juri Linkov
2021-04-25 10:00             ` Stefan Kangas
2021-04-07 17:56       ` Howard Melman
2021-04-07 18:21         ` John Yates
2021-04-07 22:56           ` Stefan Kangas
2021-04-07 22:41         ` Stefan Kangas
2021-04-07 23:15           ` Howard Melman
2021-04-08 12:57             ` Stefan Kangas
2021-02-21 19:27 ` Howard Melman
2021-02-22 15:25   ` Stefan Kangas
2021-02-22 10:01 ` Yuri Khan
2021-02-22 15:25   ` Stefan Kangas
2021-04-25 15:11     ` Stefan Kangas
2021-04-25 15:34       ` Dmitry Gutov
2021-04-25 18:43         ` Stefan Kangas
2021-04-25 14:06   ` Dmitry Gutov

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).