RE: help-fns.el patch for commands to describe options and commands

["Drew Adams" <drew.adams@oracle.com>]

>     Attached is a patch for help-fns.el. It modifies
>     `describe-function' and `describe-variable', so that a
>     prefix arg means that candidates are commands
>     and user options, respectively. So `C-u C-h f' shows and
>     accepts only commands as completion candidates, and
>     `C-u C-h v' shows and accepts only user options for completion.
>
> That doesn't sound very useful to me.  What is the benefit it
> seeks to provide? Only to limit completion?

Yes. When you are looking for a command, you don't want to see a zillion
non-interactive functions as candidates. This cuts down that noise
*considerably*.

Users who don't fiddle with Emacs Lisp want to know about commands more
often than non-interactive functions. Same thing for user options - they
want to know what options might be available for controlling this or that.
They don't want to see zillions of internal variable names - quel horreur !
And there are many *more* internal names than external, end-user names -
double the insult.

Give them only what they are interested in - less noise. (And "them" is also
us. Don't you sometimes want to know about a command or option?)

> I won't object to installing it, but I do not want to document it in
> the Emacs Manual, because it isn't worth the paper.

OK. Anyway, I guarantee it'll eventually be a faq on Emacs Wiki (and without
me putting it there). One way or the other, people will find it and use it
and pass the knowledge along. If they learn anything about help, this will
be it. This is a stupid-simple feature, but it should have been there all
along, IMO.

>     In addition, for convenience, two new commands are defined to
>     do the same thing without `C-u': `describe-command' and
>     `describe-option'. This is especially useful for newbies, who
>     might search for something that describes a command or an option.
>
> I don't think this is is going to be useful for newbies.  They won't
> learn these commands.

Reason?  Why not useful?  Why not learnable?

Will they not learn these because they are not bound to keys? How about
binding them? An end user is more interested in describing commands and
options than arbitrary functions and variables, so you could even argue that
these deserve bindings more than `describe-function' and `describe-variable'
(I don't argue that, however).

I'd rather see `C-h c' for `describe-command' and `C-h o' for
`describe-option'. I'd move `describe-key-briefly' to `C-u C-h k' (but,
then, I never use it). [No, we need not have a war over particular bindings;
I just wanted to claim that this is useful to newbies and it could warrant
bindings.]

We go to the trouble (since day 1, in fact) of providing a dedicated command
and key binding for apropos of commands (only). How is this different? By
your logic, we should remove `command-apropos' and give users just
`apropos'.

> If they remember anything relevant it will be
> C-h f and C-h v.  C-h f works with commands just as with
> noninteractive functions; C-h v works with user options just as with
> other variables.

Which is fine if you want that generality. And not fine if you have a
narrower focus.

> If you are saying that you think some newbies will type M-x
> describe-command to look for a command, I think that will be quite
> rare.  If we want to make that work, the simplest way is to alias
> describe-command to describe-function.

If someone wants to find a command, why would you give him only a way to
find all functions? By that logic, give him only one command that describes
all functions and variables, with all of their names available at once for
completion. Why help the user by distinguishing which are functions and
which are variables?

The point is to give users a tool that narrows the possibilities, that from
the beginning weeds out candidates that they know they don't want (in a
particular context). If I want to know about an option, then I don't want
the added noise of internal variable names. When the user has a focus, s?he
wants a tool that respects that focus.

The other point was that these command names say what they do, so a user
looking for something that describes commands is more likely to find
`describe-command' than `describe-function'. Try `M-x apropos describe
command' - nada. Now try `M-x apropos describe function'. OK, try `C-h a
describe function'. Repeat for `option' and `variable'.

And an absolute beginner might not even imagine that an editor command is a
"function" in Emacs. Open TextPad or (shudder) Notepad or another typical
end-user text editor. Go into the Help and search for "function". Now search
for "command". Do you see the difference in hits? Go to
http://en.wikipedia.org/wiki/Text_editor and search for "function", then
"command" - 2 hits vs 14, and those 2 are not really about functions that
are commands. But Emacs is for programmers, you say? Go to
http://en.wikipedia.org/wiki/Vi and count again: 0 hits for "function", 51
for "command". Moral: an Emacs newbie will look for commands to do things,
not functions.

Yes, your aliasing would take care of that part - but not the
noise-reduction part.