Configuring Keyboards with Org-mode Babel

Where do I even start? So, most keyboards today come with a Qwerty layout, which was named so because the first few keys in the top letter row of it are, sequentially, Q W E R T Y.

Unfortunately, Qwerty is old, with its design coming from typewriters, and can be a bit limited in its ergonomics or typing efficiency: it does not put some of the most frequently pressed keys on the middle row, so you will have to stretch your fingers most of the time.

And it’s why people tried to come up with alternative keyboard layouts, like Drovak:

Or, Colemak:

Or Colemak Mod-DH (which I use) or Workman, Norman… you name it.

There are multiple ways to use these layouts on your Qwerty keyboards. One way is through software remapping on your computer, with xkb configs or maybe AutoHotkey—it’s just you need to do this on all your devices. Another way is to flash dedicated firmware onto your keyboard so that the keyboard directly maps the keys for you, portably. And a popular, open-source keyboard firmware (that I use) is QMK.

QMK configs are plain C files that will be linked with the firmware:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[_QWERTY] = LAYOUT_ortho_5x12(
  KC_GRV,  KC_1,    KC_2,    KC_3,    KC_4,    KC_5,    KC_6,    KC_7,    KC_8,    KC_9,    KC_0,    KC_BSPC,
  KC_TAB,  KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,    KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,    KC_DEL,
  KC_ESC,  KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN, KC_QUOT,
  KC_LSFT, KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH, KC_ENT,
  KC_CAPS, KC_LCTL, KC_LALT, KC_LGUI, LOWER,   KC_SPC,  KC_SPC,  RAISE,   KC_LEFT, KC_DOWN, KC_UP,   KC_RGHT
),
// ... other layers
};

QMK also allows you to specify keys (or key combinations) to enter arbitrary Unicode characters by using basic UC(...) keycodes or Unicode maps:

enum unicode_names {
    BANG,
    IRONY,
    SNEK
};
const uint32_t PROGMEM unicode_map[] = {
    [BANG]  = 0x203D,  // UM(BANG)  → ‽
    [IRONY] = 0x2E2E,  // UM(IRONY) → ⸮
    [SNEK]  = 0x1F40D, // UM(SNEK)  → 🐍
};

With QMK, configuring the layout is quite straightforward: just add any keycodes you want, change the keymap matrix array as is shown above, and recompile it. But, things can get quite messy if you want a keyboard layout like this:

OK, I promise we’re already halfway through the introduction! So, all those Unicode symbols on the keyboard schema above is for APL, a cute array programming language (or a family of them) famous for its terseness. For example, here is one of my learning code snippets in Dyalog APL:

⍝ "⍝" marks line comments (I call it amugus BTW)
⎕IO←0     ⍝ use 0-based indices
+/⍳100     ⍝ adding from 0 to 99
(+/÷≢)⍳100 ⍝ averaging (0 1 2 ... 99)

And this is a Quicksort implementation, which I have yet to fully grasp:

Q←{1≥≢⍵:⍵ ⋄ S←{⍺⌿⍨⍺ ⍺⍺ ⍵} ⋄ ⍵((∇<S)⍪=S⍪(∇>S))⍵⌷⍨?≢⍵}

⎕, ←, ⍳, ÷, ≢, … APL uses a lot of non-ASCII symbols as “verbs”, meaning that, to learn APL, you have to first find a keyboard (or, most often, a keyboard mapping) for it.

There are dedicated key caps and some keyboard stickers sold by Dyalog Ltd. And you can find a few APL mappings for ordinary keyboards online—by “ordinary”, they very much mean “Qwerty”. And, no, the physical key mapping is different when you maps Colemak/Drovak keys into APL symbols, because you don’t want to lose their mnemonics: ²

So what do we do? Do we actually manually configure our QMK layout for all these symbols, one by one? Or can we take a shortcut to batch-generate them?

‘course, there’s an emacs command to do that.

The GNU APL mode comes with a gnu-apl-show-keyboard command. It’s in Qwerty layout, of course, but its backing data gnu-apl--symbols actually provide what we need to generate our Colemak + APL mapping.

(defvar gnu-apl--symbols '(;; Top row
                           ;; `
                           ("diamond" "◊" "`")
                           ;; 1
                           ("diaeresis" "¨" "1")
                           ("i-beam" "⌶" "!")
                           ;; 2
                           ("macron" "¯" "2")
                           ("del-tilde" "⍫" "@")
                           ;; ...

                           ;; First row
                           ;; q
                           ("question-mark" "?" "q")
                           ;; w
                           ("omega" "⍵" "w")
                           ("omega-underbar" "⍹" "W")
                           ;; e
                           ("epsilon" "∊" "e")
                           ("epsilon-underbar" "⍷" "E")
                           ;; ...
                           ))

To map from a Qwerty layout to Colemak(-DH) or your favorite keymap, you either manually replace all the letter keys, or find their textual representation to programatically maps them with Org Babel.

With the :var qwerty=qwerty header args, you can use the table above as a data source and apply any transformation to it, like this:

#+begin_src elisp :var qwerty=qwerty
  (caar qwerty)
#+end_src

#+RESULTS:
: KC_ESC

Let’s now convert the layout from Qwerty to Colemak:

