unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Stefan Kangas <stefan@marxist.se>
To: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>
Cc: larsi@gnus.org, 46627@debbugs.gnu.org
Subject: bug#46627: [PATCH] Add new help command 'describe-command'
Date: Sat, 20 Feb 2021 11:10:28 -0600	[thread overview]
Message-ID: <CADwFkmnx3ptrz_+gHxTwJy-0P=Sa5foEDHnKK6yLw97kmmOaEA@mail.gmail.com> (raw)
In-Reply-To: <83eehb17ag.fsf@gnu.org>

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

Eli Zaretskii <eliz@gnu.org> writes:

> The way to wrap it is like this:
>
>   @w{@kbd{C-h f make-vector @key{RET}}}
>
> Is this what you tried?  If so, how did it not work?

Sorry, I misunderstood.  OK, so I've added that, and it works.

I also fixed an incorrect line break in another place by adding @w{..}.

> I'd prefer:
>
>  1. You didn't specify a command's symbol
>  2. Symbol is not a command: %s

Changed in the attached.

>> Should the more technical explanations therefore stay?
>
> If it's 110% impossible to trigger those messages, they can go, of
> course.  The question is: can some completion trickery cause
> completing-read return with a value that is either not a symbol or a
> symbol whose function definition is void?

I'm also worried about third-party code calling in.
Perhaps we should better leave it, as it can't hurt.

>> ->> 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.
>
> Perhaps the text here should be amended not to mention "function".

Hmm.  OTOH, it is kind of nice to read that explanation as the first
thing you'll see is something like:

    (next-line &optional ARG TRY-VSCROLL)

So the user will worry less if she has first seen that explanation,
maybe?

I've attached an updated patch.

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

From 054666f1b3e8e6aa874c5bf1bdd21a70b33ba590 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.  (Bug#46627)
(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    | 43 +++++++++++++++--------------
 etc/NEWS               |  4 +++
 etc/tutorials/TUTORIAL |  6 ++--
 lisp/help-fns.el       | 62 ++++++++++++++++++++++++++++++------------
 lisp/help.el           |  4 ++-
 lisp/menu-bar.el       |  3 ++
 6 files changed, 80 insertions(+), 42 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 81cdeb4be5..90a2ddc809 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 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,31 @@ 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 named @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
+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}).
 
-  @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 @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 @w{@kbd{C-h f make-vector @key{RET}}}.
+Additionally, since all commands are Lisp functions, you can also use
+this command to view the documentation of any command.
 
   If you type @kbd{C-h f @key{RET}}, it describes the function called
 by the innermost Lisp expression in the buffer around point,
