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

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

[Stefan Kangas]

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

Severity: wishlist

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.

I don't know if we should add a key binding, since the most obvious
place to put it, `C-h c', is unfortunately already taken.  Perhaps
`C-h x' would make some sense in analogy with `M-x'.  (Or perhaps it is
worth moving `describe-key-briefly'...)  So I solved it here by not
adding any key at all, for now.

Thoughts?

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

From ed897d0d75465c6e5c37c4ba0c5a1716d86250ca Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefan@marxist.se>
Date: Fri, 19 Feb 2021 01:48:55 +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.
---
 etc/NEWS         |  4 ++++
 lisp/help-fns.el | 54 ++++++++++++++++++++++++++++++++----------------
 2 files changed, 40 insertions(+), 18 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 7665d4740f..269e760c5b 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.
+
 +++
 *** New command 'describe-keymap' describes keybindings in a keymap.
 
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)
-- 
2.30.0

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 18 Feb 2021 17:06:16 -0800
> 
> 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.

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

[Stefan Kangas]

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

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

[Drew Adams]

> 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.)

You don't know if you don't try.  Why not pose the
question in emacs-devel?

> So, barring that, 

Why bar it, without trying?  Just posing the question
should immediately let you know whether there is lots
of opposition (in emacs-devel, at least).  If there
isn't, that's not proof that there won't be opposition
in the wider world, of course.  But if there's lots of
opposition at least you'll feel better about binding
it to `C-h x'.  If posed, the alternative should be
mentioned, including the binding of new key `C-h x'.

> I'm still rather undecided on what's best here.
> Thoughts?

IMO, this should be combined with the other changes
I mentioned in emacs-devel:

1. Add `describe-option', and bind it to, e.g., `C-h o'.
2. Change `describe-function' and `describe-variable',
   so that, with a prefix arg, they do `describe-command'
   and `describe-option'.

(In terms of doc, #2 lessens the need to advertise
those new commands.)

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

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> So, barring that,
>
> Why bar it, without trying?  Just posing the question
> should immediately let you know whether there is lots
> of opposition (in emacs-devel, at least).  If there
> isn't, that's not proof that there won't be opposition
> in the wider world, of course.  But if there's lots of
> opposition at least you'll feel better about binding
> it to `C-h x'.  If posed, the alternative should be
> mentioned, including the binding of new key `C-h x'.

Well, sure.  Thanks for your support.  But I don't think I will be able
to muster the energy for another controversial thread at this point.

(And Eli has expressed strong opposition to the idea already.  We should
probably avoid directing the attention of the project to an idea with
low chances of success.)

Perhaps we can all just learn to like `C-h x'.  It's not too bad; it's
just ugly and hard to remember.  But OTOH, we already have plenty of
keybindings like that -- it's not the end of the world.

BTW, maybe `C-h x' is even easier for a new user to remember soon after
learning `M-x'.  Maybe users don't even think of "commands" but in terms
of "which key does what"?  So I don't know... maybe it's okay.

The big upside is that it does save us from having to do a breaking
change.  Even if that breaking change is IMHO very small, and will
probably be seen like an improvement by most, it might be upsetting to a
subset of users.

>> I'm still rather undecided on what's best here.
>> Thoughts?
>
> IMO, this should be combined with the other changes
> I mentioned in emacs-devel:
>
> 1. Add `describe-option', and bind it to, e.g., `C-h o'.
> 2. Change `describe-function' and `describe-variable',
>    so that, with a prefix arg, they do `describe-command'
>    and `describe-option'.
>
> (In terms of doc, #2 lessens the need to advertise
> those new commands.)

Good ideas.  I think `describe-option' is worth thinking about.
As for putting it `C-h o', I'm not sure such a breaking change would be
worth it: `describe-option' would be less important than
`describe-command', and `describe-symbol' is more important than
`describe-key-briefly'.

I see your point regarding #2, but thinking about it a bit I think it is
preferable to have an easier keybinding than `C-u C-h f' for commands.
And if we have `describe-command' on `C-h x', perhaps the prefix
argument to `describe-function' is just redundant?

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

[Drew Adams]

> > 2. Change `describe-function' and `describe-variable',
> >    so that, with a prefix arg, they do `describe-command'
> >    and `describe-option'.
> >    (In terms of doc, #2 lessens the need to advertise
> >    those new commands.)
> 
> I see your point regarding #2, but thinking about it a bit I think it
> is preferable to have an easier keybinding than `C-u C-h f' for commands.
> And if we have `describe-command' on `C-h x', perhaps the prefix
> argument to `describe-function' is just redundant?

It's not either/or.  It costs little to add the
prefix-arg behavior, even if you add the option
and command commands.  And it can mean one less
thing for some users to remember (or give them
an extra key to rebind).  Other users may find
it easier to remember two than one, and with
its own binding `describe-command' is more
discoverable than is `C-u C-h f'.

That's similar to what we do for some apropos
commands.  E.g. `apropos-user-option' compared
with `apropos-variable' with a prefix arg; and
`apropos-command' with and without a prefix arg.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: Lars Ingebrigtsen <larsi@gnus.org>,
>         "46627@debbugs.gnu.org"
> 	<46627@debbugs.gnu.org>
> Date: Sat, 20 Feb 2021 04:25:09 +0000
> 
> > I see your point regarding #2, but thinking about it a bit I think it
> > is preferable to have an easier keybinding than `C-u C-h f' for commands.
> > And if we have `describe-command' on `C-h x', perhaps the prefix
> > argument to `describe-function' is just redundant?
> 
> It's not either/or.  It costs little to add the
> prefix-arg behavior, even if you add the option
> and command commands.

We are not supposed to add anything that costs little.

> That's similar to what we do for some apropos
> commands.  E.g. `apropos-user-option' compared
> with `apropos-variable' with a prefix arg; and
> `apropos-command' with and without a prefix arg.

As you say, "two wrongs don't make a right".

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 19 Feb 2021 21:25:27 -0600
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, "46627@debbugs.gnu.org" <46627@debbugs.gnu.org>
> 
> I see your point regarding #2, but thinking about it a bit I think it is
> preferable to have an easier keybinding than `C-u C-h f' for commands.

Indeed.  Help commands must be simple and should not use any fancy
mechanisms that are likely to evade newbies.  We have the F1 binding
for that very reason.

IMO, adding arguments to Help commands when the respective direct
commands are already available is just creeping featurism.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 19 Feb 2021 11:42:50 -0600
> Cc: 46627@debbugs.gnu.org, Lars Ingebrigtsen <larsi@gnus.org>
> 
> 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.

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

> +@item C-h x @var{command} @key{RET}
> +Display documentation on the command named @var{command}

It is better to avoid duplicating "command" here.  Like this:

   Display documentation on the named @var{command}.

It is advantageous to use this style whenever the thing in @var{..} is
a term that explains itself clearly enough, like here.

> +  @kbd{C-h x @var{command} @key{RET}} (@code{describe-command})
> +displays the documentation of the command @var{command}, in a
                                     ^^^^^^^^^^^^^^^^^^^^^
Likewise.

> +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}.

The last sentence is better moved to the description of describe-function.

> +  @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
> +displays the documentation of Lisp function @var{function}.  This
                                      ^^^^^^^^^^^^^^^^^^^^^^^
Duplication of "function" again.  (Yes, I know it was that way in the
original text.)

> +@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.

> +    (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?

Thanks.

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

[Stefan Kangas]

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

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 19 Feb 2021 22:10:58 -0600
> Cc: 46627@debbugs.gnu.org, larsi@gnus.org
> 
> > 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.

It's virtually impossible to fix that manually, as Info output and the
printed output have different line metrics and different line-breaking
algorithms.  And even if you succeed to fix that manually, it will
break again after any slight change in wording.

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?

> >> +    (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?

I'd prefer:

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

> Hmm, but now that I'm testing this, I'm not sure how to arrive at these
> messages from `C-h x'.

You can't.  To trigger these you must do some wizardry with
completion, to allow you to inject something that is not a function.
maybe Stefan Monnier (CC'ed) can help with setting that up.

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

> ->> 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".

Thanks.

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

[Stefan Kangas]

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

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> So the user will worry less if she has first seen that explanation,
> maybe?
>
> I've attached an updated patch.

Sounds good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 20 Feb 2021 11:10:28 -0600
> Cc: 46627@debbugs.gnu.org, larsi@gnus.org
> 
> >> ->> 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?

Fair enough, let's leave this for another rainy day.

> I've attached an updated patch.

Thanks, LGTM.

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

[Stefan Kangas]

tags 46627 fixed
close 46627 28.1
thanks

Eli Zaretskii <eliz@gnu.org> writes:

>> I've attached an updated patch.
>
> Thanks, LGTM.

Thanks.

There were some other ideas discussed in this thread, but no one seems
to have been working on them.  It also seems like most people in this
thread has agreed that this is a useful addition.

Unless there are any objections, I intend to push this change to master
in the next couple of days.

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

[Stefan Kangas]

tags 46627 - fixed
reopen 46627
thanks

Stefan Kangas <stefan@marxist.se> writes:
> tags 46627 fixed
> close 46627 28.1

[Accidentally closed, reopened now.]

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

[Stefan Kangas]

tags 46627 fixed
close 46627 28.1
thanks

Stefan Kangas <stefan@marxist.se> writes:

> Unless there are any objections, I intend to push this change to master
> in the next couple of days.

No objections within 4 days; pushed to master as commit 6c1c3204e4.

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> 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.)

`C-h c' would be more natural for this command, and the `c' mnemonic for
`describe-key-briefly' is pretty weak -- I'm guessing it ended up there
because `C-h k' and `C-h K' were already taken?  And `c' is kinda like
`k'?

But I agree 100% with Eli that we can't change `C-h c' -- it's a key
binding that I think is deeply ingrained in many people's muscle memory.

I do, however, think that `C-h x' isn't that bad of a binding for
`describe-command', really.

> 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'.

No, I think it should be given precedence, like you've done in your
patch -- it is the command users should be using.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  46627@debbugs.gnu.org
> Date: Sat, 20 Feb 2021 13:56:09 +0100
> 
> `C-h c' would be more natural for this command, and the `c' mnemonic for
> `describe-key-briefly' is pretty weak -- I'm guessing it ended up there
> because `C-h k' and `C-h K' were already taken?

No, I think it's because 'c' stands for "character".

> But I agree 100% with Eli that we can't change `C-h c' -- it's a key
> binding that I think is deeply ingrained in many people's muscle memory.

Yes, there should be a limit to moving such old bindings.

> I do, however, think that `C-h x' isn't that bad of a binding for
> `describe-command', really.

I agree.

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

[Eli Zaretskii]

> Date: Sat, 20 Feb 2021 14:59:24 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: stefan@marxist.se, 46627@debbugs.gnu.org
> 
> > `C-h c' would be more natural for this command, and the `c' mnemonic for
> > `describe-key-briefly' is pretty weak -- I'm guessing it ended up there
> > because `C-h k' and `C-h K' were already taken?
> 
> No, I think it's because 'c' stands for "character".

And the user manual actually says that:

  ‘C-h c KEY’
       Show the name of the command that the key sequence KEY is bound to
       (‘describe-key-briefly’).  Here ‘c’ stands for “character”.  For
       more extensive information on KEY, use ‘C-h k’.  *Note Key Help::.

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

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I do, however, think that `C-h x' isn't that bad of a binding for
> `describe-command', really.

Yeah, I think I've finally managed to convince myself that it's a
perfectly fine choice to use `C-h x' here, given the various trade-offs.

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

[Richard Stallman]

There seems to be little difference between the proposed
describe-command command and the existing describe-function command.
Whatever the former could do, the latter already does.

Am I missing something?

If not, what benefit justifies even the small cost in complexity (of
UI, of manual, and of code) of adding describe-command?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, larsi@gnus.org, 46627@debbugs.gnu.org
> Date: Sat, 20 Feb 2021 11:06:07 -0500
> 
> There seems to be little difference between the proposed
> describe-command command and the existing describe-function command.
> Whatever the former could do, the latter already does.

The main difference is in the completion these commands offer.
describe-command completes only on commands.

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

[Drew Adams]

> > There seems to be little difference between the proposed
> > describe-command command and the existing describe-function command.
> > Whatever the former could do, the latter already does.

Yes, the latter can do more.  Just as `integerp' can do
more than `natnump'.  Just as `eval-buffer' can do more
than `eval-region'.

> The main difference is in the completion these commands
> offer.  describe-command completes only on commands.

Yes, that's an important difference.  In addition,
_only commands are accepted_ as input, regardless
of whether you use completion.

(At least that's what my implementation does.
`completing-read' uses `commandp' as PREDICATE and
`t' as REQUIRE-MATCH.)

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "larsi@gnus.org" <larsi@gnus.org>,
>         "stefan@marxist.se"
> 	<stefan@marxist.se>,
>         "46627@debbugs.gnu.org" <46627@debbugs.gnu.org>
> Date: Sat, 20 Feb 2021 20:06:47 +0000
> 
> > The main difference is in the completion these commands
> > offer.  describe-command completes only on commands.
> 
> Yes, that's an important difference.  In addition,
> _only commands are accepted_ as input, regardless
> of whether you use completion.

No, because RET does completion.

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

[Drew Adams]

> > > The main difference is in the completion these commands
> > > offer.  describe-command completes only on commands.
> >
> > Yes, that's an important difference.  In addition,
> > _only commands are accepted_ as input, regardless
> > of whether you use completion.
> 
> No, because RET does completion.

(We're getting into nits now.  OK.)

Only if REQUIRE-MATCH is non-nil.  And _that_
provides the feature I mentioned: only commands
are accepted as input.

With REQUIRE-MATCH = nil, RET does no completion:

(completing-read "Command?: " obarray 'commandp nil)

You can input `xxxxxxxxxxxxxxxxxxxx' if you like,
and it's accepted without being a command name.

What you emphasized is the result of a PREDICATE
arg of `commandp'.  But accepting only commands
has nothing to do with completing.  It has to do
with REQUIRE-MATCH.  Both are important here.

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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

> There seems to be little difference between the proposed
> describe-command command and the existing describe-function command.
> Whatever the former could do, the latter already does.
>
> Am I missing something?
>
> If not, what benefit justifies even the small cost in complexity (of
> UI, of manual, and of code) of adding describe-command?

It makes it easier for users to look up only commands, as opposed to all
functions.

For end-users, many of which are non-programmers (or at least not ELisp
programmers), it is unnecessarily hard to find documentation for a
relevant command using `C-h f'.

Consider the situation when a user doesn't already know the command
name.  The workflow today is something like: use `M-x' to find the
command name, `C-a C-k C-g', then `C-h f C-y'.

This is even worse if you don't realize you can kill the command in the
minibuffer, which is actually not immediately obvious: the workflow is
then to try to remember the name and manually disambiguate it in the
mass of often fairly similar looking names thrown at you by `C-h f'.

So the idea is to combine searching for commands with looking up their
documentation.

I think the added complexity is a small price to pay for this
improvement in usability.

(The above is also based on my own experience and frustration, in both
the distant past and the not so distant past.)

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 20 Feb 2021 10:39:14 -0600
> Cc: eliz@gnu.org, larsi@gnus.org, 46627@debbugs.gnu.org
> 
> Consider the situation when a user doesn't already know the command
> name.  The workflow today is something like: use `M-x' to find the
> command name, `C-a C-k C-g', then `C-h f C-y'.

Not according to the user manual, it isn't.

AFAIR, Emacs never meant completion to be a means of discovery.  The
discovery was always meant to be through "apropos" commands.

> So the idea is to combine searching for commands with looking up their
> documentation.

I'm not sure this is a good idea, FWIW.  For starters, it is limited:
if you spot a command whose name sounds relevant, you have no simple
way getting details about it.  Unlike apropos commands, which do
provide such ways.

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

[Drew Adams]

> AFAIR, Emacs never meant completion to be a means of discovery.
> The discovery was always meant to be through "apropos" commands.

Emacs never originally meant a lot of things that
were later expanded (or repurposed to some degree)
to advantage.

This is normal for many processes of change.

Exaptation:

 https://en.wikipedia.org/wiki/Exaptation

Spandrel:

 https://en.wikipedia.org/wiki/Spandrel_(biology)

> > So the idea is to combine searching for commands
> > with looking up their documentation.
> 
> I'm not sure this is a good idea, FWIW.  For starters, it is limited:
> if you spot a command whose name sounds relevant, you have no simple
> way getting details about it.  Unlike apropos commands, which do
> provide such ways.

"You have no such simple way" ... until you do.

Icicles (and I'm sure some other 3rd-party code
that enhances completion) can provide help on
individual completion candidates.

When completion candidates are things that have
doc strings, Icicles shows the first line of the doc
string for the "current" completion candidate in the
mode-line of the *Completions* window.  When you
cycle among some candidates, you see their help there.

And you can hit a key to see the complete doc string
for the current candidate (it's shown in *Help*).

You mention apropos commands.  They're great in part
because they allow keyword & regexp matching.  This
is also true for Icicles completion.  You can use
`M-x' with a regexp pattern as input, to see all
commands whose names match.  And thus, to also get
access to their doc.

And unlike apropos, you can quickly change the match
pattern.  And you don't need to scan a long list of
output when you're only interested in the doc of
this, that, or the other matching name.

It's not that this is _better_ than apropos.  It's
different.  Each has advantages, just as `occur'
and Isearch have different advantages.

Is the _purpose_ of `M-x' to invoke a command?
Sure - or not.  Because you can _also_ use it to
browse command doc (and in other ways, not
mentioned), you can, if you want, sometimes use it
just for that - not bothering to invoke any command.

"Emacs never meant..."  Emacs never intended...
Right.  But now it does - at least with some
3rd-party packages.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "larsi@gnus.org" <larsi@gnus.org>, "rms@gnu.org" <rms@gnu.org>,
>         "46627@debbugs.gnu.org" <46627@debbugs.gnu.org>
> Date: Sat, 20 Feb 2021 20:35:28 +0000
> 
> > AFAIR, Emacs never meant completion to be a means of discovery.
> > The discovery was always meant to be through "apropos" commands.
> 
> Emacs never originally meant a lot of things that
> were later expanded (or repurposed to some degree)
> to advantage.
> [...]
> [Icicles...]

In your relentless promotion of your own packages and solutions, you
completely miss the point of what I wrote.

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

[Drew Adams]

> In your relentless promotion of your own packages
> and solutions, you completely miss the point of
> what I wrote.

No, you missed the point.  Under discussion is
helping vanilla Emacs to let `M-x' be a better
"means of discovery" of commands.  It's already
being used sometimes as a means of discovery.
People in the thread have pointed that out: they
sometimes use vanilla Emacs `M-x' for discovery.

Your point was that Emacs _never meant_ for `M-x'
to be a means of discovery.  I pointed out that
sometimes things created for purpose X also get
used for purpose Y.  I pointed to the importance
of this happenstance in evolution.  It can apply
to Emacs evolution as well.

I pointed out that users of 3rd-party libraries
already appreciate "discovery" features similar
to those proposed.  Hence the request (not from
me, BTW) to add this to Emacs now.

I'm not promoting anything.  I spoke of Icicles
to describe a use of completion as "a means of
discovery" - by way of example.

If I instead used Helm, Ivy, or whatever other,
similar package, I could presumably use it as
an example here instead of Icicles, and that
would be just as helpful/relevant.  I'm not
familiar with them; I use Icicles.  mea culpa.

This is about improving vanilla Emacs, not about
getting users to use this or that outside pkg.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "stefan@marxist.se" <stefan@marxist.se>,
>         "larsi@gnus.org"
> 	<larsi@gnus.org>, "rms@gnu.org" <rms@gnu.org>,
>         "46627@debbugs.gnu.org"
> 	<46627@debbugs.gnu.org>
> Date: Sat, 20 Feb 2021 21:16:18 +0000
> 
> No, you missed the point.

I cannot possibly miss the point I myself raised, by definition.

My point is that Emacs already has a well-developed subsystem for
discovery, and trying to produce an alternative based on completion is
reinventing the wheel from an inferior starting point.  I question the
wisdom of investing our resources in developing such an alternative.

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

[Drew Adams]

> My point is that Emacs already has a well-developed subsystem for
> discovery, and trying to produce an alternative based on completion is
> reinventing the wheel from an inferior starting point.  I question the
> wisdom of investing our resources in developing such an alternative.

It's not either/or.

Elisp (and other Lisps) already had a well-developed
way to associate objects with other objects in a set:
alists.

That didn't prevent Elisp (and other Lisps) from later
adding hash-table support - an "alternative" in some
ways, but certainly not a substitute.

There is overlap, but the two are different.  As such,
each has its advantages.  It's not about "reinventing
the wheel".

It's not either/or.  Not at all.

But that's a general argument.  Whether it's worth
adding a separate command `describe-command' is a
particular question and judgment.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "stefan@marxist.se" <stefan@marxist.se>,
>         "larsi@gnus.org"
> 	<larsi@gnus.org>, "rms@gnu.org" <rms@gnu.org>,
>         "46627@debbugs.gnu.org"
> 	<46627@debbugs.gnu.org>
> Date: Sun, 21 Feb 2021 17:55:16 +0000
> 
> > My point is that Emacs already has a well-developed subsystem for
> > discovery, and trying to produce an alternative based on completion is
> > reinventing the wheel from an inferior starting point.  I question the
> > wisdom of investing our resources in developing such an alternative.
> 
> It's not either/or.

It should be, because we don't have infinite resources.  And because
this is a support feature, not an editing/application feature.

> But that's a general argument.  Whether it's worth
> adding a separate command `describe-command' is a
> particular question and judgment.

Which is exactly what is being discussed here.  Not the general and
theoretical questions, the specific and practical one.

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

[Drew Adams]

> > It's not either/or.
> 
> It should be, because we don't have infinite resources.  And because
> this is a support feature, not an editing/application feature.

Fair enough.  Emacs is a volunteer endeavor.
No volunteers for something means it won't
be done.

No one, AFAIK, is really directing troops to
be applied to this or that development effort.
So a decision about whether something would be
good to have need not consider whether effort
should be spent on it.  As usual, someone with
an itch scratches it - or not.

> > But that's a general argument.  Whether it's worth
> > adding a separate command `describe-command' is a
> > particular question and judgment.
> 
> Which is exactly what is being discussed here.  Not the general and
> theoretical questions, the specific and practical one.

The general question was raised (by you, among
others) as to the benefit of the kind of feature
described.  Whether, and how. people actually
use completion for discovery.  The answers tried
to explain the whether (yes), the how, and the
benefits.

Your response to that was to immediately say that
that's duplication, reinvention of the wheel, etc.

And to immediately start talking about effort to
be spent on it, as a way of saying we can't afford
such a frivolous waste of energy on something that's
essentially a duplication of what we already have.

You kinda got what you asked for.  And yes, I think
it's good for Emacs developers to hear that such
things are useful, and how they are, and why they
are.

And yes, some of that is far afield of this bug
thread.  That kind of thing is not new to bug
discussions...

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

[Drew Adams]

Apropos...

Coming back to this, as I just happened to be reading
Paul Graham's essay "Novelty and Heresy" today, and
it rang a bell...

http://paulgraham.com/nov.html

> > AFAIR, Emacs never meant completion to be a means
> > of discovery.  The discovery was always meant to
> > be through "apropos" commands.
> 
> Emacs never originally meant a lot of things that
> were later expanded (or repurposed to some degree)
> to advantage.  This is normal for many processes
> of change.
>   Exaptation: [Wikipedia URL]
>   Spandrel:   [Wikipedia URL]
> 
> > > So the idea is to combine searching for commands
> > > with looking up their documentation.
> >
> > I'm not sure this is a good idea, FWIW.  For starters,
> > it is limited: if you spot a command whose name sounds
> > relevant, you have no simple way getting details about
> > it.  Unlike apropos commands, which do provide such ways.
> 
> "You have no such simple way" ... until you do.


From "Novelty and Heresy":

  One common way for a good idea to be non-obvious is
  for it to be hidden in the shadow of some mistaken
  assumption that people are very attached to.

  But anything you discover from working on such an
  idea will tend to contradict the mistaken assumption
  that was concealing it.  And you will thus get a lot
  of heat from people attached to the mistaken assumption.
  ...
  This phenomenon [is] probably always an ingredient
  in the resistance to new ideas.
  ...
  Every cherished mistaken assumption has a dead zone
  of unexplored ideas around it.

In this case, the usefulness of completion for discovery
has been pointed out by several people.  But it's _not_
the original intention for completion.  As you put it,
"Emacs never meant completion to be a means of discovery."
And the legitimate, intended means of discovery in Emacs
was apropos.

But completion _is_, accidentally or not, a means to
discovery - and it can be a good one.

That original intention corresponds to a "mistaken
assumption" in this context: the assumption that
completion is not for discovery _because_ that isn't
why it was added to Emacs (and something else was
added to aid discovery).

Saying that completion is, or it can be, useful for
discovery?  Heresy.

The usefulness of 3rd-party code that has fruitfully
explored the "dead zone" around the assumption that
the only purpose of completion is to return completed
input is pretty clear to those acquainted with it.

The positive takeaway, beyond the case of using
completion for discovery?

  The depressingly large dead zones around mistaken
  assumptions [can] become excitingly large mines of
  new ideas.

That puts exaptation in an active light - it need not
be an entirely accidental process.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "larsi@gnus.org" <larsi@gnus.org>, "rms@gnu.org" <rms@gnu.org>,
>         "46627@debbugs.gnu.org" <46627@debbugs.gnu.org>
> Date: Fri, 26 Feb 2021 21:34:21 +0000
> 
> Apropos...
> 
> Coming back to this, as I just happened to be reading
> Paul Graham's essay "Novelty and Heresy" today, and
> it rang a bell...

It's strange to have such a discussion in a context of a bug report...

> The positive takeaway, beyond the case of using
> completion for discovery?
> 
>   The depressingly large dead zones around mistaken
>   assumptions [can] become excitingly large mines of
>   new ideas.

AFAIU, this is a classical circular logic fallacy: assume that an idea
is a smart one and everyone opposed to it is silly or mistaken, and
everything else follows.

What if it's the other way around?

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

[Drew Adams]

> > The positive takeaway, beyond the case of using
> > completion for discovery?
> >
> >   The depressingly large dead zones around mistaken
> >   assumptions [can] become excitingly large mines of
> >   new ideas.
> 
> AFAIU, this is a classical circular logic fallacy: assume that an idea
> is a smart one and everyone opposed to it is silly or mistaken, and
> everything else follows.

There's no such assumption.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Consider the situation when a user doesn't already know the command
  > name.  The workflow today is something like: use `M-x' to find the
  > command name,

Is this really what people do?  I am surprised people find it useful,
surprised that you can ever find a command name that way.

If you have seen users do it, can you say more about the situations
where it is effective?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

> Is this really what people do?  I am surprised people find it useful,
> surprised that you can ever find a command name that way.

Yes, we have evidence of this on emacs-devel.  I do it myself at times.

> If you have seen users do it, can you say more about the situations
> where it is effective?

I can't claim that it is the most effective technique in general.
I would use it when I am certain that I almost know the name of a
command -- I would know it if I see it.  In such situations, firing up
apropos is an extra step and not what I want.  Today, I just use `C-h f'
and manually filter for what is likely the command I am looking for.
With `describe-command', this would be a better experience.

But I think the use of `describe-command' goes beyond this one use-case.
In particular, I don't think end-users should need to filter through a
massive, intimidating list of functions when they are just looking for a
command.

(BTW, in the completion framework I often use, `ivy', there is a command
to run the action associated with the minibuffer without leaving the
minibuffer.  That is, I run `C-h f', type in some text to complete on,
and then hit `C-M-n' to repeatedly see the full documentation for a
number of commands.  This is a very effective way to scan for the
correct function, often much more effective than apropos.  But vanilla
Emacs currently does not support this, AFAIK.)

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 01:18:02 -0600
> Cc: eliz@gnu.org, larsi@gnus.org, 46627@debbugs.gnu.org
> 
> I can't claim that it is the most effective technique in general.
> I would use it when I am certain that I almost know the name of a
> command -- I would know it if I see it.  In such situations, firing up
> apropos is an extra step and not what I want.

Can you explain how apropos is an extra step, compared to TAB
completion followed by browsing through the candidates?  I see no
extra step here.

> But I think the use of `describe-command' goes beyond this one use-case.
> In particular, I don't think end-users should need to filter through a
> massive, intimidating list of functions when they are just looking for a
> command.

"C-h a" accomplishes that.  It is no accident that it's the very first
Help command mentioned in the user manual.  In addition, "C-h a" is
more powerful, as it accepts regular expressions and lists of
keywords, whereas completion has only crude and less powerful
approximations of those.

> (BTW, in the completion framework I often use, `ivy', there is a command
> to run the action associated with the minibuffer without leaving the
> minibuffer.  That is, I run `C-h f', type in some text to complete on,
> and then hit `C-M-n' to repeatedly see the full documentation for a
> number of commands.

You can likewise type "C-h a", then, with point on the command you
were after, type "M-x <DOWN> RET" or "M-x M-n RET" to invoke that
command.  So the task of finding a command and then quickly invoking
it already has a well-developed solution in Emacs, one that is more
powerful than completion.

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

[Howard Melman]

FWIW since I started using a third party completion package
(first helm, then ivy and now selectrum/consult/marginalia)
I use apropos far less.  I didn't expect that but it's the
case for me.

I've configured these package so that they show possible
completions vertically, one per line, and show annotations.
So now when I type M-x I not only see a list of commands I
can invoke, but also their keybinding and the first line of
their docstring.  As I type and narrow the completions this
shows me a list of commands related to what I want and even
a brief description if the name is not enough.  

I know that apropos is more featureful and I know how to
invoke it easily, but since I use M-x more commonly and it
now includes this basic info, my use of C-h a has decreased
as its just anothing thing to remember.

Also, when I use M-x normally I now get a kind of background
appropos happening all the time which gives me a little more
discovery.  If I search for "register" to find the
jump-to-register command I'll see other register commands,
and those that are bound stand out a bit. If I'm not in a
rush I might scan it to discover other things I didn't know
about.

This works for me to with C-h v whose annotations show me
the current value (in a clipped narrow column) and the first
line of the docstring.  Also with C-h f.  These are not as
complete as apropos as they don't match on the docstrings,
but they're more interactive and I've found are good enough
and apropos is still there if I need it.

-- 

Howard

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

[Drew Adams]

+1.  Well put.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> I can't claim that it is the most effective technique in general.
>> I would use it when I am certain that I almost know the name of a
>> command -- I would know it if I see it.  In such situations, firing up
>> apropos is an extra step and not what I want.
>
> Can you explain how apropos is an extra step, compared to TAB
> completion followed by browsing through the candidates?  I see no
> extra step here.

So I type `C-h a foobar RET'.

Now I realize I want to look for "foobaz", so `C-h a foobaz RET'.

Now I realize that oops, I meant "barsnaz", etc.

Typing this at a prompt is often faster for me.  In particular, I don't
need to rewrite everything for minor changes.

Yes, I can be smarter and say `C-h a M-p DEL z RET', but I think we can
agree that `DEL z TAB' is less typing.  (BTW, with many completion
frameworks you don't even need the TAB.)

Plus I often look only for names, and don't need to waste screen real
estate on documentation (which I would using apropos).

> "C-h a" accomplishes that.  It is no accident that it's the very first
> Help command mentioned in the user manual.  In addition, "C-h a" is
> more powerful, as it accepts regular expressions and lists of
> keywords, whereas completion has only crude and less powerful
> approximations of those.

Many popular completion frameworks have regexps, lists, fuzzy search,
etc.  But yes, our default one does not.

>> (BTW, in the completion framework I often use, `ivy', there is a command
>> to run the action associated with the minibuffer without leaving the
>> minibuffer.  That is, I run `C-h f', type in some text to complete on,
>> and then hit `C-M-n' to repeatedly see the full documentation for a
>> number of commands.
>
> You can likewise type "C-h a", then, with point on the command you
> were after, type "M-x <DOWN> RET" or "M-x M-n RET" to invoke that
> command.  So the task of finding a command and then quickly invoking
> it already has a well-developed solution in Emacs, one that is more
> powerful than completion.

Sure, you can do that.  It is in my view often slower (and more typing)
than the workflow I described, but of course that also depends on the
circumstances.

I don't see that we need to agree about the relative efficiency of these
workflows.  We can and do support both workflows well.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 11:01:11 -0600
> Cc: rms@gnu.org, larsi@gnus.org, 46627@debbugs.gnu.org
> 
> So I type `C-h a foobar RET'.
> 
> Now I realize I want to look for "foobaz", so `C-h a foobaz RET'.
> 
> Now I realize that oops, I meant "barsnaz", etc.
> 
> Typing this at a prompt is often faster for me.  In particular, I don't
> need to rewrite everything for minor changes.
> 
> Yes, I can be smarter and say `C-h a M-p DEL z RET', but I think we can
> agree that `DEL z TAB' is less typing.

No, I think you are splitting hair.  Typing one more key justifies a
whole new command?  Really?

And I'm not even talking about the display you get with "C-h a", which
is much more informative than what completion shows.

> (BTW, with many completion frameworks you don't even need the TAB.)

We are talking about features that are built-in.  Otherwise, why did
we add a new command for getting help on commands, when it's so easy
to get it from other completion frameworks?

> Plus I often look only for names, and don't need to waste screen real
> estate on documentation (which I would using apropos).

Displaying completion candidates doesn't use any screen estate?

> I don't see that we need to agree about the relative efficiency of these
> workflows.  We can and do support both workflows well.

See my other message: building a discovery subsystem starting from
completion reinvents the wheel, and begins from an inferior starting
point.  If that's not an argument worth considering, from the project
management POV, then I don't know what is.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> No, I think you are splitting hair.  Typing one more key justifies a
> whole new command?  Really?

Wait, are you now arguing against `C-h x'?

> Displaying completion candidates doesn't use any screen estate?

It uses more screen estate to display documentation than to just display
the command name.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sun, 21 Feb 2021 12:02:20 -0600
> Cc: rms@gnu.org, larsi@gnus.org, 46627@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > No, I think you are splitting hair.  Typing one more key justifies a
> > whole new command?  Really?
> 
> Wait, are you now arguing against `C-h x'?

No, if I wanted to argue against it, I'd do it before it was
installed.  I don't mind the command, although I personally will
probably never use it.

I'm arguing against the tendency to introduce a whole new discovery
framework based on completion.  I think Emacs doesn't need that in
core; whoever wants something like that, can use one of the many
packages out there which implement every possible completion paradigm
under the sun.  We as the core development team should not invest any
significant energy in developing such framework, but should instead
improve and enhance what we already have.  For example, the apropos
commands could perhaps benefit from taking some context into account,
like the current major mode and the previous apropos searches, and
improve accuracy using that.

IOW, my problem is not "C-h x", it's that "C-h x" and its ilk is or
will be seen as the beginning of a discovery framework that we will
now actively develop.

> > Displaying completion candidates doesn't use any screen estate?
> 
> It uses more screen estate to display documentation than to just display
> the command name.

Completion doesn't just display a single command name, it displays a
list, which typically takes more than one screen line.

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

[Dmitry Gutov]

On 21.02.2021 20:21, Eli Zaretskii wrote:
> I'm arguing against the tendency to introduce a whole new discovery
> framework based on completion.  I think Emacs doesn't need that in
> core; whoever wants something like that, can use one of the many
> packages out there which implement every possible completion paradigm
> under the sun.  We as the core development team should not invest any
> significant energy in developing such framework, but should instead
> improve and enhance what we already have.

I think we've "had it" ever since 'M-x' started providing completion. 
Right after that, it became possible to discover commands this way (and 
I do it all the time, too).

So it's really about improving an existing feature.

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

[Eli Zaretskii]

> Cc: larsi@gnus.org, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 21 Feb 2021 21:57:25 +0200
> 
> On 21.02.2021 20:21, Eli Zaretskii wrote:
> > I'm arguing against the tendency to introduce a whole new discovery
> > framework based on completion.  I think Emacs doesn't need that in
> > core; whoever wants something like that, can use one of the many
> > packages out there which implement every possible completion paradigm
> > under the sun.  We as the core development team should not invest any
> > significant energy in developing such framework, but should instead
> > improve and enhance what we already have.
> 
> I think we've "had it" ever since 'M-x' started providing completion. 

And I tried to explain why this is a bad starting point.

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

[Dmitry Gutov]

On 21.02.2021 22:13, Eli Zaretskii wrote:
>> I think we've "had it" ever since 'M-x' started providing completion.
> And I tried to explain why this is a bad starting point.

I think Stefan explained quite well that 'M-x apropos' is very often not 
an optimal alternative.

Nor is this a first discussion about how users discover new functions 
using completion. It came at least once before when we talked about 
Elisp function naming and consistency.

Saying "Emacs has these functions for doc discovery" is totally fine, 
but I don't think we can stop there and ignore the current practice 
among our users, or the experience from other editing environments.

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

[Eli Zaretskii]

> Cc: stefan@marxist.se, larsi@gnus.org, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 22 Feb 2021 01:46:50 +0200
> 
> Saying "Emacs has these functions for doc discovery" is totally fine, 
> but I don't think we can stop there and ignore the current practice 
> among our users, or the experience from other editing environments.

We are not ignoring the current practices.  We are saying that people
who want their discovery based on completion will find the solution in
the completion alternatives we have already in Emacs, and if that
still doesn't fit the bill, in the 3rd-party packages out there.  I
think Emacs provides, and will continue providing, ample
infrastructure for such extensions, and that's enough, IMO.  There's
no reason we should feel obliged to develop these features in Emacs.
We will never be able to satisfy everyone there anyway.

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

[Dmitry Gutov]

On 22.02.2021 17:18, Eli Zaretskii wrote:
>> Cc: stefan@marxist.se, larsi@gnus.org, rms@gnu.org, 46627@debbugs.gnu.org
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Mon, 22 Feb 2021 01:46:50 +0200
>>
>> Saying "Emacs has these functions for doc discovery" is totally fine,
>> but I don't think we can stop there and ignore the current practice
>> among our users, or the experience from other editing environments.
> 
> We are not ignoring the current practices.  We are saying that people
> who want their discovery based on completion will find the solution in
> the completion alternatives we have already in Emacs, and if that
> still doesn't fit the bill, in the 3rd-party packages out there.

Do you have in mind some particular "completion alternative we have 
already" for 'describe-command'?

> I
> think Emacs provides, and will continue providing, ample
> infrastructure for such extensions, and that's enough, IMO.  There's
> no reason we should feel obliged to develop these features in Emacs.
> We will never be able to satisfy everyone there anyway.

I believe the argument is that we can improve the default experience by 
enacting some minor changes which correspond to what we know about how 
users discover new commands (or functions) or remember existing ones. 
And do that without pulling in major new functionality or features from 
third-party packages (which goes against the "lean core" concept which 
you probably know I prefer).

And I believe we shouldn't discount initiatives to improve the default 
experience's usability as attempts to "satisfy everyone". Which I also 
think we shouldn't do.

There were also suggestions for admittedly more invasive changes (like 
doing a bunch of renames in the standard library) which seem to have all 
been rejected by the leadership. I understand the reluctance to change 
things, but the argument about Emacs's extensibility and the 3rd party 
ecosystem wouldn't apply to it either because no matter how convenient 
and slick an external package might make completion experience, if the 
functions are irregularly named, that will remain a problem anyway.

So you might disagree on whether this feature is important. But I hope 
you can see how some aspects of the "whole new discovery framework" 
(which I'm saying isn't new) cannot be effectively enacted by 3rd party 
code without help from us here.

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

[Eli Zaretskii]

> Cc: larsi@gnus.org, stefan@marxist.se, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 27 Feb 2021 22:38:31 +0200
> 
> > We are not ignoring the current practices.  We are saying that people
> > who want their discovery based on completion will find the solution in
> > the completion alternatives we have already in Emacs, and if that
> > still doesn't fit the bill, in the 3rd-party packages out there.
> 
> Do you have in mind some particular "completion alternative we have 
> already" for 'describe-command'?

icomplete.el, completion.el, pcomplete.el, and the non-default styles
in completion-styles-alist come to mind.

> > I
> > think Emacs provides, and will continue providing, ample
> > infrastructure for such extensions, and that's enough, IMO.  There's
> > no reason we should feel obliged to develop these features in Emacs.
> > We will never be able to satisfy everyone there anyway.
> 
> I believe the argument is that we can improve the default experience by 
> enacting some minor changes which correspond to what we know about how 
> users discover new commands (or functions) or remember existing ones. 
> And do that without pulling in major new functionality or features from 
> third-party packages (which goes against the "lean core" concept which 
> you probably know I prefer).

This loses the context.  Minor improvements were not the issue I
raised, the issue was the perceived attempt to build a significant
discovery framework based on completion.

> There were also suggestions for admittedly more invasive changes (like 
> doing a bunch of renames in the standard library) which seem to have all 
> been rejected by the leadership. I understand the reluctance to change 
> things, but the argument about Emacs's extensibility and the 3rd party 
> ecosystem wouldn't apply to it either because no matter how convenient 
> and slick an external package might make completion experience, if the 
> functions are irregularly named, that will remain a problem anyway.

How is this relevant to the issue at hand?

> So you might disagree on whether this feature is important. But I hope 
> you can see how some aspects of the "whole new discovery framework" 
> (which I'm saying isn't new) cannot be effectively enacted by 3rd party 
> code without help from us here.

I have nothing against providing infrastructure for more sophisticated
completion, I was talking only about adding new commands which aim to
provide discovery based on completion, or extend existing
completion-related commands with the goal of providing discovery
through them.

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

[Dmitry Gutov]

On 28.02.2021 19:27, Eli Zaretskii wrote:

>>> We are not ignoring the current practices.  We are saying that people
>>> who want their discovery based on completion will find the solution in
>>> the completion alternatives we have already in Emacs, and if that
>>> still doesn't fit the bill, in the 3rd-party packages out there.
>>
>> Do you have in mind some particular "completion alternative we have
>> already" for 'describe-command'?
> 
> icomplete.el, completion.el, pcomplete.el, and the non-default styles
> in completion-styles-alist come to mind.

All of these (with possible exception of completion.el, which I'm not 
familiar with) determine how completions are shown and/or how matching 
is performed, but the total set of completions (completion table) is 
determined by the command the user invokes.

So they don't include anything that looks like a replacement for 
'describe-command'. But when there is a standard command with a good 
completion table, they indeed can enhance the user experience.

There are packages which create new commands (and might even have 
something similar to describe-command), but they are usually tied to a 
particular completion framework.

>>> I
>>> think Emacs provides, and will continue providing, ample
>>> infrastructure for such extensions, and that's enough, IMO.  There's
>>> no reason we should feel obliged to develop these features in Emacs.
>>> We will never be able to satisfy everyone there anyway.
>>
>> I believe the argument is that we can improve the default experience by
>> enacting some minor changes which correspond to what we know about how
>> users discover new commands (or functions) or remember existing ones.
>> And do that without pulling in major new functionality or features from
>> third-party packages (which goes against the "lean core" concept which
>> you probably know I prefer).
> 
> This loses the context.  Minor improvements were not the issue I
> raised, the issue was the perceived attempt to build a significant
> discovery framework based on completion.

"Significant discovery framework" is something very ill-defined. From 
where I'm standing, function and variable discovery based on completion 
is already in Emacs, and we sometimes provide minor fixes and 
improvement for it (such as this command). Sometimes we do request major 
changes that would help it as well...

>> There were also suggestions for admittedly more invasive changes (like
>> doing a bunch of renames in the standard library) which seem to have all
>> been rejected by the leadership. I understand the reluctance to change
>> things, but the argument about Emacs's extensibility and the 3rd party
>> ecosystem wouldn't apply to it either because no matter how convenient
>> and slick an external package might make completion experience, if the
>> functions are irregularly named, that will remain a problem anyway.
> 
> How is this relevant to the issue at hand?

...and see them thoroughly rejected. So I think this is relevant. But we 
might be talking about different things.

>> So you might disagree on whether this feature is important. But I hope
>> you can see how some aspects of the "whole new discovery framework"
>> (which I'm saying isn't new) cannot be effectively enacted by 3rd party
>> code without help from us here.
> 
> I have nothing against providing infrastructure for more sophisticated
> completion, I was talking only about adding new commands which aim to
> provide discovery based on completion,

But which otherwise duplicate existing commands? This is a valid 
concern, but I don't think we'll get a lot of them.

> or extend existing
> completion-related commands with the goal of providing discovery
> through them.

Do you mean like extensions of the completion-at-point interface with 
that aim? I'm curious about possibilities, but so far we haven't really 
discussed them here.

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

[Eli Zaretskii]

> Cc: larsi@gnus.org, stefan@marxist.se, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 28 Feb 2021 23:40:06 +0200
> 
> On 28.02.2021 19:27, Eli Zaretskii wrote:
> 
> >> Do you have in mind some particular "completion alternative we have
> >> already" for 'describe-command'?
> > 
> > icomplete.el, completion.el, pcomplete.el, and the non-default styles
> > in completion-styles-alist come to mind.
> 
> All of these (with possible exception of completion.el, which I'm not 
> familiar with) determine how completions are shown and/or how matching 
> is performed, but the total set of completions (completion table) is 
> determined by the command the user invokes.

The completion style does determine the set of candidates, if that's
the only aspect you are interested in.  And the way the candidates are
presented is an important part of how easy and user-friendly discovery
is.

> So they don't include anything that looks like a replacement for 
> 'describe-command'.

I wasn't talking only about describe-command, not even in particular
about it.  I was talking about a much more general issue.  If
describe-command is the only addition, then I have no problems with
that; I only care if that command is the tip of a much larger iceberg.

> > This loses the context.  Minor improvements were not the issue I
> > raised, the issue was the perceived attempt to build a significant
> > discovery framework based on completion.
> 
> "Significant discovery framework" is something very ill-defined. From 
> where I'm standing, function and variable discovery based on completion 
> is already in Emacs, and we sometimes provide minor fixes and 
> improvement for it (such as this command).

Then we are in fact in violent agreement.

> Sometimes we do request major changes that would help it as well...

That's the issue at hand.  I don't think we need or should entertain
major changes in that area.

> > I have nothing against providing infrastructure for more sophisticated
> > completion, I was talking only about adding new commands which aim to
> > provide discovery based on completion,
> 
> But which otherwise duplicate existing commands?

Duplicate functionality, not commands.

> > or extend existing
> > completion-related commands with the goal of providing discovery
> > through them.
> 
> Do you mean like extensions of the completion-at-point interface with 
> that aim? I'm curious about possibilities, but so far we haven't really 
> discussed them here.

I don't know what I mean, I will know when actual proposals are
brought up.

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

[Dmitry Gutov]

On 01.03.2021 08:05, Eli Zaretskii wrote:

>>>> Do you have in mind some particular "completion alternative we have
>>>> already" for 'describe-command'?
>>>
>>> icomplete.el, completion.el, pcomplete.el, and the non-default styles
>>> in completion-styles-alist come to mind.
>>
>> All of these (with possible exception of completion.el, which I'm not
>> familiar with) determine how completions are shown and/or how matching
>> is performed, but the total set of completions (completion table) is
>> determined by the command the user invokes.
> 
> The completion style does determine the set of candidates, if that's
> the only aspect you are interested in. 

Completion style only determines how completions are matched, but not 
the total set of them. That's defined either by the completion table, or 
by a completion predicate.

> And the way the candidates are
> presented is an important part of how easy and user-friendly discovery
> is.

Of course.

>> So they don't include anything that looks like a replacement for
>> 'describe-command'.
> 
> I wasn't talking only about describe-command, not even in particular
> about it.  I was talking about a much more general issue.  If
> describe-command is the only addition, then I have no problems with
> that; I only care if that command is the tip of a much larger iceberg.

I don't think it's going to be.

Even if we wanted, there are only so many free key bindings anyway. And 
having more and more commands, bound to different keys, is not actually 
something that's going to help a new user get oriented quickly.

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

[Eli Zaretskii]

> Cc: larsi@gnus.org, stefan@marxist.se, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 2 Mar 2021 03:40:02 +0200
> 
> >> All of these (with possible exception of completion.el, which I'm not
> >> familiar with) determine how completions are shown and/or how matching
> >> is performed, but the total set of completions (completion table) is
> >> determined by the command the user invokes.
> > 
> > The completion style does determine the set of candidates, if that's
> > the only aspect you are interested in. 
> 
> Completion style only determines how completions are matched, but not 
> the total set of them. That's defined either by the completion table, or 
> by a completion predicate.

Perhaps I'm missing something, but if, for example, you use the
'initials' style, then "lch" can complete to list-command-history, but
if you don't use 'initials', it will complete to nothing.  So maybe
you are right from the implementation POV, but the list of the
candidates shown to the user is in fact determined by the style.  And
that displayed list is what matters for discovery; that Emacs
internally had some other list is immaterial.

> > I wasn't talking only about describe-command, not even in particular
> > about it.  I was talking about a much more general issue.  If
> > describe-command is the only addition, then I have no problems with
> > that; I only care if that command is the tip of a much larger iceberg.
> 
> I don't think it's going to be.

Then we will be fine.

> Even if we wanted, there are only so many free key bindings anyway. And 
> having more and more commands, bound to different keys, is not actually 
> something that's going to help a new user get oriented quickly.

I agree.

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

[Dmitry Gutov]

On 02.03.2021 07:31, Eli Zaretskii wrote:
> Perhaps I'm missing something, but if, for example, you use the
> 'initials' style, then "lch" can complete to list-command-history, but
> if you don't use 'initials', it will complete to nothing.  So maybe
> you are right from the implementation POV, but the list of the
> candidates shown to the user is in fact determined by the style.  And
> that displayed list is what matters for discovery; that Emacs
> internally had some other list is immaterial.

It matters because the completion table is determined by the command in 
use, and the completion style is based on user customization.

As such, completion styles don't usually use any semantic information 
about completions.

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

[Eli Zaretskii]

> Cc: larsi@gnus.org, stefan@marxist.se, rms@gnu.org, 46627@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Tue, 2 Mar 2021 14:55:26 +0200
> 
> On 02.03.2021 07:31, Eli Zaretskii wrote:
> > Perhaps I'm missing something, but if, for example, you use the
> > 'initials' style, then "lch" can complete to list-command-history, but
> > if you don't use 'initials', it will complete to nothing.  So maybe
> > you are right from the implementation POV, but the list of the
> > candidates shown to the user is in fact determined by the style.  And
> > that displayed list is what matters for discovery; that Emacs
> > internally had some other list is immaterial.
> 
> It matters because the completion table is determined by the command in 
> use, and the completion style is based on user customization.
> 
> As such, completion styles don't usually use any semantic information 
> about completions.

We are talking past each other.

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

[Drew Adams]

> You can likewise type "C-h a", then, with point on the command you
> were after, type "M-x <DOWN> RET" or "M-x M-n RET" to invoke that
> command.  So the task of finding a command and then quickly invoking
> it already has a well-developed solution in Emacs, one that is more
> powerful than completion.

You can use `occur' and go to a line and hit RET.
But that doesn't mean we should have only `occur'
and not also Isearch.

Your reasoning here is black-&-white, either/or.

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

[Drew Adams]

> (BTW, in the completion framework I often use,
> `ivy', there is a command to run the action
> associated with the minibuffer without leaving
> the minibuffer.

This feature was introduced by Icicles, BTW.
It's since been copied in other (more popular)
libraries, along with other Icicles features.

> That is, I run `C-h f', type in some text to
> complete on, and then hit `C-M-n' to repeatedly
> see the full documentation

That feature of providing help on candidates
was also introduced by Icicles, BTW.  But it's
available for all commands, not just help
commands.  IOW, you have both the command's
action and help available, for each candidate.

I introduced this in 1995, back when Icicles
was still called elect-mbuf.el (it was renamed
in 2005).

RMS was aware of this feature in the mid-2000s,
at least, when there was some discussion of
integrating some of Icicles into Emacs.

> This is a very effective way to scan for the
> correct function, often much more effective
> than apropos.

Yes.  As I mentioned, both apropos and such
on-the-fly completion-candidate help are useful.
Neither need be seen as a substitute for the
other.  This is like both `occur' and Isearch
being useful, each in its own way.

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

[Lars Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

>   > Consider the situation when a user doesn't already know the command
>   > name.  The workflow today is something like: use `M-x' to find the
>   > command name,
>
> Is this really what people do?  I am surprised people find it useful,
> surprised that you can ever find a command name that way.

I do it all the time.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Consider the situation when a user doesn't already know the command
  > name.  The workflow today is something like: use `M-x' to find the
  > command name,

Is this really what people do?  I am surprised people find it useful,
surprised that you can ever find a command name that way.

If you have seen users do it, can you say more about the situations
where it is effective?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

There seems to be little difference between the proposed
describe-command command and the existing describe-function command.
Whatever the former could do, the latter already does.

What benefit justifies even the small cost in complexity (of UI, of
manual, and of code) of adding describe-command?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

There seems to be little difference between the proposed
describe-command command and the existing describe-function command.
Whatever the former could do, the latter already does.

What benefit justifies even the small cost in complexity (of UI, of
manual, and of code) of adding describe-command?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> 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.

Good idea.

> I don't know if we should add a key binding, since the most obvious
> place to put it, `C-h c', is unfortunately already taken.  Perhaps
> `C-h x' would make some sense in analogy with `M-x'.  (Or perhaps it is
> worth moving `describe-key-briefly'...)  So I solved it here by not
> adding any key at all, for now.
>
> Thoughts?

Yeah, the `C-h' keymap is very full...  Hm...  `C-h x' does indeed seem
to be the most best one among the non-taken letters.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> > I don't know if we should add a key binding, since the most obvious
> > place to put it, `C-h c', is unfortunately already taken.  Perhaps
> > `C-h x' would make some sense in analogy with `M-x'.  (Or perhaps it
> is
> > worth moving `describe-key-briefly'...)  So I solved it here by not
> > adding any key at all, for now.
> >
> > Thoughts?
> 
> Yeah, the `C-h' keymap is very full...  Hm...  `C-h x' does indeed seem
> to be the most best one among the non-taken letters.

(I'm the one who wrote `describe-command' (long ago).)

I bind it to `C-h c', in place of `describe-key-briefly',
which I moved to `C-h C-c'.

I think this makes sense for vanilla Emacs also, as
`d-k-b' is, I think, not used so much nowadays.
(Am I wrong about that?  Dunno.)

Yes, this would be an incompatible default key change,
so if you think it's a good idea then it should maybe
be discussed in emacs-devel.

I personally haven't used `describe-key-briefly since
the 80s.  And I use `C-h k' often (as well as `C-h c'
as `describe-command').

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Fri, 19 Feb 2021 18:27:05 +0000
> Cc: "46627@debbugs.gnu.org" <46627@debbugs.gnu.org>
> 
> I bind it to `C-h c', in place of `describe-key-briefly',
> which I moved to `C-h C-c'.
> 
> I think this makes sense for vanilla Emacs also

No, we will NOT move the "C-h c" binding, not on my watch.  Please
drop this idea.

> as `d-k-b' is, I think, not used so much nowadays.  (Am I wrong
> about that?  Dunno.)

Yes, you are wrong.  I use it all the time.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I use C-h c.  I expect that lots of people use it.  Don't change it!


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I use C-h c.  I expect that lots of people use it.  Don't change it!


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > As recently discussed on emacs-devel, it could be useful to have a
  > command `describe-command' to search for commands.

What would this command do?  "Search for commands" is not very clear.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

>   > As recently discussed on emacs-devel, it could be useful to have a
>   > command `describe-command' to search for commands.
>
> What would this command do?  "Search for commands" is not very clear.

It would be like `describe-function' but show only commands.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It would be like `describe-function' but show only commands.

Are you perhaps talking about limiting the candidates for completion?

If the only difference between these commands is completion of the
argument, here's an idea.

* Make TAB and ?, when a completion list is displayed, toggle the
completion mode between commands-only and all-functions.

* Arrange a way to show on the screen which completion mode is in use.
Perhaps in the completions list buffer.

* Make C-h f start out with completion in commands-only mode.  That
will be good for beginners.  If you want to complete a noninteractive
function name, toggle the completion mode.

This interface involves no new commands, and no new bindings, and it
is easy to discover.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It would be like `describe-function' but show only commands.

Are you perhaps talking about limiting the candidates for completion?

If the only difference between these commands is completion of the
argument, here's an idea.

* Make TAB and ?, when a completion list is displayed, toggle the
completion mode between commands-only and all-functions.

* Arrange a way to show on the screen which completion mode is in use.
Perhaps in the completions list buffer.

* Make C-h f start out with completion in commands-only mode.  That
will be good for beginners.  If you want to complete a noninteractive
function name, toggle the completion mode.

This interface involves no new commands, and no new bindings, and it
is easy to discover.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

>   > It would be like `describe-function' but show only commands.
>
> Are you perhaps talking about limiting the candidates for completion?

Yes.

> If the only difference between these commands is completion of the
> argument, here's an idea.
>
> * Make TAB and ?, when a completion list is displayed, toggle the
> completion mode between commands-only and all-functions.
>
> * Arrange a way to show on the screen which completion mode is in use.
> Perhaps in the completions list buffer.
>
> * Make C-h f start out with completion in commands-only mode.  That
> will be good for beginners.  If you want to complete a noninteractive
> function name, toggle the completion mode.
>
> This interface involves no new commands, and no new bindings, and it
> is easy to discover.

To me, it certainly sounds more complicated to learn, and harder to use,
than just having two separate commands.  If your concern is complexity,
the above is the more complex UI.

Just compare the above explanation with this:

- `C-h f' for any function
- `C-h x' for commands

Also, the patch is really not that big.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > To me, it certainly sounds more complicated to learn, and harder to use,
  > than just having two separate commands.  If your concern is complexity,
  > the above is the more complex UI.

I am astounded by the way you see it.
I did not expect to encounter disagreement on this point.

It seems that you are equally astounded.

I will explain why I see it the way I do.

  > - `C-h f' for any function
  > - `C-h x' for commands

This is yet one more specific command one needs to remember.  For a
beginner, or even a not-quite-beginner, learning hundreds of other
commands is the hard part.  And it is easy to forget them.

By contrast, what TAB TAB TAB... does inside completion for commands
is a general feature, not similar to any other.

Users will forget commands that they learned, but I think they will
hardly forget this.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

> I will explain why I see it the way I do.

Thank you, I will add my thoughts below.

>   > - `C-h f' for any function
>   > - `C-h x' for commands
>
> This is yet one more specific command one needs to remember.  For a
> beginner, or even a not-quite-beginner, learning hundreds of other
> commands is the hard part.  And it is easy to forget them.

This is an important point when we add any command.  I agree that in
general we must be careful to not unduly add to the cognitive load of
using Emacs.

Note first that the `C-h f' command has never been that hard to learn,
because it is just exactly the help key "C-h" and then "f" for
"function" -- arguably one of the most mnemonic keybindings we have.
(`C-h x' is a bit less mnemonic, indeed.)

Here is how I approach this problem:

- Most users do not need to see Emacs Lisp functions when starting out.
  They need to be able to find help for editor commands.

- They should be using `C-h x', `describe-command'.

That actually concludes what I expect a beginning Emacs user will have
to learn.  :-)

- Emacs Lisp "literate" users often (but not always, see below) do want
  to see all functions.

- Such users will hopefully already be familiar with `C-h x' from the
  tutorial, and its general use.

- They will have to learn that you can see all functions, including
  commands, with this new command `C-h f'.

This does add some cognitive load, I agree, as does any new command, but
I think it is justified (see below).

> By contrast, what TAB TAB TAB... does inside completion for commands
> is a general feature, not similar to any other.
>
> Users will forget commands that they learned, but I think they will
> hardly forget this.

In general, I think the general idea behind the proposal is good.  But
in this case I think it is the wrong tool for the job.

Let's think about the case with experienced users, because if I'm
correct then newbies are not at first interested in functions.

More experienced users will OTOH sometimes want to complete commands,
and sometimes all functions.  With the suggested TAB behavior, there is
indeed an interface to switch between different completions.

But which you prefer to see first is highly situationally bound:
I myself would strongly prefer "all functions" when writing ELisp and
"all commands" when, e.g. sending email or for general writing.

So when writing ELisp, in comparison to today there is one more key to
press if you want to complete on functions.  This would mean that some
users would likely want to turn this behavior off.  (I would probably
end up in that camp.)  Doing that would unfortunately leave them with no
way of completing on commands only--unless they again change the option
to enable the feature.

Now, if you are a bit smart, you would of course say: well, let's just
use the correct default depending on mode!  And perhaps that would help.
But really, I do want to sometimes want to find the documentation for a
function even when writing email (perhaps I want to quote it to someone,
or perhaps I am just in the wrong window when trying to write some ELisp
in *scratch*, ugh).

So I think any model we find here really just leaves us with a
sub-optimal user interface, merely to save us the cost of one command.

Now, with the new `describe-command' command, a user could instead just
press the correct key to get the exact completion she is looking for.
In the same way, you would press `C-h v' for variables, etc.  It is dead
simple, but yes, one more command to learn (when you need it).

One final point: the need to learn a new command by heart is at least
somewhat offset by the `help-for-help' screen, conveniently available on
`C-h C-h'.  Not all commands have their keybindings this readily
available: on a screen that looks the same in all modes, and which users
will therefore hopefully learn to find and scan quicker than most other
help screens.

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

[Dmitry Gutov]

On 22.02.2021 08:23, Richard Stallman wrote:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>    > To me, it certainly sounds more complicated to learn, and harder to use,
>    > than just having two separate commands.  If your concern is complexity,
>    > the above is the more complex UI.
> 
> I am astounded by the way you see it.
> I did not expect to encounter disagreement on this point.
> 
> It seems that you are equally astounded.
> 
> I will explain why I see it the way I do.
> 
>    > - `C-h f' for any function
>    > - `C-h x' for commands
> 
> This is yet one more specific command one needs to remember.  For a
> beginner, or even a not-quite-beginner, learning hundreds of other
> commands is the hard part.  And it is easy to forget them.

I sympathize with reluctance to add new commands, especially when one is 
very similar to an existing one.

> By contrast, what TAB TAB TAB... does inside completion for commands
> is a general feature, not similar to any other.
> 
> Users will forget commands that they learned, but I think they will
> hardly forget this.

...but making a general feature (and completion-at-point is a general 
interface which we use in many context) more complex can be much worse.

TAB and 'TAB TAB' already do different things. Now, what happens if a 
third 'TAB' will switch the completion tale? The user will have to count 
how many times they pressed TAB now. Did I press it one or twice? If 
once, next press will pop up the Completions buffer, if two: switch to 
another completion table. What if I press TAB 4 times, what will happen? 
Or ok, I pressed TAB a few times, but forgot to count. Which completion 
table is it using now?

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > TAB and 'TAB TAB' already do different things. Now, what happens if a 
  > third 'TAB' will switch the completion tale? The user will have to count 
  > how many times they pressed TAB now. Did I press it one or twice?

There is no need to count.  You just keep typing TAB until you get
what you want.  When it alternates between all functions and only
commands, you'll see the number of completions change in an obvious
way.

Another advantage is that this gives you both completion spaces in
every command that reads a function name, not only in
describe-function.

We should try this and see what it is like, then judge it.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Drew Adams]

> There is no need to count.  You just keep typing TAB until you get
> what you want.  When it alternates between all functions and only
> commands, you'll see the number of completions change in an obvious
> way.
> 
> Another advantage is that this gives you both completion spaces
> in every command that reads a function name, not only in
> describe-function.
> 
> We should try this and see what it is like, then judge it.

Having a general ability to switch or transform
the domain of candidates - that is, the initial
set (after filtering with the PREDICATE arg)
before any user filtering by minibuffer input -
is indeed a fine feature.

Icicles has such a toggle, bound to `C-$' during
completion.  It toggles between using the initial
set and the initial set "transformed" in some way.

The default transformation is to remove duplicate
candidates.  (Duplicate candidates can be useful,
in general.)  A given command can define its own
transformation function for this, and bind it to
variable `icicle-transform-function'.

But for something like `C-h f', it makes sense to
have a prefix arg limit the candidates to commands.
For that, there's no need to wait for a general
transform-toggle feature.

And it makes sense to also have a separate command,
`describe-command'.  And to have a prefix arg to it
extend the candidate set to include all functions
(a reverse of the swap of the previous paragraph).
___

As for letting `TAB' switch completion tables or
otherwise transform the initial candidate set:
that too is a possibility.  I'd agree that trying
such ideas and seeing what people think can be a
useful experiment.

Personally, I'd prefer that such trials be done
in the form of 3rd-party efforts.  See what kind
of use and feedback it results in outside Emacs.

"Trials" in Emacs itself are not so great, IMO.
Someone puts something on a branch and invites
trial and feedback.  But the only people who try
it are Emacs Dev aficionados who build Emacs or
pull stuff from Git etc.  That's more for large
developments, like bidi support.

Wrt TAB as a key for this: Sure, try it.  But a
priori I'm not in favor of reusing TAB this way.
TAB should be for something that will be used a
lot and that needs to be quick.  That's not the
case here.

As an example, Icicles, like vanilla Emacs, uses
TAB to complete, but repeating TAB then cycles
among the candidates.  That's an operation that
you can repeat often and quickly.

Emacs's own binding of TAB to scroll *Completions*
is not a good key choice, IMO.  Much better for
scrolling *Completions* is to use the usual keys:
`C-v' and `M-v'.  (It's natural for them to scroll
*Completions* and not the minibuffer itself.)
Icicles does that.

But again - the kind of idea you suggested is just
what we need more of: ideas about extending or
otherwise improving user interaction with the set
of completion candidates.

And again, I agree that the right approach wrt
such ideas is for people to try them out and
provide feedback.  I'd sooner see that happen
with a 3rd-party library than with an Emacs
branch, but I suppose that's a detail. 

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > "Trials" in Emacs itself are not so great, IMO.
  > Someone puts something on a branch 

That way of tryialing something has a drawback as you say:

  > trial and feedback.  But the only people who try
  > it are Emacs Dev aficionados who build Emacs or
  > pull stuff from Git etc.

The way I suggest handling these is to put them in the release, then
tell people a command to run to try them.  That makes it easy
to try them out.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 02 Mar 2021 01:29:06 -0500
> Cc: stefan@marxist.se, 46627@debbugs.gnu.org, dgutov@yandex.ru
> 
>   > "Trials" in Emacs itself are not so great, IMO.
>   > Someone puts something on a branch 
> 
> That way of tryialing something has a drawback as you say:
> 
>   > trial and feedback.  But the only people who try
>   > it are Emacs Dev aficionados who build Emacs or
>   > pull stuff from Git etc.
> 
> The way I suggest handling these is to put them in the release, then
> tell people a command to run to try them.  That makes it easy
> to try them out.

That is only a viable option if the new feature is opt-in and doesn't
change the default behavior in any way, shape or form.  (This being an
old discussion, I no longer have a clear idea whether the above
conditions are fulfilled under your proposal.)  And having the new
feature on a branch first does not in any way contradict the trial by
a larger audience later, when the feature is released.

So I don't think I understand well enough what is the issue being
discussed here, as we already do all of that.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The way I suggest handling these is to put them in the release, then
  > > tell people a command to run to try them.  That makes it easy
  > > to try them out.

  > That is only a viable option if the new feature is opt-in and doesn't
  > change the default behavior in any way, shape or form.

We can make it work for any change.  We just need to define a command
to install the change.  That command would set up key bindings, set variables,
even redefine functions so as to enable the proposed new behavior.

It would be nice to have a command to remove the change, but that is
not essential -- killing that Emacs and starting another would do the
job.

  >   And having the new
  > feature on a branch first does not in any way contradict the trial by
  > a larger audience later, when the feature is released.

Indeed, we can.  I was responding to the point that trialing a feature
on a branch will get responses only from a limited set of people.

Drew wrote:

  > Yes, but that has another downside: what's in a release tends to
  > stick, for various reasons, including user take-up and developer
  > acceptance.

I think that is a miscommunication.  With the scheme I propose, the
code to implement some new behavior is included in a release, but the
default behavior has not been changed, and we have made no commitment
to change it.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Drew Adams]

> I was responding to the point that trialing a feature on a
> branch will get responses only from a limited set of people.
> 
> Drew wrote:
> 
>   > Yes, but that has another downside: what's in a release tends to
>   > stick, for various reasons, including user take-up and developer
>   > acceptance.
> 
> I think that is a miscommunication.  With the scheme I propose, the
> code to implement some new behavior is included in a release, but the
> default behavior has not been changed, and we have made no commitment
> to change it.

I don't think it's a misconception, as a generalization.

In practice, things that get added to Emacs, whether as
new default behavior or not, and regardless of presence
or lack of any stated or intended commitment to them,
tend to remain, I think.

I'm not saying I think your suggestion is worthless;
I'm saying I think it has this downside.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "stefan@marxist.se" <stefan@marxist.se>,
>         "46627@debbugs.gnu.org"
> 	<46627@debbugs.gnu.org>,
>         "dgutov@yandex.ru" <dgutov@yandex.ru>
> Date: Wed, 3 Mar 2021 15:26:26 +0000
> 
> In practice, things that get added to Emacs, whether as
> new default behavior or not, and regardless of presence
> or lack of any stated or intended commitment to them,
> tend to remain, I think.

Which is how it should be: "tend to remain".  If it were not so, it
would mean the Emacs developers have very poor judgment.

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

[Drew Adams]

>   > "Trials" in Emacs itself are not so great, IMO.
>   > Someone puts something on a branch
> 
> That way of tryialing something has a drawback as you say:
> 
>   > trial and feedback.  But the only people who try
>   > it are Emacs Dev aficionados who build Emacs or
>   > pull stuff from Git etc.
> 
> The way I suggest handling these is to put them in the release, then
> tell people a command to run to try them.  That makes it easy
> to try them out.

Yes, but that has another downside: what's in a release tends to stick, for various reasons, including user take-up and developer acceptance.  At that point, the question becomes who likes the new thing and who doesn't, how many do and don't.  And such "polling" or debate typically favor the (new) status quo - it's in; leave it in.  "That ship has sailed" is a sea-shanty refrain we hear quite often here.