[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#52058: 29.0.50; Confused by usage and documentation of "C-x 8 e e"
From: |
Eli Zaretskii |
Subject: |
bug#52058: 29.0.50; Confused by usage and documentation of "C-x 8 e e" |
Date: |
Sun, 28 Nov 2021 17:11:32 +0200 |
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.