Proper way to add bindings under C-x 8

Proper way to add bindings under C-x 8

[Howard Melman]

I'd like to add some things to the `C-x 8' prefix and am
curious as to the proper way to do it.  I'm interested in
adding more fractions similar to `C-x 8 1 / 2' and in adding
another prefix for my commonly used emojis as `C-x 8 e ...'

With a normal keymap I know I could do something like this:

    (global-set-key (kbd "C-x 8 1 / 5") (lambda () (interactive) (insert "⅕")))
    (global-set-key (kbd "C-x 8 e c") (lambda () (interactive) (insert "✅")))

But C-x 8 uses iso-transl-ctl-x-8-map which is some kind of
special translation map which I'm a bit vague about.  Also
there's some magic described in iso-transl.el about allowing
Alt to work as well.

The elisp manual doesn't mention C-x 8 stuff at all, and
that seems to be by design based on bug #594.  The emacs
manual mentions how to use it but not how to extend it. I
feel like customizing it should be described some place.

-- 

Howard

Re: Proper way to add bindings under C-x 8

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sat, 10 Apr 2021 12:57:15 -0400
> 
> I'd like to add some things to the `C-x 8' prefix and am
> curious as to the proper way to do it.  I'm interested in
> adding more fractions similar to `C-x 8 1 / 2' and in adding
> another prefix for my commonly used emojis as `C-x 8 e ...'
> 
> With a normal keymap I know I could do something like this:
> 
>     (global-set-key (kbd "C-x 8 1 / 5") (lambda () (interactive) (insert "⅕")))
>     (global-set-key (kbd "C-x 8 e c") (lambda () (interactive) (insert "✅")))

I think you want to use iso-transl-define-keys.

Re: Proper way to add bindings under C-x 8

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> I'd like to add some things to the `C-x 8' prefix and am
>> curious as to the proper way to do it.  I'm interested in
>> adding more fractions similar to `C-x 8 1 / 2' and in adding
>> another prefix for my commonly used emojis as `C-x 8 e ...'
>> 
>> With a normal keymap I know I could do something like this:
>> 
>>     (global-set-key (kbd "C-x 8 1 / 5") (lambda () (interactive) (insert "⅕")))
>>     (global-set-key (kbd "C-x 8 e c") (lambda () (interactive) (insert "✅")))
>
> I think you want to use iso-transl-define-keys.

Great, that worked just fine.  Shouldn't it be mentioned in
one of the manuals?  The preferred idioms for customizing
other keys are.

-- 

Howard

Re: Proper way to add bindings under C-x 8

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sat, 10 Apr 2021 17:35:07 -0400
> 
> >>     (global-set-key (kbd "C-x 8 1 / 5") (lambda () (interactive) (insert "⅕")))
> >>     (global-set-key (kbd "C-x 8 e c") (lambda () (interactive) (insert "✅")))
> >
> > I think you want to use iso-transl-define-keys.
> 
> Great, that worked just fine.  Shouldn't it be mentioned in
> one of the manuals?  The preferred idioms for customizing
> other keys are.

It's an obscure use case, and we don't necessarily document everything
in the manuals: that would make then too large.

In general, you are well advised to read the source code when the
documentation is missing or unclear.  That's what I did to answer your
question.

Re: Proper way to add bindings under C-x 8

[Howard Melman]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Howard Melman <hmelman@gmail.com>
>> Date: Sat, 10 Apr 2021 17:35:07 -0400
>> 
>> >>     (global-set-key (kbd "C-x 8 1 / 5") (lambda () (interactive) (insert "⅕")))
>> >>     (global-set-key (kbd "C-x 8 e c") (lambda () (interactive) (insert "✅")))
>> >
>> > I think you want to use iso-transl-define-keys.
>> 
>> Great, that worked just fine.

