bug#46627: [PATCH] Add new help command 'describe-command'

[Stefan Kangas <stefan@marxist.se>]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> As recently discussed on emacs-devel, it could be useful to have a
>> command `describe-command' to search for commands.  Please find attached
>> a patch that adds such a command.
>
> Thanks, but please also include the necessary updates for the user
> manual, and perhaps also the tutorial.  The Help menu should probably
> also have this.

OK, I have written the documentation, updated the help screen and
tutorial, and added a menu entry.  It would be good if someone could
look it over and see that it reads okay and makes sense.

The way I add it in the documentation treats it as more basic than
`C-h f'.  That is, the proposed text first describes how to find
documentation for commands, and only then describes how to find
documentation for any Lisp function.  It is the most reasonable way to
do it here, I think; this is after all the "user" manual and not the
"Elisp" manual.

I also went ahead and added the keybinding `C-h x'.  It seemed strange
to not have one for a basic help command such as this.  It would of
course have been less work to just tack it on the existing
documentation, but I took some care here to rewrite it slightly in a way
that I believe will be better in the long-run.

The exercise of documenting this, and thinking about how this new
command fits in, has made me realize that while having a keybinding for
this is useful, and `C-h x' is the best free one we have, putting it
there and not on `C-h c' is rather unfortunate.  (The mnemonic `M-x'
feels forced and artificial.)

It really is more than a little tempting to propose replacing the
long-standing keybinding for `describe-key-briefly' with the new
`describe-command'.  But I am well aware of how hard it is to get
consensus around such changes, especially with a new command.  (And once
it is no longer new, it is of course even harder to get it
changed... and around it goes.)

So, barring that, we could perhaps turn the entire argument around 180
degrees: precisely because the keybinding is so bad, it should *not* be
recommended in the TUTORIAL above `C-h f', and the right thing is
consequently not to give it a strong spotlight but to simply have it
"tacked on", like the after-thought it is, right after our trusty old
`C-h f'.  And perhaps we should not give it a default keybinding either,
if there is to be any hope for it to push out `describe-key-briefly' in
the future...

So yeah, the patch is attached, but I'm still rather undecided on what's
best here.

Thoughts?

[-- Attachment #2: 0001-Add-new-help-command-describe-command.patch --]
[-- Type: text/x-diff, Size: 10964 bytes --]

From 4e36d9e2f26d6d490b037b9f5ec7d08402479c08 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 19 Feb 2021 18:21:23 +0100
Subject: [PATCH] Add new help command 'describe-command'

* lisp/help-fns.el (describe-command): New command.
(help-fns--describe-function-or-command-prompt): New helper
function to prompt for a function or function.
(describe-function): Use above new helper function.

* lisp/help.el (help-map): Bind above new command to `C-h x'.
(help-for-help-internal): Add this new binding to the help summary.
* lisp/menu-bar.el (menu-bar-describe-menu): Add the new command to
the help menu.

* doc/emacs/help.texi (Help Summary, Name Help): Document
'describe-function', and update documentation on 'describe-command'.
* etc/tutorials/TUTORIAL: Change reference from 'describe-function' to
'describe-command'.
---
 doc/emacs/help.texi    | 44 ++++++++++++++++++----------------
 etc/NEWS               |  4 ++++
 etc/tutorials/TUTORIAL |  6 ++---
 lisp/help-fns.el       | 54 ++++++++++++++++++++++++++++--------------
 lisp/help.el           |  4 +++-
 lisp/menu-bar.el       |  3 +++
 6 files changed, 73 insertions(+), 42 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 81cdeb4be5..fd24826b86 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -107,8 +107,8 @@ Help Summary
 (@code{view-echo-area-messages}).  @xref{Misc Help}.
 @item C-h f @var{function} @key{RET}
 Display documentation on the Lisp function named @var{function}
-(@code{describe-function}).  Since commands are Lisp functions,
-this works for commands too.  @xref{Name Help}.
+(@code{describe-function}).  Since commands are Lisp functions, this
+works for commands too, but you can also use @code{C-h x}.  @xref{Name Help}.
 @item C-h h
 Display the @file{HELLO} file, which shows examples of various character
 sets.
