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>
Cc: larsi@gnus.org, 46627@debbugs.gnu.org
Subject: bug#46627: [PATCH] Add new help command 'describe-command'
Date: Fri, 19 Feb 2021 22:10:58 -0600	[thread overview]
Message-ID: <CADwFkmmfiXSrTEBYvdU5smEXeDMMM9+W7ryrXD5TCPvNc3CvRg@mail.gmail.com> (raw)
In-Reply-To: <83pn0v257d.fsf@gnu.org>

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

Eli Zaretskii <eliz@gnu.org> writes:

> Please remember this when we discuss use of functions in user-level
> features, such as values for user options.

Yes, I actually mostly agree with you on that point already.

Thank you for your very helpful comments.  I tried fixing them in the
attached patch.

>> +@code{make-vector} properly, type @kbd{C-h f make-vector
>> +@key{RET}}.
>
> When a long text in |@kbd (or any other Texinfo markup) is near a
> line's end, it is better to wrap it in @w{..}, so that it won't be
> broken in half by the end of line.

I tried wrapping it in @w{..} but I wasn't able to get it to avoid line
breaks.  Perhaps I'm doing something wrong, but I tried fixing these
cases manually for now.

>> +    (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))
>
> These messages say "function" regardless of whether the user typed
> "C-h x" or "C-h f".  Is that optimal?

Hmm, good point.  I made an attempt at making this more user-friendly
and less technical in the attached patch by introducing two new
messages:

1. "You didn't specify a valid command name"
2. "No such command: %s"

WDYT?

Hmm, but now that I'm testing this, I'm not sure how to arrive at these
messages from `C-h x'.  I just get a "no match" message for anything
that is not a valid command name.  So can you reach this only from Lisp
or something?  Should the more technical explanations therefore stay?

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

From 6a570beb34d22f428f92bd1899dec55b63940e8b 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    | 47 +++++++++++++++++---------------
 etc/NEWS               |  4 +++
 etc/tutorials/TUTORIAL |  6 ++--
 lisp/help-fns.el       | 62 ++++++++++++++++++++++++++++++------------
 lisp/help.el           |  4 ++-
 lisp/menu-bar.el       |  3 ++
 6 files changed, 82 insertions(+), 44 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 81cdeb4be5..1d0a65b8b1 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,40 +236,40 @@ 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.
+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,
 @emph{provided} that function name is a valid, defined Lisp function.
 (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
-function @code{make-vector}.
+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 function @code{make-vector}.
 
   @kbd{C-h f} is also useful just to verify that you spelled a
 function name correctly.  If the minibuffer prompt for @kbd{C-h f}
diff --git a/etc/NEWS b/etc/NEWS
index ee8a68a259..9f84fc6c72 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..043c989946 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 valid command name"
+                    "You didn't specify a function symbol")))
+    (unless (or (fboundp fn) (get fn 'function-documentation))
+      (user-error (if want-command
+                      "No such 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  4: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 [this message]
2021-02-20  8:18         ` Eli Zaretskii
2021-02-20 17:10           ` Stefan Kangas
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=CADwFkmmfiXSrTEBYvdU5smEXeDMMM9+W7ryrXD5TCPvNc3CvRg@mail.gmail.com \
    --to=stefan@marxist.se \
    --cc=46627@debbugs.gnu.org \
    --cc=eliz@gnu.org \
    --cc=larsi@gnus.org \
    /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).