Vim Digraphs: The Unnecessarily Detailed Guide

In Vim, in Insert mode, if you type Ctrl-K followed by two characters, you can insert a special Unicode character corresponding to those two characters. The two-character combo is often easier to remember than other codes. These are called digraphs.

For example, Ctrl-K12 will insert ½.

Everything below this is unnecessary detail.

What are all the digraphs?

I used to think the big table :help digraphs-table at the bottom of Vim’s help page for digraphs was exhaustive. As the page explains, the mnemonics are based on RFC1345, an Internet standard that provides two-character mnemonics for various characters.

To locate ourselves on a timeline: this RFC is from June 1992. To define what a “character” is, it refers to “ISO 2DIS 10646”. That’s a version¹ of ISO 10646, a standard which had sort of competed with Unicode for a while before they became unified in 1991, shortly before our RFC. Of course, these standard(s) hadn’t “won” at the time; single-byte encodings with all kinds of competing codepages were all the rage still. I assume this is the time about which Joel Spolsky wrote that Americans’ résumés would arrive in Israel as rגsumגs.

However, at some point, I accidentally discovered that you can use the digraph 22 for the superscript 2 character, ². This is not in RFC1345 or on that help page! It does get printed by :digraphs, but it’s harder to find, and since it’s easier to type than the help page’s 2S, I wanted to learn what other digraphs there were that I didn’t know about.

In the Vim source code (or Neovim), the 22 digraph and several others have a comment saying, “Vim 5.x compatible”. Vim 5.0 was released in February 1998. But Vim had digraphs before then; the comment means that the digraphs without the comment were added after Vim 5.x: in September 2001, when Vim 6.0 was released. Vim’s documentation notes as much, in a short section under :help incompatible-6:

The default digraphs now correspond to RFC1345. This is very different from what was used in Vim 5.x.

(Understandably, this section is not in NeoVim’s docs.)

To track down our mystery digraphs, we need to go further back in Vim history. This is a little tricky. The (now-)official Vim git repo only goes as far back as 7.0²; even the official Vim source mirrors only go back to 3.0.

Fortunately, the vim-history GitHub repo has older versions, including version notes³ saying that digraphs were added in Vim 1.18. No release date for 1.18 is documented, but the repo lists release dates for 1.17 in April 1992 and for 1.27 in April 1993, so it seems likely that 1.18 came out mid-1992. Interestingly, the version notes say that “CTRL-K for entering digraphs” was only added in version 1.25. Before then, you could only use digraphs with the “one character, backspace, the other character” song and dance (which might have been helpfully analogous to a typewriter for some users), and only if digraphs were specifically enabled.⁴

Anyway, the 1.24 version of digraphs is the earliest source code I could find, and there it is, the 22 digraph for ².

While we’re randomly rabbit-holing

I couldn’t help but notice the contributors on top of the file:

Bram Moolenaar          [email protected]
Tim Thompson            twitch!tjt
Tony Andrews            onecom!wldrdg!tony 
G. R. (Fred) Walter     watmath!watcgl!grwalter

You know what other standard we take for granted today hadn’t “won” yet? Email addresses. Bram Moolenaar had an email address, but the other three contributors’ contact information was provided as UUCP bang paths.

A short history of digraphs and code pages

If you trace the file a bit further, you find that the next commit we have, 1.27, switches to a file digraph.c.uue. I realized shortly after actually typing this out that I don’t actually know whether the file was provided as such back in 1993 or whether this was the archivist’s decision. (The repository history is clearly post-hoc since Git itself came out in 2005.) I considered checking every commit to write down every digraph change, but quickly decided that that would be far too time-consuming. Let’s just check in on digraph.c at the start of each major version.

• In v2.0 (December 1993) Vim can be compiled with “standard MSDOS digraphs” or “standard ISO digraphs”. It looks like “standard MSDOS digraphs” use the same mnemonics applied to Code page 437.

• In v3.0 (August 1994) the digraphs are mostly the same as v2.0. (I couldn’t figure out why git blame shows a large change.)

• In v4.0 (May 1996) Vim gained “HPUX digraphs” for HP Roman.

• In v5.0 (February 1998), under an ATARI MiNT preprocessor guard, Vim gained “ATARI digraphs” for the Atari ST character set.

• In v6.0 (August 2001), Vim gained digraphs for EBCDIC and MACOS (Mac OS Roman), in addition to the modern RFC1345 digraphs. The old digraphs that didn’t conflict with the new ones were generally kept around (though see below), but all old digraphs were still available under an OLD_DIGRAPHS preprocessor guard. There were also a few tweaks and additions to those old default digraphs in v5.2: AA/aa were added next to A@/a@ for Å/å, and a few digraphs for characters where ISO 8859-15 diverged from ISO 8859-1 were added.

