bug#52058: 29.0.50; Confused by usage and documentation of "C-x 8 e e"

[Eli Zaretskii]

Forwarding to the bug tracker an exchange that was mistakenly held
off-list:

> From: Jonas Bernoulli <jonas@bernoul.li>
> Date: Sat, 27 Nov 2021 22:18:11 +0100
> 
> > But I'm not yet frustrated enough for C-g, so I type a second '?',
> > hoping to see the manual, and is presented with the following:
> >
> >   emoji--command-Emoji is an interactive compiled Lisp function.
> >
> >   (emoji--command-Emoji)
> >
> >   Not documented.
> >
> >     This function is for interactive use only.
> >
> > Where's my promised "manual"?
> 
> If you press "? ?" in the magit-diff transient, then that shows you the
> man-page for git-diff.  Similarly if you typed "? - s", then that shows
> you do the same man-page but also jumps to the line where the
> documentation for the "--stat" argument begins.  This works because the
> definition of the magit-diff transient sets :man-page "git-diff".

I expected it to show me something about using this feature, not about
an external command or somesuch.  That's because my main confusion was
about how to use "C-x 8 e e" for inserting Emoji, and because "?" in
Emacs usually shows some helpful usage information.  For example, type
"M-$" and then "?" -- this is what I expected to be presented with.

> Transient definitions can alternatively set :info-manual.  If there is
> an info node for the emoji feature, then this issue could be addressed
> by setting :info-manual "(emacs)Emoji" in all the generated transient
> prefixes and sub-prefixes.  The generated "insert this particular emoji"
> suffixes should probably have a generated doc-string along the lines of
> "Insert 🤗.\nFor more information see info node (emacs)Emoji and info
> node (transient)".

Sending the user to the manual is only useful after showing some
minimal usage information that allows to proceed without reading the
manual.  "Insert 🤗." might qualify as "good enough", but in the case
of "C-x 8 e e", the display you are presented with hints that a
single key will not be enough to insert a specific Emoji, so a short
text explaining how to select one emoticon from the shown list would
be better.  This is what I expected to see, and that is why I was
disappointed by what I actually saw.

> Similarly the usage information that one gets after pressing just "?":
> 
>   Type a <KEY> to show help for that suffix command, or ? to show manual.
>   Type C-g to exit help.

That text is actually completely impenetrable.  What is <KEY>? if it's
any key, then, as I reported, the response to typing at least some
keys confuses even more.  If it's only one of a specific set of keys,
something should tell the users which KEYs will result in useful
responses.  And what is "suffix command"? that is not a usual Emacs
terminology, so it just muddies the waters.

> could be extended with an additional line:
> 
>   Type <f1> to show information about such transient interfaces.

Mentioning "transient" here would be a didactic mistake, IMO: the user
doesn't necessarily know what that is about, and the usual meaning of
that word will definitely confuse even more.