@@ -265,7 +268,7 @@ Name Help
 (That name appears as the default while you enter the argument.)  For
 example, if point is located following the text @samp{(make-vector
 (car x)}, the innermost list containing point is the one that starts
-with @samp{(make-vector}, so @kbd{C-h f @key{RET}} describes the
+with @samp{(make-vector}, so @w{@kbd{C-h f @key{RET}}} describes the
 function @code{make-vector}.
 
   @kbd{C-h f} is also useful just to verify that you spelled a
diff --git a/etc/NEWS b/etc/NEWS
index c4f4c1d9d8..fb702e6862 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -864,6 +864,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..a14df9013a 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -174,26 +174,47 @@ 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)))
+    ;; These error messages are intended to be less technical for the
+    ;; `describe-command' case, as they are directed at users that are
+    ;; not necessarily ELisp programmers.
+    (unless (and fn (symbolp fn))
+      (user-error (if want-command
+                      "You didn't specify a command's symbol"
+                    "You didn't specify a function symbol")))
+    (unless (or (fboundp fn) (get fn 'function-documentation))
+      (user-error (if want-command
+                      "Symbol is not a command: %s"
+                    "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 +244,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


  reply	other threads:[~2021-02-20 17:10 UTC|newest]

Thread overview: 86+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-02-19  1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
2021-02-19  8:42 ` Eli Zaretskii
2021-02-19 17:42   ` Stefan Kangas
2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
2021-02-20  3:25       ` Stefan Kangas
2021-02-20  4:25         ` Drew Adams
2021-02-20  8:20           ` Eli Zaretskii
2021-02-20  7:44         ` Eli Zaretskii
2021-02-19 20:05     ` Eli Zaretskii
2021-02-20  4:10       ` Stefan Kangas
2021-02-20  8:18         ` Eli Zaretskii
2021-02-20 17:10           ` Stefan Kangas [this message]
2021-02-21 13:08             ` Lars Ingebrigtsen
2021-02-22 15:58             ` Eli Zaretskii
2021-04-28 13:58               ` Stefan Kangas
2021-04-28 14:17                 ` Stefan Kangas
2021-05-02 13:14                 ` Stefan Kangas
2021-02-20 12:56     ` Lars Ingebrigtsen
2021-02-20 12:59       ` Eli Zaretskii
2021-02-20 16:16         ` Eli Zaretskii
2021-02-20 14:04       ` Stefan Kangas
2021-02-20 16:06     ` Richard Stallman
2021-02-20 16:09       ` Eli Zaretskii
2021-02-20 20:06         ` bug#46627: [External] : " Drew Adams
2021-02-20 20:17           ` Eli Zaretskii
2021-02-20 20:54             ` Drew Adams
2021-02-20 16:39       ` Stefan Kangas
2021-02-20 16:49         ` Eli Zaretskii
2021-02-20 20:35           ` bug#46627: [External] : " Drew Adams
2021-02-20 20:46             ` Eli Zaretskii
2021-02-20 21:16               ` Drew Adams
2021-02-21 15:07                 ` Eli Zaretskii
2021-02-21 17:55                   ` Drew Adams
2021-02-21 18:11                     ` Eli Zaretskii
2021-02-21 18:30                       ` Drew Adams
2021-02-26 21:34             ` Drew Adams
2021-02-27  8:04               ` Eli Zaretskii
2021-02-27 17:46                 ` Drew Adams
2021-02-21  6:19         ` Richard Stallman
2021-02-21  7:18           ` Stefan Kangas
2021-02-21 15:27             ` Eli Zaretskii
2021-02-21 16:39               ` Howard Melman
2021-02-21 18:01                 ` bug#46627: [External] : " Drew Adams
2021-02-21 17:01               ` Stefan Kangas
2021-02-21 17:36                 ` Eli Zaretskii
2021-02-21 18:02                   ` Stefan Kangas
2021-02-21 18:21                     ` Eli Zaretskii
2021-02-21 19:57                       ` Dmitry Gutov
2021-02-21 20:13                         ` Eli Zaretskii
2021-02-21 23:46                           ` Dmitry Gutov
2021-02-22 15:18                             ` Eli Zaretskii
2021-02-27 20:38                               ` Dmitry Gutov
2021-02-28 17:27                                 ` Eli Zaretskii
2021-02-28 21:40                                   ` Dmitry Gutov
2021-03-01  6:05                                     ` Eli Zaretskii
2021-03-02  1:40                                       ` Dmitry Gutov
2021-03-02  5:31                                         ` Eli Zaretskii
2021-03-02 12:55                                           ` Dmitry Gutov
2021-03-02 13:47                                             ` Eli Zaretskii
2021-02-21 17:57               ` bug#46627: [External] : " Drew Adams
2021-02-21 17:33             ` Drew Adams
2021-02-21 13:06           ` Lars Ingebrigtsen
2021-02-21  6:27         ` Richard Stallman
2021-02-21  6:10     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-19 13:12 ` Lars Ingebrigtsen
2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
2021-02-19 18:43     ` Eli Zaretskii
2021-02-21  6:18     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-20  6:56 ` Richard Stallman
2021-02-20  7:14   ` Stefan Kangas
2021-02-21  6:19     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-21  7:17       ` Stefan Kangas
2021-02-22  6:23         ` Richard Stallman
2021-02-24  3:28           ` Stefan Kangas
2021-02-27 18:58           ` Dmitry Gutov
2021-03-01  5:18             ` Richard Stallman
2021-03-01 16:13               ` bug#46627: [External] : " Drew Adams
2021-03-02  6:29                 ` Richard Stallman
2021-03-02  6:50                   ` Eli Zaretskii
2021-03-03  5:55                     ` Richard Stallman
2021-03-03 15:26                       ` Drew Adams
2021-03-03 16:14                         ` Eli Zaretskii
2021-03-02 16:52                   ` Drew Adams

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CADwFkmnx3ptrz_+gHxTwJy-0P=Sa5foEDHnKK6yLw97kmmOaEA@mail.gmail.com' \
    --to=stefan@marxist.se \
    --cc=46627@debbugs.gnu.org \
    --cc=eliz@gnu.org \
    --cc=larsi@gnus.org \
    --cc=monnier@iro.umontreal.ca \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).