unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / Atom feed
* bug#46627: [PATCH] Add new help command 'describe-command'
@ 2021-02-19  1:06 Stefan Kangas
  2021-02-19  8:42 ` Eli Zaretskii
                   ` (2 more replies)
  0 siblings, 3 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-19  1:06 UTC (permalink / raw)
  To: 46627

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


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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19  1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
@ 2021-02-19  8:42 ` Eli Zaretskii
  2021-02-19 17:42   ` Stefan Kangas
  2021-02-19 13:12 ` Lars Ingebrigtsen
  2021-02-20  6:56 ` Richard Stallman
  2 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-19  8:42 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19  1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
  2021-02-19  8:42 ` Eli Zaretskii
@ 2021-02-19 13:12 ` Lars Ingebrigtsen
  2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
  2021-02-20  6:56 ` Richard Stallman
  2 siblings, 1 reply; 65+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-19 13:12 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19  8:42 ` Eli Zaretskii
@ 2021-02-19 17:42   ` Stefan Kangas
  2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
                       ` (5 more replies)
  0 siblings, 6 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-19 17:42 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Lars Ingebrigtsen, 46627

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


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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 13:12 ` Lars Ingebrigtsen
@ 2021-02-19 18:27   ` Drew Adams
  2021-02-19 18:43     ` Eli Zaretskii
                       ` (2 more replies)
  0 siblings, 3 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-19 18:27 UTC (permalink / raw)
  To: Lars Ingebrigtsen, Stefan Kangas; +Cc: 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
@ 2021-02-19 18:38     ` Drew Adams
  2021-02-20  3:25       ` Stefan Kangas
  2021-02-19 20:05     ` Eli Zaretskii
                       ` (4 subsequent siblings)
  5 siblings, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-19 18:38 UTC (permalink / raw)
  To: Stefan Kangas, Eli Zaretskii; +Cc: Lars Ingebrigtsen, 46627

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

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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
@ 2021-02-19 18:43     ` Eli Zaretskii
  2021-02-21  6:18     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  2 siblings, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-19 18:43 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
  2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
@ 2021-02-19 20:05     ` Eli Zaretskii
  2021-02-20  4:10       ` Stefan Kangas
  2021-02-20 12:56     ` Lars Ingebrigtsen
                       ` (3 subsequent siblings)
  5 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-19 20:05 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
@ 2021-02-20  3:25       ` Stefan Kangas
  2021-02-20  4:25         ` Drew Adams
  2021-02-20  7:44         ` Eli Zaretskii
  0 siblings, 2 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20  3:25 UTC (permalink / raw)
  To: Drew Adams, Eli Zaretskii; +Cc: Lars Ingebrigtsen, 46627

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?





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 20:05     ` Eli Zaretskii
@ 2021-02-20  4:10       ` Stefan Kangas
  2021-02-20  8:18         ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20  4:10 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, 46627

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


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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  3:25       ` Stefan Kangas
@ 2021-02-20  4:25         ` Drew Adams
  2021-02-20  8:20           ` Eli Zaretskii
  2021-02-20  7:44         ` Eli Zaretskii
  1 sibling, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-20  4:25 UTC (permalink / raw)
  To: Stefan Kangas, Eli Zaretskii; +Cc: Lars Ingebrigtsen, 46627

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

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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19  1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
  2021-02-19  8:42 ` Eli Zaretskii
  2021-02-19 13:12 ` Lars Ingebrigtsen
@ 2021-02-20  6:56 ` Richard Stallman
  2021-02-20  7:14   ` Stefan Kangas
  2 siblings, 1 reply; 65+ messages in thread
From: Richard Stallman @ 2021-02-20  6:56 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  6:56 ` Richard Stallman
@ 2021-02-20  7:14   ` Stefan Kangas
  2021-02-21  6:19     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  0 siblings, 2 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20  7:14 UTC (permalink / raw)
  To: rms; +Cc: 46627

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.





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  3:25       ` Stefan Kangas
  2021-02-20  4:25         ` Drew Adams
@ 2021-02-20  7:44         ` Eli Zaretskii
  1 sibling, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20  7:44 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  4:10       ` Stefan Kangas