@@ -154,6 +154,9 @@ Help Summary
 @item C-h w @var{command} @key{RET}
 Show which keys run the command named @var{command} (@code{where-is}).
 @xref{Key Help}.
+@item C-h x @var{command} @key{RET}
+Display documentation on the command named @var{command}
+(@code{describe-command}).  @xref{Name Help}.
 @item C-h C @var{coding} @key{RET}
 Describe the coding system @var{coding}
 (@code{describe-coding-system}).  @xref{Coding Systems}.
@@ -233,31 +236,32 @@ Key Help
 @node Name Help
 @section Help by Command or Variable Name
 
-@kindex C-h f
-@findex describe-function
-  @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
-displays the documentation of Lisp function @var{function}, in a
-window.  Since commands are Lisp functions, you can use this method to
-view the documentation of any command whose name you know.  For
-example,
+@kindex C-h x
+@findex describe-command
+  @kbd{C-h x @var{command} @key{RET}} (@code{describe-command})
+displays the documentation of the command @var{command}, in a
+window.  For example,
 
 @example
-C-h f auto-fill-mode @key{RET}
+C-h x auto-fill-mode @key{RET}
 @end example
 
 @noindent
-displays the documentation of @code{auto-fill-mode}.  This is the only
-way to get the documentation of a command that is not bound to any key
-(one which you would normally run using @kbd{M-x}).
+displays the documentation of @code{auto-fill-mode}.  This is how you
+would get the documentation of a command that is not bound to any key
+(one which you would normally run using @kbd{M-x}).  Since all
+commands are Lisp functions, you can also find its documentation using
+@code{describe-function}.
 
-  @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp
-program.  For example, if you have just written the expression
+@kindex C-h f
+@findex describe-function
+  @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
+displays the documentation of Lisp function @var{function}.  This
+command is intended for Lisp functions that you use in a Lisp program.
+For example, if you have just written the expression
 @code{(make-vector len)} and want to check that you are using
-@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
-Because @kbd{C-h f} allows all function names, not just command names,
-you may find that some of your favorite completion abbreviations that
-work in @kbd{M-x} don't work in @kbd{C-h f}.  An abbreviation that is
-unique among command names may not be unique among all function names.
+@code{make-vector} properly, type @kbd{C-h f make-vector
+@key{RET}}.
 
   If you type @kbd{C-h f @key{RET}}, it describes the function called
 by the innermost Lisp expression in the buffer around point,
diff --git a/etc/NEWS b/etc/NEWS
index 7665d4740f..6bab47f62c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -857,6 +857,10 @@ skipped.
 ---
 *** 'g' ('revert-buffer') in 'help-mode' no longer requires confirmation.
 
+*** New command 'describe-command' shows help for a command.
+This can be used instead of 'describe-function' that describes any
+function.  It is globally bound to `C-h x'.
+
 +++
 *** New command 'describe-keymap' describes keybindings in a keymap.
 
diff --git a/etc/tutorials/TUTORIAL b/etc/tutorials/TUTORIAL
index 6194e55ea3..dcdb61f23e 100644
--- a/etc/tutorials/TUTORIAL
+++ b/etc/tutorials/TUTORIAL
@@ -1038,10 +1038,10 @@ then type C-x 1.
 
 Here are some other useful C-h options:
 
-   C-h f	Describe a function.  You type in the name of the
-		function.
+   C-h x	Describe a command.  You type in the name of the
+		command.
 
->> Try typing C-h f previous-line <Return>.
+>> Try typing C-h x previous-line <Return>.
    This displays all the information Emacs has about the
    function which implements the C-p command.
 
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index ceb6bc0901..3354accd67 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -174,26 +174,39 @@ describe-function-orig-buffer
 Functions on `help-fns-describe-function-functions' can use this
 to get buffer-local values.")
 
