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

[Stefan Kangas]

Richard Stallman <rms@gnu.org> writes:

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

Thank you, I will add my thoughts below.

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

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

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

Here is how I approach this problem:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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