@ 2021-02-20  8:18         ` Eli Zaretskii
  2021-02-20 17:10           ` Stefan Kangas
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20  8:18 UTC (permalink / raw)
  To: Stefan Kangas, Stefan Monnier; +Cc: larsi, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  4:25         ` Drew Adams
@ 2021-02-20  8:20           ` Eli Zaretskii
  0 siblings, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20  8:20 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
  2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
  2021-02-19 20:05     ` Eli Zaretskii
@ 2021-02-20 12:56     ` Lars Ingebrigtsen
  2021-02-20 12:59       ` Eli Zaretskii
  2021-02-20 14:04       ` Stefan Kangas
  2021-02-20 16:06     ` Richard Stallman
                       ` (2 subsequent siblings)
  5 siblings, 2 replies; 65+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-20 12:56 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 12:56     ` Lars Ingebrigtsen
@ 2021-02-20 12:59       ` Eli Zaretskii
  2021-02-20 16:16         ` Eli Zaretskii
  2021-02-20 14:04       ` Stefan Kangas
  1 sibling, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 12:59 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: stefan, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 12:56     ` Lars Ingebrigtsen
  2021-02-20 12:59       ` Eli Zaretskii
@ 2021-02-20 14:04       ` Stefan Kangas
  1 sibling, 0 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20 14:04 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 46627

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.





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
                       ` (2 preceding siblings ...)
  2021-02-20 12:56     ` Lars Ingebrigtsen
@ 2021-02-20 16:06     ` Richard Stallman
  2021-02-20 16:09       ` Eli Zaretskii
  2021-02-20 16:39       ` Stefan Kangas
  2021-02-21  6:10     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  5 siblings, 2 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-20 16:06 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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)







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:06     ` Richard Stallman
@ 2021-02-20 16:09       ` Eli Zaretskii
  2021-02-20 20:06         ` bug#46627: [External] : " Drew Adams
  2021-02-20 16:39       ` Stefan Kangas
  1 sibling, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 16:09 UTC (permalink / raw)
  To: rms; +Cc: larsi, stefan, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 12:59       ` Eli Zaretskii
@ 2021-02-20 16:16         ` Eli Zaretskii
  0 siblings, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 16:16 UTC (permalink / raw)
  To: larsi; +Cc: stefan, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:06     ` Richard Stallman
  2021-02-20 16:09       ` Eli Zaretskii
@ 2021-02-20 16:39       ` Stefan Kangas
  2021-02-20 16:49         ` Eli Zaretskii
                           ` (2 more replies)
  1 sibling, 3 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20 16:39 UTC (permalink / raw)
  To: rms; +Cc: larsi, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:39       ` Stefan Kangas
@ 2021-02-20 16:49         ` Eli Zaretskii
  2021-02-20 20:35           ` bug#46627: [External] : " Drew Adams
  2021-02-21  6:19         ` Richard Stallman
  2021-02-21  6:27         ` Richard Stallman
  2 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 16:49 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  8:18         ` Eli Zaretskii
@ 2021-02-20 17:10           ` Stefan Kangas
  2021-02-21 13:08             ` Lars Ingebrigtsen
  2021-02-22 15:58             ` Eli Zaretskii
  0 siblings, 2 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-20 17:10 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Monnier; +Cc: larsi, 46627

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


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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:09       ` Eli Zaretskii
@ 2021-02-20 20:06         ` Drew Adams
  2021-02-20 20:17           ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-20 20:06 UTC (permalink / raw)
  To: Eli Zaretskii, rms; +Cc: larsi, stefan, 46627

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






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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 20:06         ` bug#46627: [External] : " Drew Adams
@ 2021-02-20 20:17           ` Eli Zaretskii
  2021-02-20 20:54             ` Drew Adams
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 20:17 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:49         ` Eli Zaretskii
@ 2021-02-20 20:35           ` Drew Adams
  2021-02-20 20:46             ` Eli Zaretskii
  2021-02-26 21:34             ` Drew Adams
  0 siblings, 2 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-20 20:35 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Kangas; +Cc: larsi, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 20:35           ` bug#46627: [External] : " Drew Adams
@ 2021-02-20 20:46             ` Eli Zaretskii
  2021-02-20 21:16               ` Drew Adams
  2021-02-26 21:34             ` Drew Adams
  1 sibling, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-20 20:46 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 20:17           ` Eli Zaretskii
@ 2021-02-20 20:54             ` Drew Adams
  0 siblings, 0 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-20 20:54 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 20:46             ` Eli Zaretskii
@ 2021-02-20 21:16               ` Drew Adams
  2021-02-21 15:07                 ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-20 21:16 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
                       ` (3 preceding siblings ...)
  2021-02-20 16:06     ` Richard Stallman
@ 2021-02-21  6:10     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  5 siblings, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:10 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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







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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
  2021-02-19 18:43     ` Eli Zaretskii