+(defun help-fns--describe-function-or-command-prompt (&optional want-command)
+  "Prompt for a function from `describe-function' or `describe-command'.
+If optional argument WANT-COMMAND is non-nil, prompt for an
+interactive command."
+  (let* ((fn (if want-command
+                 (caar command-history)
+               (function-called-at-point)))
+         (prompt (format-prompt (if want-command
+                                    "Describe command"
+                                  "Describe function")
+                                fn))
+         (enable-recursive-minibuffers t)
+         (val (completing-read
+               prompt
+               #'help--symbol-completion-table
+               (lambda (f) (if want-command
+                          (commandp f)
+                        (or (fboundp f) (get f 'function-documentation))))
+               t nil nil
+               (and fn (symbol-name fn)))))
+    (unless (equal val "")
+      (setq fn (intern val)))
+    (unless (and fn (symbolp fn))
+      (user-error "You didn't specify a function symbol"))
+    (unless (or (fboundp fn) (get fn 'function-documentation))
+      (user-error "Symbol's function definition is void: %s" fn))
+    (list fn)))
+
 ;;;###autoload
 (defun describe-function (function)
   "Display the full documentation of FUNCTION (a symbol).
 When called from lisp, FUNCTION may also be a function object."
-  (interactive
-   (let* ((fn (function-called-at-point))
-          (enable-recursive-minibuffers t)
-          (val (completing-read
-                (format-prompt "Describe function" fn)
-                #'help--symbol-completion-table
-                (lambda (f) (or (fboundp f) (get f 'function-documentation)))
-                t nil nil
-                (and fn (symbol-name fn)))))
-     (unless (equal val "")
-       (setq fn (intern val)))
-     (unless (and fn (symbolp fn))
-       (user-error "You didn't specify a function symbol"))
-     (unless (or (fboundp fn) (get fn 'function-documentation))
-       (user-error "Symbol's function definition is void: %s" fn))
-     (list fn)))
+  (interactive (help-fns--describe-function-or-command-prompt))
 
   ;; We save describe-function-orig-buffer on the help xref stack, so
   ;; it is restored by the back/forward buttons.  'help-buffer'
@@ -223,9 +236,14 @@ describe-function
         (describe-function-1 function)
         (with-current-buffer standard-output
           ;; Return the text we displayed.
-          (buffer-string))))
-    ))
+          (buffer-string))))))
 
+;;;###autoload
+(defun describe-command (command)
+  "Display the full documentation of COMMAND (a symbol).
+When called from lisp, COMMAND may also be a function object."
+  (interactive (help-fns--describe-function-or-command-prompt 'is-command))
+  (describe-function command))
 
 ;; Could be this, if we make symbol-file do the work below.
 ;; (defun help-C-file-name (subr-or-var kind)
diff --git a/lisp/help.el b/lisp/help.el
index 084e941549..daeca2b406 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -106,6 +106,7 @@ help-map
     (define-key map "t" 'help-with-tutorial)
     (define-key map "w" 'where-is)
     (define-key map "v" 'describe-variable)
+    (define-key map "x" 'describe-command)
     (define-key map "q" 'help-quit)
     map)
   "Keymap for characters following the Help key.")
@@ -192,7 +193,7 @@ 'help
 (defalias 'help-for-help 'help-for-help-internal)
 ;; It can't find this, but nobody will look.
 (make-help-screen help-for-help-internal
-  (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvw.] C-[cdefmnoptw] or ?")
+  (purecopy "Type a help option: [abcCdefFgiIkKlLmnprstvwx.] 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
   ;; be moved to the DOC file anyway: no need for purecopying it).
@@ -231,6 +232,7 @@ 'help-for-help
 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).
+x COMMAND   Display documentation for the given command.
 .           Display any available local help at point in the echo area.
 
 C-a         Information about Emacs.
diff --git a/lisp/menu-bar.el b/lisp/menu-bar.el
index 133df65cbc..0e634cc4a0 100644
--- a/lisp/menu-bar.el
+++ b/lisp/menu-bar.el
@@ -1882,6 +1882,9 @@ menu-bar-describe-menu
     (bindings--define-key menu [describe-function]
       '(menu-item "Describe Function..." describe-function
                   :help "Display documentation of function/command"))
+    (bindings--define-key menu [describe-command]
+      '(menu-item "Describe Command..." describe-command
+                  :help "Display documentation of command"))
     (bindings--define-key menu [shortdoc-display-group]
       '(menu-item "Function Group Overview..." shortdoc-display-group
                   :help "Display a function overview for a specific topic"))
-- 
2.30.0