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

Previous Next

To reply to this bug, email your comments to 52058 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; Confused by usage and documentation of "C-x 8 e e"
Date: Tue, 23 Nov 2021 16:11:05 +0200

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

Message #8 received at 52058 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Jonas Bernoulli <jonas <at> bernoul.li>, 52058 <at> debbugs.gnu.org
Subject: Re: bug#52058: 29.0.50; Confused by usage and documentation of "C-x
 8 e e"
Date: Wed, 24 Nov 2021 08:46:47 +0100

Eli Zaretskii <eliz <at> 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

Message #11 received at 52058 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jonas Bernoulli <jonas <at> bernoul.li>
Cc: 52058 <at> debbugs.gnu.org
Subject: Re: 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 <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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.