@ 2021-02-21  6:18     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  2 siblings, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:18 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  7:14   ` Stefan Kangas
@ 2021-02-21  6:19     ` Richard Stallman
  2021-02-21  6:27     ` Richard Stallman
  1 sibling, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:19 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:39       ` Stefan Kangas
  2021-02-20 16:49         ` Eli Zaretskii
@ 2021-02-21  6:19         ` Richard Stallman
  2021-02-21  7:18           ` Stefan Kangas
  2021-02-21 13:06           ` Lars Ingebrigtsen
  2021-02-21  6:27         ` Richard Stallman
  2 siblings, 2 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:19 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 17:42   ` Stefan Kangas
                       ` (4 preceding siblings ...)
  2021-02-21  6:10     ` Richard Stallman
@ 2021-02-21  6:27     ` Richard Stallman
  5 siblings, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:27 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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







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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
  2021-02-19 18:43     ` Eli Zaretskii
  2021-02-21  6:18     ` Richard Stallman
@ 2021-02-21  6:27     ` Richard Stallman
  2 siblings, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:27 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20  7:14   ` Stefan Kangas
  2021-02-21  6:19     ` Richard Stallman
@ 2021-02-21  6:27     ` Richard Stallman
  2021-02-21  7:17       ` Stefan Kangas
  1 sibling, 1 reply; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:27 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 16:39       ` Stefan Kangas
  2021-02-20 16:49         ` Eli Zaretskii
  2021-02-21  6:19         ` Richard Stallman
@ 2021-02-21  6:27         ` Richard Stallman
  2 siblings, 0 replies; 65+ messages in thread
From: Richard Stallman @ 2021-02-21  6:27 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  6:27     ` Richard Stallman
@ 2021-02-21  7:17       ` Stefan Kangas
  2021-02-22  6:23         ` Richard Stallman
  0 siblings, 1 reply; 65+ messages in thread
From: Stefan Kangas @ 2021-02-21  7:17 UTC (permalink / raw)
  To: rms; +Cc: 46627

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.





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  6:19         ` Richard Stallman
@ 2021-02-21  7:18           ` Stefan Kangas
  2021-02-21 15:27             ` Eli Zaretskii
  2021-02-21 17:33             ` Drew Adams
  2021-02-21 13:06           ` Lars Ingebrigtsen
  1 sibling, 2 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-21  7:18 UTC (permalink / raw)
  To: rms; +Cc: larsi, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  6:19         ` Richard Stallman
  2021-02-21  7:18           ` Stefan Kangas
@ 2021-02-21 13:06           ` Lars Ingebrigtsen
  1 sibling, 0 replies; 65+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-21 13:06 UTC (permalink / raw)
  To: Richard Stallman; +Cc: Stefan Kangas, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 17:10           ` Stefan Kangas
@ 2021-02-21 13:08             ` Lars Ingebrigtsen
  2021-02-22 15:58             ` Eli Zaretskii
  1 sibling, 0 replies; 65+ messages in thread
From: Lars Ingebrigtsen @ 2021-02-21 13:08 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: Stefan Monnier, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 21:16               ` Drew Adams
@ 2021-02-21 15:07                 ` Eli Zaretskii
  2021-02-21 17:55                   ` Drew Adams
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 15:07 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  7:18           ` Stefan Kangas
@ 2021-02-21 15:27             ` Eli Zaretskii
  2021-02-21 16:39               ` Howard Melman
                                 ` (2 more replies)
  2021-02-21 17:33             ` Drew Adams
  1 sibling, 3 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 15:27 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, rms, 46627

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






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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 15:27             ` Eli Zaretskii
@ 2021-02-21 16:39               ` Howard Melman
  2021-02-21 18:01                 ` bug#46627: [External] : " Drew Adams
  2021-02-21 17:01               ` Stefan Kangas
  2021-02-21 17:57               ` bug#46627: [External] : " Drew Adams
  2 siblings, 1 reply; 65+ messages in thread
From: Howard Melman @ 2021-02-21 16:39 UTC (permalink / raw)
  To: 46627


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






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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 15:27             ` Eli Zaretskii
  2021-02-21 16:39               ` Howard Melman
@ 2021-02-21 17:01               ` Stefan Kangas
  2021-02-21 17:36                 ` Eli Zaretskii
  2021-02-21 17:57               ` bug#46627: [External] : " Drew Adams
  2 siblings, 1 reply; 65+ messages in thread
From: Stefan Kangas @ 2021-02-21 17:01 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, rms, 46627

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.





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  7:18           ` Stefan Kangas
  2021-02-21 15:27             ` Eli Zaretskii
