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

[Eli Zaretskii]

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