Well, it mostly works just fine.  I'm using the following
and they work up until the "card suits" section:

    (defvar my-iso-transl-char-map
      '(
        ;; pretty comparisons
        (">"  . nil)                        ; first unbind »
        (">=" . [?≥])                       ; way better than » or using _>
        ("<"  . nil)                        ; first unbind «
        ("<=" . [?≤])                       ; way better than « or using _<
        ("!"  . nil)                        ; first unbind ¡
        ("!=" . [?≠])                       ; way better than ¡ or using /=
        ;; fractions that emacs doesn't include
        ("1/3" . [?⅓])
        ("1/5" . [?⅕])
        ("1/6" . [?⅙])
        ("1/7" . [?⅐])
        ("1/8" . [?⅛])
        ("1/9" . [?⅑])
        ("1/10" . [?⅒])
        ("2/3" . [?⅔])
        ("2/5" . [?⅖])
        ("3/5" . [?⅗])
        ("3/8" . [?⅜])
        ("4/5" . [?⅘])
        ("5/6" . [?⅚])
        ("5/8" . [?⅝])
        ("7/8" . [?⅞])
        ;; add the emojis I commonly use
        ("ec" . [?✅])
        ("eu" . [?👍])
        ("ed" . [?👎])
        ("ew" . [?🖐])
        ("et" . [?📺])
        ;; card suits
        ;; ("es" . [?♠️])
        ;; ("eC" . [?♣️])
        ;; ("eH" . [?♥️])
        ;; ("eD" . [?♦️])
        ))

    (require 'iso-transl)
    (iso-transl-define-keys my-iso-transl-char-map)

If the card suits are uncommented I get the error:

    (invalid-read-syntax "?")
    
I assume this is because these emoji use some more
complicated encoding since C-x = tells me it's a composed
form unlike the others.  Is there a way to include these as
well?  I don't really want to have to know the different way
different emoji are encoded but if necessary I can. 

I saw the new emoji entry stuff that Lars did, but I don't
want to wait until Emacs 29 (it would be great if that was
in Emacs 28). 

I'm using the macport "GNU Emacs 27.2 (build 1,
x86_64-apple-darwin20.6.0, Carbon Version 164 AppKit 2022.6) 

-- 

Howard

Re: Proper way to add bindings under C-x 8

[Michael Heerdegen]

Howard Melman <hmelman@gmail.com> writes:

> I assume this is because these emoji use some more
> complicated encoding since C-x = tells me it's a composed
> form unlike the others.  Is there a way to include these as
> well?  I don't really want to have to know the different way
> different emoji are encoded but if necessary I can. 

I don't know anything about it.  But I can see that these card emojis
are not characters - wrapped into a string you get a length of 2:

  (length "♠️") ==> 2

Inserting the two consecutive characters seems to work:

  (insert ?♠ 65039)  ;; inserts ♠️

So iso-transl-define-keys doesn't seem to be usable for this task
indeed.

Michael.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Tue, 30 Nov 2021 12:34:28 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Howard Melman <hmelman@gmail.com> writes:
    >> I assume this is because these emoji use some more
    >> complicated encoding since C-x = tells me it's a composed
    >> form unlike the others.  Is there a way to include these as
    >> well?  I don't really want to have to know the different way
    >> different emoji are encoded but if necessary I can. 

    Michael> I don't know anything about it.  But I can see that these card emojis
    Michael> are not characters - wrapped into a string you get a length of 2:

    Michael>   (length "♠️") ==> 2

    Michael> Inserting the two consecutive characters seems to work:

    Michael>   (insert ?♠ 65039)  ;; inserts ♠️

    Michael> So iso-transl-define-keys doesn't seem to be usable for this task
    Michael> indeed.

I think youʼre right. Using the global map works fine if you use the
syntax

[?♠?️]

(where thereʼs a literal U+FE0F after that second "?")

but with the iso-transl-ctl-x-8-map it always inserts only the last
element of that vector.

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Michael Heerdegen]

Robert Pluim <rpluim@gmail.com> writes:

> [?♠?️]
>
> (where thereʼs a literal U+FE0F after that second "?")

Ah - gucharmap (a unicode character table for Gnome) says U+FE0F is
the variation-selector-16 aka "emoji variation selector".

Michael.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Tue, 30 Nov 2021 14:07:38 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Robert Pluim <rpluim@gmail.com> writes:
    >> [?♠?️]
    >> 
    >> (where thereʼs a literal U+FE0F after that second "?")

    Michael> Ah - gucharmap (a unicode character table for Gnome) says U+FE0F is
    Michael> the variation-selector-16 aka "emoji variation selector".

