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?