@ 2021-02-21 17:33             ` Drew Adams
  1 sibling, 0 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-21 17:33 UTC (permalink / raw)
  To: Stefan Kangas, rms; +Cc: larsi, 46627

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

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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 17:01               ` Stefan Kangas
@ 2021-02-21 17:36                 ` Eli Zaretskii
  2021-02-21 18:02                   ` Stefan Kangas
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 17:36 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 15:07                 ` Eli Zaretskii
@ 2021-02-21 17:55                   ` Drew Adams
  2021-02-21 18:11                     ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-21 17:55 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, stefan, rms, 46627

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






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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 15:27             ` Eli Zaretskii
  2021-02-21 16:39               ` Howard Melman
  2021-02-21 17:01               ` Stefan Kangas
@ 2021-02-21 17:57               ` Drew Adams
  2 siblings, 0 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-21 17:57 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Kangas; +Cc: larsi, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 16:39               ` Howard Melman
@ 2021-02-21 18:01                 ` Drew Adams
  0 siblings, 0 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-21 18:01 UTC (permalink / raw)
  To: Howard Melman, 46627

+1.  Well put.






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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 17:36                 ` Eli Zaretskii
@ 2021-02-21 18:02                   ` Stefan Kangas
  2021-02-21 18:21                     ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Stefan Kangas @ 2021-02-21 18:02 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, rms, 46627

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.





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 17:55                   ` Drew Adams
@ 2021-02-21 18:11                     ` Eli Zaretskii
  2021-02-21 18:30                       ` Drew Adams
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 18:11 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 18:02                   ` Stefan Kangas
@ 2021-02-21 18:21                     ` Eli Zaretskii
  2021-02-21 19:57                       ` Dmitry Gutov
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 18:21 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, rms, 46627

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





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 18:11                     ` Eli Zaretskii
@ 2021-02-21 18:30                       ` Drew Adams
  0 siblings, 0 replies; 65+ messages in thread
From: Drew Adams @ 2021-02-21 18:30 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 18:21                     ` Eli Zaretskii
@ 2021-02-21 19:57                       ` Dmitry Gutov
  2021-02-21 20:13                         ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Dmitry Gutov @ 2021-02-21 19:57 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Kangas; +Cc: larsi, rms, 46627

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.





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 19:57                       ` Dmitry Gutov
@ 2021-02-21 20:13                         ` Eli Zaretskii
  2021-02-21 23:46                           ` Dmitry Gutov
  0 siblings, 1 reply; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-21 20:13 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 20:13                         ` Eli Zaretskii
@ 2021-02-21 23:46                           ` Dmitry Gutov
  2021-02-22 15:18                             ` Eli Zaretskii
  0 siblings, 1 reply; 65+ messages in thread
From: Dmitry Gutov @ 2021-02-21 23:46 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: larsi, stefan, rms, 46627

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.





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21  7:17       ` Stefan Kangas
@ 2021-02-22  6:23         ` Richard Stallman
  2021-02-24  3:28           ` Stefan Kangas
  0 siblings, 1 reply; 65+ messages in thread
From: Richard Stallman @ 2021-02-22  6:23 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 46627

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







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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-21 23:46                           ` Dmitry Gutov
@ 2021-02-22 15:18                             ` Eli Zaretskii
  0 siblings, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-22 15:18 UTC (permalink / raw)
  To: Dmitry Gutov; +Cc: larsi, stefan, rms, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 17:10           ` Stefan Kangas
  2021-02-21 13:08             ` Lars Ingebrigtsen
@ 2021-02-22 15:58             ` Eli Zaretskii
  1 sibling, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-22 15:58 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: larsi, monnier, 46627

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





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

* bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-22  6:23         ` Richard Stallman
@ 2021-02-24  3:28           ` Stefan Kangas
  0 siblings, 0 replies; 65+ messages in thread
From: Stefan Kangas @ 2021-02-24  3:28 UTC (permalink / raw)
  To: rms; +Cc: 46627

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.





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-20 20:35           ` bug#46627: [External] : " Drew Adams
  2021-02-20 20:46             ` Eli Zaretskii
@ 2021-02-26 21:34             ` Drew Adams
  2021-02-27  8:04               ` Eli Zaretskii
  1 sibling, 1 reply; 65+ messages in thread
From: Drew Adams @ 2021-02-26 21:34 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Kangas; +Cc: larsi, rms, 46627

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.





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

* bug#46627: [External] : bug#46627: [PATCH] Add new help command 'describe-command'
  2021-02-26 21:34             ` Drew Adams
@ 2021-02-27  8:04               ` Eli Zaretskii
  0 siblings, 0 replies; 65+ messages in thread