Yes, I knew that :-)

If OP wants his emojis to be displayed properly, they need to be
followed by VS-16 if their default emoji presentation is no, which is
the case for ♠ (and the other suit codepoints).

Lars' emoji insertion code for emacs-29 does all that for you
automatically, but emacs-29 is far from ready for release.

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Howard Melman]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Tue, 30 Nov 2021 12:34:28 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

> I think youʼre right. Using the global map works fine if you use the
> syntax
>
> [?♠?️]
>
> (where thereʼs a literal U+FE0F after that second "?")
>
> but with the iso-transl-ctl-x-8-map it always inserts only the last
> element of that vector.
>
> Robert

Thanks for the help.

So could this be considered a bug in iso-transl-define-keys?

I mean I'd like to be able to enter these both via C-x 8 e
and A-e and while not documented I was previously told to
read the source of iso-transl-define-keys.

I could make my own keymap or transient for the emoji's I
commonly use, but it really would be nice to integrate it
with Emacs' builtin way for entering non-ascii unicode
characters so I don't have to keep track of two different
mechanisms.

Or maybe Lars' Emacs 28 emoji stuff could be released as a
package that could be used with Emacs 28?

-- 

Howard

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Tue, 30 Nov 2021 11:32:13 -0500, Howard Melman <hmelman@gmail.com> said:

    Howard> Robert Pluim <rpluim@gmail.com> writes:
    >>>>>>> On Tue, 30 Nov 2021 12:34:28 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    >> I think youʼre right. Using the global map works fine if you use the
    >> syntax
    >> 
    >> [?♠?️]
    >> 
    >> (where thereʼs a literal U+FE0F after that second "?")
    >> 
    >> but with the iso-transl-ctl-x-8-map it always inserts only the last
    >> element of that vector.
    >> 
    >> Robert

    Howard> Thanks for the help.

    Howard> So could this be considered a bug in iso-transl-define-keys?

Possibly. I was hoping Eli would jump in and tell me :-)

All the uses of key-translation-map that I can find map a sequence to
a character, but your mapping is to multiple characters. That works
fine with normal keymaps, but not with key-translation-map, and Iʼve
not found documentation telling me thatʼs wrong (nor that itʼs right).

    Howard> I mean I'd like to be able to enter these both via C-x 8 e
    Howard> and A-e and while not documented I was previously told to
    Howard> read the source of iso-transl-define-keys.

    Howard> I could make my own keymap or transient for the emoji's I
    Howard> commonly use, but it really would be nice to integrate it
    Howard> with Emacs' builtin way for entering non-ascii unicode
    Howard> characters so I don't have to keep track of two different
    Howard> mechanisms.

    Howard> Or maybe Lars' Emacs 28 emoji stuff could be released as a
    Howard> package that could be used with Emacs 28?

Lars has said he's planning to do that. Iʼm growing quite fond of it 😁😼

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Tue, 30 Nov 2021 17:49:22 +0100
> Cc: help-gnu-emacs@gnu.org
> 
> >>>>> On Tue, 30 Nov 2021 11:32:13 -0500, Howard Melman <hmelman@gmail.com> said:
> 
>     Howard> So could this be considered a bug in iso-transl-define-keys?
> 
> Possibly. I was hoping Eli would jump in and tell me :-)

You were doing so well explaining the issue that I didn't even bother
looking at the code.  I will, if I need to.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Tue, 30 Nov 2021 19:25:13 +0200, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Date: Tue, 30 Nov 2021 17:49:22 +0100
    >> Cc: help-gnu-emacs@gnu.org
    >> 
    >> >>>>> On Tue, 30 Nov 2021 11:32:13 -0500, Howard Melman <hmelman@gmail.com> said:
    >> 
    Howard> So could this be considered a bug in iso-transl-define-keys?
    >> 
    >> Possibly. I was hoping Eli would jump in and tell me :-)

    Eli> You were doing so well explaining the issue that I didn't even bother
    Eli> looking at the code.  I will, if I need to.

