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

classic Classic list List threaded Threaded
67 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

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

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

0001-Add-new-help-command-describe-command.patch (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Stefan Kangas <[hidden email]>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Drew Adams
In reply to this post by Stefan Kangas
> > 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').



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Drew Adams <[hidden email]>
> Date: Fri, 19 Feb 2021 18:27:05 +0000
> Cc: "[hidden email]" <[hidden email]>
>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Eli Zaretskii
> From: Stefan Kangas <[hidden email]>
> Date: Fri, 19 Feb 2021 11:42:50 -0600
> Cc: [hidden email], Lars Ingebrigtsen <[hidden email]>
>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
In reply to this post by Eli Zaretskii
Drew Adams <[hidden email]> 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?



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
In reply to this post by Eli Zaretskii
Eli Zaretskii <[hidden email]> 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?

0001-Add-new-help-command-describe-command.patch (15K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Richard Stallman
In reply to this post by Stefan Kangas
[[[ 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)





Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
Richard Stallman <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Stefan Kangas
> From: Stefan Kangas <[hidden email]>
> Date: Fri, 19 Feb 2021 21:25:27 -0600
> Cc: Lars Ingebrigtsen <[hidden email]>, "[hidden email]" <[hidden email]>
>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Stefan Kangas
> From: Stefan Kangas <[hidden email]>
> Date: Fri, 19 Feb 2021 22:10:58 -0600
> Cc: [hidden email], [hidden email]
>
> > 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.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Stefan Kangas
> From: Drew Adams <[hidden email]>
> CC: Lars Ingebrigtsen <[hidden email]>,
>         "[hidden email]"
> <[hidden email]>
> 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".



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
In reply to this post by Eli Zaretskii
Stefan Kangas <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
Lars Ingebrigtsen <[hidden email]> 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.



Reply | Threaded
Open this post in threaded view
|

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

Richard Stallman
In reply to this post by Eli Zaretskii
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)





Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Richard Stallman <[hidden email]>
> Cc: [hidden email], [hidden email], [hidden email]
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
In reply to this post by Lars Ingebrigtsen
> Date: Sat, 20 Feb 2021 14:59:24 +0200
> From: Eli Zaretskii <[hidden email]>
> Cc: [hidden email], [hidden email]
>
> > `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::.



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
In reply to this post by Richard Stallman
Richard Stallman <[hidden email]> 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.)



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> From: Stefan Kangas <[hidden email]>
> Date: Sat, 20 Feb 2021 10:39:14 -0600
> Cc: [hidden email], [hidden email], [hidden email]
>
> 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.



Reply | Threaded
Open this post in threaded view
|

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

Stefan Kangas
In reply to this post by Eli Zaretskii
Eli Zaretskii <[hidden email]> 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.

0001-Add-new-help-command-describe-command.patch (15K) Download Attachment
1234