bug#61227: 29.0.60; Customize UI for customization of keys

[Eli Zaretskii]

To reproduce, try to customize any variable whose value should be a
key.  For example:

  emacs -Q
  M-x load-library RET repeat RET
  M-x customize-variable RET repeat-exit-key RET

You are now presented with the Customize UI, where the Value Menu
shows two possibilities:

   No special key to exit repeating sequence
   Kbd keys that exit repeating sequence

Click on the second one, and Emacs displays an editable field:

   Kbd keys that exit repeating sequence: _______________________

Now what?  It is completely unclear how to specify a key for this
customization.  I tried to type the key I wanted (which was RET) as a
quoted character: "C-q RET" (which is already quite tricky).  That
says in the minibuffer

  Key <return> is translated to RET -- use RET? (y or n)

Pressing 'y' then inserts "RET" into the field, but trying to set this
customization for the current session produces an error message:

  Invalid key: "RET "

And I'm somehow expected to guess that I need to remove the trailing
blank.  It took me a while...

If you are an Emacs hacker, you might be able to look in the sources
and see this:

  (defcustom repeat-exit-key nil
    "Key that stops the modal repeating of keys in sequence.
  For example, you can set it to <return> like `isearch-exit'."
    :type '(choice (const :tag "No special key to exit repeating sequence" nil)
                   (key :tag "Kbd keys that exit repeating sequence"))
                    ^^^

which will tell you that the custom type here is 'key'.  The look it
up in the ELisp manual:

  ‘key’
       The value is a valid key according to ‘key-valid-p’, and suitable
       for use with, for example ‘keymap-set’.

Then call up the documentation of key-valid-p and see this:

  (key-valid-p KEYS)

  Say whether KEYS is a valid key.
  A key is a string consisting of one or more key strokes.
  The key strokes are separated by single space characters.

And now we finally know what is expected: a _string_ that describes a
key.  So, for example, if you want RET as the key, you need to type
the literal string "<RET>" (without the quotes.

My questions are: is this a reasonable UI for easy customization?  Do
we really expect our users to guess how to specify keys in this
situation?  Wouldn't it be better if some hint(s) to that effect were
displayed by Custom?


In GNU Emacs 29.0.60 (build 268, i686-pc-mingw32) of 2023-02-02 built on
 HOME-C4E4A596F7
Repository revision: be304bb3286eb27e1aa8248eb3904925ed73dfcb
Repository branch: emacs-29
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 SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

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

Major mode: Custom

Minor modes in effect:
  tooltip-mode: t
  global-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
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message mailcap yank-media puny dired
dired-loaddefs rfc822 mml mml-sec password-cache epa derived epg rfc6068
epg-config gnus-util text-property-search time-date subr-x mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils tabify
repeat find-func thingatpt help-fns radix-tree help-mode cus-edit pp
cus-start cus-load icons wid-edit cl-loaddefs cl-lib rmc iso-transl
tooltip cconv 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 nadvice seq simple cl-generic
indonesian philippine 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 abbrev obarray oclosure cl-preloaded button loaddefs
theme-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 67786 12255)
 (symbols 48 8168 0)
 (strings 16 22174 3089)
 (string-bytes 1 536088)
 (vectors 16 11452)
 (vector-slots 8 166311 16003)
 (floats 8 31 23)
 (intervals 40 384 92)
 (buffers 888 13))