Re: emacs-28 56026242e4: Explain how to bind keys to non-ASCII sequences

[Robert Pluim <rpluim@gmail.com>]

>>>>> On Mon, 14 Nov 2022 19:40:35 -0800, Stefan Kangas <stefankangas@gmail.com> said:

    Stefan> This section has changed quite a bit on master, including using
    Stefan> `keymap-global-set' instead.  Unfortunately, I'm not sure what if
    Stefan> anything needs adding to the text already on master.  Could you please
    Stefan> look into it, or even help merge it?

Well this has opened a can of worms:

Item the first:

    (keymap-global-set "C-c h" "h") => [104]

    (keymap-global-set "C-c h" "hello") => 

    Debugger entered--Lisp error: (error "\"hello\" is not a valid key definition; see `key-va...")
      signal(error ("\"hello\" is not a valid key definition; see `key-va..."))
      error("%S is not a valid key definition; see `key-valid-p..." "hello")
      keymap--check("hello")
      keymap-set((keymap #^[nil nil keymap 
      keymap-global-set("C-c h" "hello")

    (keymap-global-set "C-c h" (kbd "hello")) => same

    (keymap-global-set "C-c h" "h e l l o") => [104 101 108 108 111]

    But:

    (keymap-global-set "C-c h" (kbd "olá"))  => [111 108 225]

I think itʼs a bug (and a regression from `global-set-key') to require
that what weʼre binding a key to satifies `key-valid-p' (or we need to
change the output of (kbd "hello") 😺)

(I know that binding keys to strings is not common amongst people who
know how to write their own commands, but plenty of people just want
to insert commonly used strings)

Item the second:

Higher up in that texi file is the following text:

    @findex kbd
      There are several ways to write a key binding using Lisp.  The
    simplest is to use the @code{kbd} function, which converts a textual
    representation of a key sequence---similar to how we have written key
    sequences in this manual---into a form that can be passed as an
    argument to @code{keymap-global-set}.  For example, here's how to bind
    @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):

    @example
    (keymap-global-set "C-z" 'shell)
    @end example

which talks about `kbd' but then never uses it (since
`keymap-global-set' doesnʼt need it).

Item the third:

But wait, maybe the documentation about `kbd' has been moved, so I
look for discussion about non-ASCII, since thatʼs where itʼs useful,
and find the following (in @node Init Non-ASCII):

      To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init
    Rebinding}).  The string syntax cannot be used, since the
    non-@acronym{ASCII} characters will be interpreted as meta keys.  For
    instance:

    @example
    (global-set-key [?@var{char}] 'some-function)
    @end example

    @noindent
    Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.

where rather than telling people to write vectors by hand, we could
explain how to use `kbd'.

Robert
--