I am? I donʼt feel like I have any grasp of it at all.

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Howard Melman]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Tue, 30 Nov 2021 19:25:13 +0200, Eli Zaretskii <eliz@gnu.org> said:
>
>     >> From: Robert Pluim <rpluim@gmail.com>
>     >> Date: Tue, 30 Nov 2021 17:49:22 +0100
>     >> Cc: help-gnu-emacs@gnu.org
>     >> 
>     >> >>>>> On Tue, 30 Nov 2021 11:32:13 -0500, Howard Melman <hmelman@gmail.com> said:
>     >> 
>     Howard> So could this be considered a bug in iso-transl-define-keys?
>     >> 
>     >> Possibly. I was hoping Eli would jump in and tell me :-)
>
>     Eli> You were doing so well explaining the issue that I didn't even bother
>     Eli> looking at the code.  I will, if I need to.
>
> I am? I donʼt feel like I have any grasp of it at all.

I'd like to know.  The work-around posted doesn't bind
things in all the places iso-tranl-define-keys does (only
under C-x 8) and I find that code a bit opaque.

-- 

Howard

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Tue, 30 Nov 2021 12:43:33 -0500, Howard Melman <hmelman@gmail.com> said:

    >> I am? I donʼt feel like I have any grasp of it at all.

    Howard> I'd like to know.  The work-around posted doesn't bind
    Howard> things in all the places iso-tranl-define-keys does (only
    Howard> under C-x 8) and I find that code a bit opaque.

So the elisp manual says the following in "(elisp) Translation Keymaps"
(see especially that last sentence)

       Translation keymaps have the same structure as other keymaps, but are
    used differently: they specify translations to make while reading key
    sequences, rather than bindings for complete key sequences.  As each key
    sequence is read, it is checked against each translation keymap.  If one
    of the translation keymaps binds K to a vector V, then whenever K
    appears as a sub-sequence _anywhere_ in a key sequence, that
    sub-sequence is replaced with the events in V.

"event_s_ in V."

Later in the same node:

       You can use ‘input-decode-map’, ‘local-function-key-map’, and
    ‘key-translation-map’ for more than simple aliases, by using a function,
    instead of a key sequence, as the translation of a key.  Then this
    function is called to compute the translation of that key.

"instead of a key _sequence_"

So Iʼd expect the following

