GNU bug report logs -
#52058
29.0.50; Confused by usage and documentation of "C-x 8 e e"
Previous Next
Full log
Message #11 received at 52058 <at> debbugs.gnu.org (full text, mbox):
Forwarding to the bug tracker an exchange that was mistakenly held
off-list:
> From: Jonas Bernoulli <jonas <at> 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.
This bug report was last modified 3 years and 256 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.