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

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

[Eli Zaretskii]

I did:

  emacs -Q
  C-x 8 e e

This pops up a window with a list of Emoji categories and the
respective Emoji.  It looks like a normal popup window Emacs shows,
for example *Help* or a list of completion candidates, so I just typed
<UP> arrow to dismiss it as I'm used to.  (Or maybe I expected the
arrow keys to allow selection of categories?)  This displays the
following message in the echo-area:

  Unbound suffix: ‘<up>’ (Use ‘C-g’ to abort, ‘?’ for help) [previous-line]

Tried some other keys with a similar effect.  (What is "suffix", and
"unbound" on top of that?)  So finally, I press '?', hoping it will
show me the light.  This gets me the following:

  Type a <KEY> to show help for that suffix command, or ? to show manual.
  Type C-g to exit help.

Tried to type some <KEY>.  For example, 'a'.  This produces:

  emoji--command-Emoji\ >\ Animals\ &\ Nature is an interactive compiled
  Lisp function.

  (emoji--command-Emoji\ >\ Animals\ &\ Nature)

  Not documented.

    This function is for interactive use only.

Hmm... not very helpful, as I still don't understand how to do
something useful here.  "Not documented"? hmm...

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"?

So, bottom line, I think it would be mighty good to make this
interface more user-friendly, so that it at least describes what
<KEY>s one can type to produce something useful.  And if it promises a
"manual", please make it show something to that effect...

In GNU Emacs 29.0.50 (build 210, i686-pc-mingw32)
 of 2021-11-23 built on HOME-C4E4A596F7
Repository revision: 8b62b20159f8ec3f5c7ea5227f814681741d61b1
Repository branch: master
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
System Description: Microsoft Windows XP Service Pack 3 (v5.1.0.2600)

Configured using:
 'configure -C --prefix=/d/usr --with-wide-int
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -gdwarf-4 -g3''

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NOTIFY
W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS WEBP
XPM ZLIB

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message mailcap yank-media rmc puny
dired dired-loaddefs rfc822 mml mml-sec epa derived epg rfc6068
epg-config gnus-util rmail rmail-loaddefs auth-source password-cache
json map time-date mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils eieio-opt speedbar ezimage dframe
find-func shortdoc text-property-search help-fns radix-tree emoji-labels
emoji transient cl-seq format-spec edmacro kmacro eieio eieio-core
cl-macs eieio-loaddefs cl-extra seq gv subr-x byte-opt bytecomp
byte-compile cconv help-mode cl-loaddefs cl-lib iso-transl tooltip eldoc
paren electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode
mwheel dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars
term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice button
loaddefs faces cus-face macroexp files window text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads w32notify w32 lcms2 multi-tty
make-network-process emacs)

Memory information:
((conses 16 128507 10597)
 (symbols 48 12084 1)
 (strings 16 51322 3299)
 (string-bytes 1 1264079)
 (vectors 16 24397)
 (vector-slots 8 320035 12877)
 (floats 8 74 75)
 (intervals 40 8376 93)
 (buffers 888 11))

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> It looks like a normal popup window Emacs shows,
> for example *Help* or a list of completion candidates, so I just typed
> <UP> arrow to dismiss it as I'm used to.

Yes, it's transient.el -- it's a different interface.

> Hmm... not very helpful, as I still don't understand how to do
> something useful here.  "Not documented"? hmm...

Should probably have some doc strings, yes...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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.