(defun parse-keys (s)
  (mapcar
   (lambda (k) (or (alist-get k '((";" . "SCLN")
                                  ("," . "COMM")
                                  ("." . "DOT")
                                  ("/" . "SLSH"))
                              k nil #'equal)))
   (string-split (upcase s))))
(setq
 ;; https://github.com/ColemakMods/mod-dh/blob/gh-pages/webapp/resources/layout_main/qwerty.keyb
 qwerty-keys (parse-keys "
q  w  e  r  t  y  u  i  o  p
a  s  d  f  g  h  j  k  l  ;
z  x  c  v  b  n  m  ,  .  /
")
 ;; https://github.com/ColemakMods/mod-dh/blob/gh-pages/webapp/resources/layout_main/colemak_dh.keyb
 colemak-dh-keys (parse-keys "
q  w  f  p  b  j  l  u  y  ;
a  r  s  t  g  m  n  e  i  o
z  x  c  d  v  k  h  ,  .  /
"))
(defun table-substitute (new old table)
  (dolist (row table)
    (cl-nsubstitute new old row :test #'equal)))
(seq-mapn (lambda (c q) (table-substitute (concat "→KC_" c) (concat "KC_" q) qwerty))
          colemak-dh-keys qwerty-keys)
(dolist (c colemak-dh-keys)
  (table-substitute (concat "KC_" c) (concat "→KC_" c) qwerty))
qwerty

Make some manual adjustments to that, (for example, I usually map Caps Lock to the Escape key) and you now have a layout to map the APL symbols onto.

Similarly, we can easily create an Org table for APL keyboard layouts. (By adding #+name: colemak attributes onto the source block, you can refer to the Colemak table with :var colemak=colemak.)

(setq dyalog--symbols gnu-apl--symbols) ; adjust the keymap
(defvar key-to-char-mapping
  '(("GRAVE" "`" "~")
    ("MINS" "-" "_")
    ("EQL" "=" "+")
    ("SCLN" ";" ":")
    ("LBRC" "[" "{")
    ("RBRC" "]" "}")
    ("BSLS" "\\" "|")
    ("QUOT" "'" "\"")
    ("COMM" "," "<")
    ("DOT" "." ">")
    ("SLSH" "/" "?")
    ))
(defun alist-get-nth (n key seq)
  (seq-find (lambda (ele) (equal key (nth n ele))) seq))
(defvar number-to-char-mapping ")!@#$%^&*(")
(defun key-to-char (key)
  (if (string-match "^KC_\\([0-9A-Z]\\)$" key)
      (downcase (match-string 1 key))
    (and (string-prefix-p "KC_" key)
         (cadr (alist-get-nth 0 (substring key 3) key-to-char-mapping)))))
(defun char-to-shifted (char)
  (let ((c (string-to-char char)))
    (cond
     ((<= ?a c ?z)
      (string (upcase c)))
     ((<= ?0 c ?9)
      (string (aref number-to-char-mapping (- c ?0))))
     (t (caddr (alist-get-nth 1 char key-to-char-mapping))))))
(defun to-c (sym)
  (string-replace "-" "_" (upcase sym)))
(defun dyalog-mapping (keys &optional up)
  (mapcar
   (lambda (key)
     (when-let* ((c (key-to-char key))
                 (c (if up (char-to-shifted c) c))
                 (entry (alist-get-nth 2 c dyalog--symbols))
                 (sym (to-c (car entry)))
                 (c (cadr entry)))
       (list sym c key)))
   keys))

(defun keymap-from-table (name table)
  (with-temp-buffer
    (dolist (row table)
      (dolist (key row)
        (insert "| ")
        (insert
         (cond
          ((equal key "___") "_______")
          (key key)
          (t ""))))
      (insert "|\n"))
    (org-table-align)
    ;; Org-table to C args
    (goto-char (point-min)) (replace-string " |" ",")
    (goto-char (point-min)) (replace-regexp "^| " "    ")
    (goto-char (point-min))
    (while (re-search-forward ",\\([ ,]+\\)," nil t)
      (replace-match (concat (make-string (- (match-end 0) (match-beginning 0) 1) ?\ ) ",")))
    ;; No trailing comma
    (search-backward ",")
    (delete-char 1)
    ;; Wrap
    (goto-char (point-min)) (insert "[" name "] = LAYOUT_60_ansi(\n")
    (goto-char (point-max)) (insert "),\n")
    (buffer-string)))

• APL symbols on Colemak layout (lower-case / with Shift un-pressed):

  (cl-loop for row in colemak
           collect (mapcar (lambda (l) (or (cadr l) "")) (dyalog-mapping row)))
  

  ¨

  ¯

  <

  ≤

  =

  ≥

  >

  ≠

  ∨

  ∧

  ×

  ÷

  ?

  ⍵

  _

  ⋆

  ⊥

  ∘

  ⎕

  ↓

  ↑

  ⍎

  ←

  →

  ⊢

  ⍺

  ⍴

  ⌈

  ∼

  ∇

  ⊤

  ∊

  ⍳

  ○

  ⍕

  ⊂

  ⊃

  ∩

  ⌊

  ∪

  ‘

  ∆

  ⍝

  ⌿

• APL symbols on Colemak layout (upper-case / with Shift modifier):

  (cl-loop for row in colemak
           collect (mapcar (lambda (l) (or (cadr l) "")) (dyalog-mapping row t)))
  

  ⌶

  ⍫

  ⍒

  ⍋

  ⌽

  ⍉

  ⊖

  ⍟

  ⍱

  ⍲

  !

  ⌹

  ⍹

  ⍫

  ⍣

  £

  ⍤

  ⌷

  ¥

  ≡

  ⍞

  ⍬

  ⊣

  ⍶

  ⍨

  ⍷

  ⍸

  ⍥

  ≢

  χ

  ⍧

  ⌺

  ⍙

  ⍪

  ⍀

  ⍠