From: Eli Zaretskii @ 2021-02-27  8:04 UTC (permalink / raw)
  To: Drew Adams; +Cc: larsi, stefan, rms, 46627

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





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

end of thread, other threads:[~2021-02-27  8:04 UTC | newest]

Thread overview: 65+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-19  1:06 bug#46627: [PATCH] Add new help command 'describe-command' Stefan Kangas
2021-02-19  8:42 ` Eli Zaretskii
2021-02-19 17:42   ` Stefan Kangas
2021-02-19 18:38     ` bug#46627: [External] : " Drew Adams
2021-02-20  3:25       ` Stefan Kangas
2021-02-20  4:25         ` Drew Adams
2021-02-20  8:20           ` Eli Zaretskii
2021-02-20  7:44         ` Eli Zaretskii
2021-02-19 20:05     ` Eli Zaretskii
2021-02-20  4:10       ` Stefan Kangas
2021-02-20  8:18         ` Eli Zaretskii
2021-02-20 17:10           ` Stefan Kangas
2021-02-21 13:08             ` Lars Ingebrigtsen
2021-02-22 15:58             ` Eli Zaretskii
2021-02-20 12:56     ` Lars Ingebrigtsen
2021-02-20 12:59       ` Eli Zaretskii
2021-02-20 16:16         ` Eli Zaretskii
2021-02-20 14:04       ` Stefan Kangas
2021-02-20 16:06     ` Richard Stallman
2021-02-20 16:09       ` Eli Zaretskii
2021-02-20 20:06         ` bug#46627: [External] : " Drew Adams
2021-02-20 20:17           ` Eli Zaretskii
2021-02-20 20:54             ` Drew Adams
2021-02-20 16:39       ` Stefan Kangas
2021-02-20 16:49         ` Eli Zaretskii
2021-02-20 20:35           ` bug#46627: [External] : " Drew Adams
2021-02-20 20:46             ` Eli Zaretskii
2021-02-20 21:16               ` Drew Adams
2021-02-21 15:07                 ` Eli Zaretskii
2021-02-21 17:55                   ` Drew Adams
2021-02-21 18:11                     ` Eli Zaretskii
2021-02-21 18:30                       ` Drew Adams
2021-02-26 21:34             ` Drew Adams
2021-02-27  8:04               ` Eli Zaretskii
2021-02-21  6:19         ` Richard Stallman
2021-02-21  7:18           ` Stefan Kangas
2021-02-21 15:27             ` Eli Zaretskii
2021-02-21 16:39               ` Howard Melman
2021-02-21 18:01                 ` bug#46627: [External] : " Drew Adams
2021-02-21 17:01               ` Stefan Kangas
2021-02-21 17:36                 ` Eli Zaretskii
2021-02-21 18:02                   ` Stefan Kangas
2021-02-21 18:21                     ` Eli Zaretskii
2021-02-21 19:57                       ` Dmitry Gutov
2021-02-21 20:13                         ` Eli Zaretskii
2021-02-21 23:46                           ` Dmitry Gutov
2021-02-22 15:18                             ` Eli Zaretskii
2021-02-21 17:57               ` bug#46627: [External] : " Drew Adams
2021-02-21 17:33             ` Drew Adams
2021-02-21 13:06           ` Lars Ingebrigtsen
2021-02-21  6:27         ` Richard Stallman
2021-02-21  6:10     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-19 13:12 ` Lars Ingebrigtsen
2021-02-19 18:27   ` bug#46627: [External] : " Drew Adams
2021-02-19 18:43     ` Eli Zaretskii
2021-02-21  6:18     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-20  6:56 ` Richard Stallman
2021-02-20  7:14   ` Stefan Kangas
2021-02-21  6:19     ` Richard Stallman
2021-02-21  6:27     ` Richard Stallman
2021-02-21  7:17       ` Stefan Kangas
2021-02-22  6:23         ` Richard Stallman
2021-02-24  3:28           ` Stefan Kangas

unofficial mirror of bug-gnu-emacs@gnu.org 

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://yhetil.org/emacs-bugs/0 emacs-bugs/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 emacs-bugs emacs-bugs/ https://yhetil.org/emacs-bugs \
		bug-gnu-emacs@gnu.org
	public-inbox-index emacs-bugs

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.yhetil.org/yhetil.emacs.bugs
	nntp://news.gmane.io/gmane.emacs.bugs


AGPL code for this site: git clone http://ou63pmih66umazou.onion/public-inbox.git