(define-key iso-transl-ctl-x-8-map "ef" (vector #x2660 #x2660))

to allow me to use C-x 8 e f to insert U+2660 twice, but it only
inserts it once. What am I missing?

(emacs-master, although I doubt that matters)

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Michael Heerdegen]

Robert Pluim <rpluim@gmail.com> writes:

> to allow me to use C-x 8 e f to insert U+2660 twice, but it only
> inserts it once. What am I missing?

Maybe the whole procedure stops when a complete key sequence with a
binding has been reached?  I guess that in this case what you want is
beyond the reach of key translation mechanisms.

Michael.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Thu, 02 Dec 2021 15:44:43 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Robert Pluim <rpluim@gmail.com> writes:
    >> to allow me to use C-x 8 e f to insert U+2660 twice, but it only
    >> inserts it once. What am I missing?

    Michael> Maybe the whole procedure stops when a complete key sequence with a
    Michael> binding has been reached?  I guess that in this case what you want is
    Michael> beyond the reach of key translation mechanisms.

Iʼm not sure I understand what you mean. 'C-x 8 e' is not a complete
key sequence, itʼs a prefix. And the character inserted is always the
second one from the vector in the binding.

Just to be sure, I tried:

(define-key iso-transl-ctl-x-8-map "ff" (vector #x2660 #x2661))

Thereʼs no 'C-x 8 f' bindings at all, and this ends up inserting
U+2661, as does

(define-key iso-transl-ctl-x-8-map "f" (vector #x2660 #x2661))

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Michael Heerdegen]

Robert Pluim <rpluim@gmail.com> writes:

>     Michael> Maybe the whole procedure stops when a complete key
>     Michael> sequence with a
>     Michael> binding has been reached?  I guess that in this case what
>     Michael> you want is
>     Michael> beyond the reach of key translation mechanisms.
>
> Iʼm not sure I understand what you mean. 'C-x 8 e' is not a complete
> key sequence, itʼs a prefix. And the character inserted is always the
> second one from the vector in the binding.

But #x2660 and #x2661 are keys, complete key sequences each, bound to
`self-insert-command'.

Michael.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Thu, 02 Dec 2021 16:27:55 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Robert Pluim <rpluim@gmail.com> writes:
    Michael> Maybe the whole procedure stops when a complete key
    Michael> sequence with a
    Michael> binding has been reached?  I guess that in this case what
    Michael> you want is
    Michael> beyond the reach of key translation mechanisms.
    >> 
    >> Iʼm not sure I understand what you mean. 'C-x 8 e' is not a complete
    >> key sequence, itʼs a prefix. And the character inserted is always the
    >> second one from the vector in the binding.

    Michael> But #x2660 and #x2661 are keys, complete key sequences each, bound to
    Michael> `self-insert-command'.

Not on my keyboard :-)

If that were the case, the sequence would stop, produce #x2660, and
then continue and produce #x2661. Except I donʼt see that #x2660 anywhere.

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Michael Heerdegen]

Robert Pluim <rpluim@gmail.com> writes:

> If that were the case, the sequence would stop, produce #x2660, and
> then continue and produce #x2661.

Would it?  My interpretation is that what you do is outside of the
specification of key translations, and you shouldn't do it no matter
what happens by accident.  But there is no need to philosophize, a
better answer should be findable in the source code.

Michael.

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Thu, 02 Dec 2021 17:18:04 +0100, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Robert Pluim <rpluim@gmail.com> writes:
    >> If that were the case, the sequence would stop, produce #x2660, and
    >> then continue and produce #x2661.

    Michael> Would it?  My interpretation is that what you do is outside of the
    Michael> specification of key translations, and you shouldn't do it no matter
    Michael> what happens by accident.  But there is no need to philosophize, a
    Michael> better answer should be findable in the source code.

Itʼs not outside what's documented, unless Iʼm misunderstanding the
documentation.

Iʼll put looking at the code on my list.

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Robert Pluim]

>>>>> On Mon, 29 Nov 2021 11:21:46 -0500, Howard Melman <hmelman@gmail.com> said:

    Howard> Well, it mostly works just fine.  I'm using the following
    Howard> and they work up until the "card suits" section:

    Howard>         ;; card suits
    Howard>         ;; ("es" . [?♠️])
    Howard>         ;; ("eC" . [?♣️])
    Howard>         ;; ("eH" . [?♥️])
    Howard>         ;; ("eD" . [?♦️])
    Howard>         ))

    Howard> If the card suits are uncommented I get the error:

    Howard>     (invalid-read-syntax "?")

That may or may not be a bug, Iʼm not sure. In the meantime, thereʼs
nothing stopping you from adding bindings to the keymap used for 'C-x'
without using iso-transl-define-keys. Itʼs a bit more verbose, but
works fine:

    (let ((map (make-sparse-keymap)))
      (define-key map "s" [?♠?️])
      (define-key map "C" [?♣?️])
      (define-key map "H" [?♥?️])
      (define-key map "D" [?♦?️])
      (define-key ctl-x-map "8e" map))

Robert
-- 

Re: Proper way to add bindings under C-x 8

[Howard Melman]

Robert Pluim <rpluim@gmail.com> writes:

> In the meantime, thereʼs nothing stopping you from adding
> bindings to the keymap used for 'C-x' without using
> iso-transl-define-keys. Itʼs a bit more verbose, but works
> fine:
>
>     (let ((map (make-sparse-keymap)))
>       (define-key map "s" [?♠?️])
>       (define-key map "C" [?♣?️])
>       (define-key map "H" [?♥?️])
>       (define-key map "D" [?♦?️])
>       (define-key ctl-x-map "8e" map))

I went with the following:

(let ((map (make-sparse-keymap)))
  (define-key map "c" (string-to-vector "✅️"))
  (define-key map "u" (string-to-vector "👍️"))
  (define-key map "d" (string-to-vector "👎️"))
  (define-key map "w" (string-to-vector "🖐️"))
  (define-key map "t" (string-to-vector "📺️"))
  (define-key map "S" (string-to-vector "♠️"))
  (define-key map "C" (string-to-vector "♣️"))
  (define-key map "H" (string-to-vector "♥️"))
  (define-key map "D" (string-to-vector "♦️"))
  (define-key ctl-x-map "8e" map))

-- 

Howard