This appendix draws heavily from Josh Lifton's 2010 Plover Guide.

The Basics

The Plover dictionary file is in JSON format, essentially a bunch of key/value pairs. Each pair is separated from the next by a comma, and the key and the value are each in double quotes, and separated from each other by a colon. And the entire dictionary is enclosed in a single pair of curly braces:

Note that the last entry in the dictionary file has no trailing comma.

In the keystroke portion of each entry, a hyphen is used to disambiguate which side of the keyboard has a particular key:

Note that the hyphen does not indicate multiple keystrokes. When stroking SK-D, you would press the S, K, and D keys at the same time.

To indicate multiple strokes, the keystroke portion of each entry uses a forward slash:

Some entries have lots of strokes:

An entry can output more than just a single word. In the output portion of the entry, use blank spaces to create strings of words to output:

Aside from spaces and letters, you can use numerals, and any of '.'-$%:,/()&=>?*' in the output portion of an entry.

Note that the above characters aren't special in any way. They are simply output by Plover, exactly like other entries.

To use the double quote '"' character in the output portion of an entry, you need to precede it with a backslash '\':

The above entry isn't in the dictionary file because it's not very useful. As it is, Plover treats it like any other word, and inserts spaces before and after. So if you stroke SAEU/KWOT/HEU/KWOT/TO/HEUPL, Plover will produce 'say " hi " to him' instead of 'say "hi" to him'.

Introduction To Commands

To get special behaviors from certain characters, you must enclose them in curly braces within the output portion of an entry. For example, '{.}' tells Plover to output a period followed by a space, and then capitalize the first letter of whatever word the user types next:

Likewise, '{?}' does the same with the question mark, and '{!}' does the same with an exclamation mark:

These characters wrapped in curly braces do not have to take up the whole output by themselves. They can be combined with regular text and other curly braced characters:

The above entry attaches a comma to the previous word, then adds a space, and the words "does it", then adds a question mark, then adds a space and forces Plover to capitalize the next word. For example, stroke EUT/TKOPBT/HURT/-RGBS/TOS/STPH to produce 'it doesn't hurt, does it?'

Note that any blank spaces surrounding the curly braces are ignored. So, the above entry produces the exact same output as:

If you don't necessarily want to add punctuation, but you still want Plover to capitalize the first letter of whatever the user types next, put '{-|}' at the end of the output portion of the entry:

In the above entry, it's not the '.' outside of curly braces, but the '{-|}', that causes the first letter of the next word to be capitalized. So to get 'Dr. King', you could stroke TKR*FPLT/KEUPBG.

Notice that in the above example, there's a space between the 'Dr.' and the 'King'. This has nothing to do with either the '.' or the '{-|}'. This is simply Plover inserting a space before each next word, as usual.

Just as the '{-|}' command  forces the first letter of the next word to be capitalized, so the '{>}' command forced the first letter of the next word to be lowercase:

Normally, stroking KO*EUPBG produces 'King'. But if you stroke the above entry first, and then stroke KO*EUPBG, it produces 'king'.

It's possible to suppress the space between words, using '{^}'. Consider if the 'king' entry used this:

Now stroking TKR*FPLT/KEUPBG would produce 'Dr.King' instead of 'Dr. King'. The '{-|}' from the previous entry causes 'King' to be capitalized, while the '{^}' in this entry suppresses the space between 'Dr.' and 'King'.

You could get a similar effect by moving the '{^}' from the start of the 'king' entry to the end of the 'Dr.' entry.

Now TKR*FPLT/KEUPBG  will still produce 'Dr.King' with no space between 'Dr.' and 'King'. But the same effect will now be achieved for other doctors as well. So, TKR*FPLT/HOUS produces 'Dr.House', and TKR*FPLT/WHO produces 'Dr.Who'.

If you like this space-suppressing effect in general, but just not for a specific case, you can force Plover to output a space, using '{ }' (a blank space wrapped between curly braces).

Now, TKR*FPLT/HOUS will still produce 'Dr.House' and TKR*FPLT/WHO will still produce 'Dr.Who', but TKR*FPLT/KEUPBG will produce 'Dr. King', with a space between 'Dr.' and 'King'.

Notice that the second stroke overrode the first. The TKR*FPLT stroke instructs Plover to suppress the following space, but then the KEUPBG stroke tells Plover to add it back in again.

Extended {^} Commands

In the previous section, we saw how '{^}' could be used to suppress the space between a word and its neighbor in either direction. In fact, this is the foundation of a very powerful feature of Plover - the ability to support prefix and suffix strokes.

In the above entry, the '^' is on the right, and suppresses the space between the 'kilo' and the next word. It has the effect of turning the 'kilo' into a prefix that you can prepend onto any word. So K*EUL/KEUPBG produces 'kiloking', K*EUL/HOUS produces 'kilohouse', and K*EUL/WHO produces 'kilowho'.

Or consider the opposite case:

In the above entry, the '^' is on the left, and suppresses the space between the 'ing' and the previous word. It has the effect of turning the 'ing' into a suffix that you can append onto any word. So KEUPBG/-G produces 'kinging', and HOUS/-G produces 'housing', and WHO/-G produces 'whoing'.