• In v7.0 (May 2006) the digraphs are mostly the same as v6.0. From this point on, though, Vim started to shed support for operating systems and their code pages as they faded into obscurity. (Also, we have real git commits and it’s easier to find major changes.) Vim dropped MS-DOS in 7.4.1399, MACOS in 8.1.0805, MiNT in 8.2.1215, EBCDIC in 8.2.4273, and OLD_DIGRAPHS and HPUX_DIGRAPHS in 9.0.0328. On the other hand, it also gained new default digraphs in tiny batches:

  • =e for € EURO SIGN in 7.0017,
  • Eu for € EURO SIGN (again) in 7.0146,
  • =R and =P for ₽ RUBLE SIGN (called ROUBLE SIGN in the source code) in 7.4.335,
  • ,. for … HORIZONTAL ELLIPSIS in 8.0.0062,
  • W`, w`, Y`, and y` for some letters with graves (Ẁ, ẁ, Ỳ, ỳ) in 8.0.0749,
  • oo for • BULLET in 8.2.1635,
  • 4' for ⁗ QUADRUPLE PRIME in 9.0.2056, and
  • .= for ≐ APPROACHES THE LIMIT in 9.1.1065.

  That last one was committed in February this year, after I started writing this post. I have a few dozen custom digraphs in my vimrc file; maybe only a handful are digraphs I could imagine being broadly useful and memorable, but I have never once considered the option of trying to upstream any of them to every Vim user ever. I admire the hustle.

I’ve given up on documenting the digraphs for every now-dead codepage, not only because there are so many but because it would often be anachronistic to describe “what character” each digraph was for in modern terms. Unicode still hadn’t won! In pursuit of economy, several code pages deliberately conflate the German eszett ß with the Greek beta β. HPUX had digraphs L- and L= for one-bar £ and two-bar ₤ pound signs, even though today they’re considered typographical variations — in fact, the HP Roman codepage is the reason Unicode has a separate ₤ character.⁵ MACOS had the AP digraph for the Apple logo, which is a private-use character, U+F8FF, today. Are you on a macOS device? 

For a similar rabbit hole, you can read about the “small house” in Code Page 437 on Glyph Drawing Club.

Every old Vim digraph

Here are the final “old Vim digraphs” before they were removed in 9.0.0328, and each of their ultimate fates. I also provide the new, RFC-compliant digraph for the character each old digraph was for. The unintuitive digraphs, like e= mapping to U+00A4, are related to the ISO 8859-15 divergence.

Surprisingly, four digraphs — "", rO, ,,, and i" — were not preserved even though they don’t conflict with any RFC digraphs, and even though some similar digraphs (cO for ©, a" for ä, e" for ë, etc.) were preserved.

All remaining default digraphs that aren’t from the RFC were added after 7.0 and mentioned above, though how Vim’s digraphs help page discusses them varies. That page documents a subset of those digraphs in the big :help digraph-table table that I originally hoped was exhaustive, and calls out a different subset in the prose as additions to RFC1345. Though, 9.1.1065, the last commit to add a digraph, also revises the prose to say that the default digraphs come from “RFC1345 mnemonics (with some additions)”, so arguably that base is now fully covered.

How do you implement digraphs in the wild?

(Really stretching the concept of relevance here.)

I have a problem where I will have tiny conveniences on some computers that I own and then get annoyed that I don’t have them on other devices or operating systems. I’m also enough of a web dev that I can fix this. Digraphs are easy enough: In a text area, capture the keydown event. If it’s Ctrl-K, activate digraph mode and capture and preventDefault the next two keydown events. After the second such event, look up the digraph and append it.

textarea.addEventListener('keydown', function(e) {
    if (e.ctrlKey && e.key === 'k') {
        e.preventDefault();
        isDigraphMode = true;
        // ...
    }
    if (isDigraphMode) {
        // look some stuff up with previous/current e.key
    }
});

Problem: I can’t Ctrl-K on my phone. Solution: Pick a different typeable key, say the backslash. (In practice I made it customizable.)

textarea.addEventListener('keydown', function(e) {
    if (e.ctrlKey && e.key === 'k'
            || (!isDigraphMode && e.key === "\\")) {
        e.preventDefault();
        isDigraphMode = true;
        // ...
    }
    if (isDigraphMode) {
        // look some stuff up with e.key and any buffered presses
    }
});

Surprisingly, although this works on my computer and a few other desktop and mobile browsers I checked, it doesn’t work on Android Chrome, where e.key is always "Unidentified". Some StackOverflow issues like Why is “Unidentified” returned on keyboard input on mobile? point to issue 118639 on the Chromium bug tracker, but it denies access for me. According to a Wayback Machine snapshot, this bug was opened in March 2012 and a fix was merged in August 2014, but then the fix was reverted in April 2015 and the bug was marked as WontFix.

Too many non-western-keyboard use-cases depend on having “compose” key-codes instead of guessed “proper” ones. We’ve tried fixes that compromise but they never get all the edge-cases.

The bottom line is that if you want your keyboard-knowledgeable web page to work with Chrome, you’re going to have to be tolerant of IME’s idiosyncrasies with regard to key-codes.

The best resolution I found is to capture the beforeinput event instead, whose meaning maybe is simpler in a world with so many input methods — “if you would insert this text, don’t”.

textarea.addEventListener('beforeinput', function(e) {
    if (e.data === "\\") {
        e.preventDefault();
        isDigraphMode = true;
        // ...
    }
});

Anyway I now have a digraphs.html with an obnoxious number of custom digraphs I can use anywhere I have an internet connection and a modern JavaScript-enabled browser.