But wait! There was something unexpected in one of those examples. Why didn't HOUS/-G produce 'houseing' instead of 'housing' How did Plover know to drop the final 'e' before adding the 'ing'?

In fact, Plover recognizes four special suffixes - '^ed', '^ing', '^er', and '^s':

These four suffix strokes have special logic in the Plover engine itself that has nothing to do with the dictionary file, and that cause them to do the right thing when used at the end of most words. So HEUT/-G produces 'hitting' with a doubled 't', while KAOEP/-G produces 'keeping' with only a single 'p'. The Plover engine understands the English rules for adding these suffixes to words.

Other suffix strokes simply append their suffix to the existing word as stroked.

The above suffix has no logic internal to the Plover engine, and simply appends 'cracy' to whatever word came before. So KEUPBG/-KRAES produces 'kingcracy', HOUS/-KRAES produces 'housecracy', and WHO/-KRAES produces 'whocracy'.

Prefixes and suffixes can be combined without any root word:

The above two entries can be stroked together as EUD/KWRO/KRAES to produce 'idiocracy'.

It's also possible to use the '^' at both ends of an entry, to suppress the space on both sides:

Using the above entry, it's possible to stroke PHURD/K*UPL/S-DZ to produce 'murder-cum-suicide'.

The '^' is a general-purpose command. It can be used wherever you'd like to suppress a previous or subsequent word break:

The above entry produces the ellipses, followed by a space, and capitalizing the following word. It can be used when the ellipses are intended to end a sentence. So you could stroke HE/WAS/TKPWOPB/SKWR-RBGS/WE/HREFT/-T/TPHELGT/TKAEU to produce 'He was gone... We left the next day.'

An example of a case where word breaks must be routinely altered is when using quotes.

These are the dictionary entries for the closing quote and the opening quote. For example, stroke SAEU/KW-GS/HEU/KR-GS/TO/HEUPL to produce 'say "hi" to him'.

The '~|' tells Plover to maintain capitalization after the quote. If one does KPA/KW-GS/HEL/HROE the result is '"Hello'; however, if one were to do KPA/S-P/HEL/HROE the result would be ' hello' as the KPA capitalization is no longer in effect. 

Sometimes you want punctuation on the inside of the quote, sometimes on the outside. Personally, I put punctuation on the inside when quoting human speech, and outside when quoting computer speech. Plover supports both approaches:

The first entry suppresses a space after the previous word, then adds the double quote character, then suppresses the space after that and adds the period character, then adds a space, and capitalizes the first letter of whatever word comes next. So for example, stroke AOUS/KW-GS/TKPW*/R*/E*/P*/KR-GS/TP-PL/EUT/WORBGS to produce 'use "grep". It works'. 

The second entry does the same, but outputs the period before the double quote character. So for example, stroke SAEU/KW-GS/HEU/TP-PL/KR-GS/TKPWO/OPB to produce 'say "hi." Go on'.

The {&} Glue Command

The '&' command is similar to the '^' command. It always suppresses spaces on both the left and the right sides of the output; but only for neighboring strokes that are also '&' glue commands. This is the foundation of Plover's fingerspelling support.

These are the dictionary entries for the fingerspelled letters 'p', 'i', and 't'. To fingerspell the word 'pit', you could stroke P*/*EU/T*. To type 'snake pit city' you could stroke STPHAEUBG/P*/*EU/T*/STEU.

Notice that 'snake' and 'city' are not joined with 'pit' into 'snakepitcity', because the entries for 'snake' and 'city' don't contain the '&' glue command, while the strokes for the letters 'p', 'i', and 't' do:

Also notice that the '&' character has no special power in the dictionary file, outside of curly braces:

In the above entry, the '&' in the output portion of the entry is just a regular ampersand. It only becomes a glue command inside curly braces. So when you stroke HED/PH-PBD/SHOULD/ERS, you get the exact output 'Head & Shoulders'.

Raw {#} Keyboard Inputs

A lot of computer software takes keyboard command sequences, and often these sequences use keys like CTRL, ESC, SHIFT, NumLock, F7, and so on. Plover allows you to define strokes that simulate pressing any key on the keyboard, in any simultaneous combination and in any sequential order. This feature can give you tremendous power over your computer, but it also comes with dangerous caveats. As we've seen, Plover will unhesitatingly guess at the meaning of a stroke, then back up and replace that stroke with another. If your software can't tolerate commands that back up and change, then you'll need to make sure none of the strokes for these commands have any conflicting matches in the dictionary file. And since the dictionary file changes over time as you refine it, you'll need to make sure no conflicts emerge over time.

Before explaining how to encode raw keyboard input, it may be useful to see the full list of available key names. These correspond exactly to the traditional names of key codes that a keyboard can send into to the computer.

Available Key Names

The following is the full set of keys that may be referenced with the '{#}' command in Plover (note that the Super_L and Super_R keys correspond to the command keys in OSX.):

Key Sequences

To define a dictionary entry that will send a series of keystrokes to your computer, list all the keys within the '{#}' command, separated by spaces:

The above entry will produce: