Dictionary format: Difference between revisions

From Plover Wiki
(add external links)
m (Aerick moved page Dictionary Format to Dictionary format: Sentence case)
 
(16 intermediate revisions by 3 users not shown)
Line 4: Line 4:


* A ''stroke'' is a group of keyboard keys that are pressed simultaneously to produce output. As soon as all keys on the keyboard are released, the steno machine sends out that entire chord of key presses as a stroke.  
* A ''stroke'' is a group of keyboard keys that are pressed simultaneously to produce output. As soon as all keys on the keyboard are released, the steno machine sends out that entire chord of key presses as a stroke.  
* Plover converts that input into English words and phrases on the screen, by using _dictionaries_
* Plover converts that input into English words and phrases on the screen, by using ''dictionaries''
* symbol, emoji, software command, or a meta command for controlling spacing and capitalization.
* with Plover, outputs are not limited to characters and punctuation symbols... Yes, a real stenographer chords emoji😅
* Steno machines makes use of either defined software command, or a meta command, for controlling spacing and capitalization.
* Every stenographer creates their own customized dictionary to supplement or amend the default dictionary that comes with a steno application, such as Plover. By default, you add your customizations to the <code>user.json</code> dictionary that comes with Plover.
* Every stenographer creates their own customized dictionary to supplement or amend the default dictionary that comes with a steno application, such as Plover. By default, you add your customizations to the <code>user.json</code> dictionary that comes with Plover.


Line 20: Line 21:
If two dictionaries contain the same steno strokes, Plover will use the one in the dictionary that has the highest priority. The dictionaries in the dictionary list are prioritised from the bottom up.
If two dictionaries contain the same steno strokes, Plover will use the one in the dictionary that has the highest priority. The dictionaries in the dictionary list are prioritised from the bottom up.


By default, the <code>user.json</code> dictionary is placed at the bottom of the dictionary list and has the highest priority. If you want new strokes to go to different dictionary (for example, you have your own dictionary already), make sure that dictionary is at the bottom of the list.<blockquote>'''Note:''' With Plover 4.0+, default dictionary priority is now top-down and can be changed.  In the configuration settings, you can select your preferred ordering of dictionary priority to be bottom-up or top-down.</blockquote>
By default, the <code>user.json</code> dictionary is placed at the bottom of the dictionary list and has the highest priority. If you want new strokes to go to different dictionary (for example, you have your own dictionary already), make sure that dictionary is at the bottom of the list.{{Info|text=With Plover 4.0+, default dictionary priority is now top-down and can be changed.  In the configuration settings, you can select your preferred ordering of dictionary priority to be bottom-up or top-down.}}


== JSON and RTF/CRE ==
== Dictionary File Formats ==
Plover supports two types of dictionaries:
Plover is (or will be) able to import dictionaries from other steno programs. Here are some technical notes on each file format.


* '''JSON''' (the default and recommended format), and
Some formats (including those not listed here) may require installation of a dedicated plugin.
* '''RTF/CRE'''.
{{Info|text=There is a plugin <code>plover-python-dictionary</code> available in the [[Plugins#Via the built-in Plugins Manager (recommended)|plugins manager]] that allows you to use Python (<code>.py</code>) dictionaries. After installing the plugin, you will need to restart Plover before it will let you load Python dictionaries.}}
 
RTF/CRE is an import/export format used by proprietary steno software. This means Plover can work with exported dictionaries from Eclipse, ProCAT, Case CATalyst, and other steno software applications.<blockquote>'''Note:''' With Plover 4.0+, there is a plugin <code>plover-python-dictionary</code> that allows you to use Python (<code>.py</code>) dictionaries. After installing the plugin, you will need to restart Plover before it will let you load Python dictionaries.</blockquote>


=== Limitations ===
=== Limitations ===
Line 36: Line 35:
* The JSON format that Plover uses is not used or supported by other steno applications. If you want to move or copy your Plover JSON formatted dictionary to another steno software application, you will need to convert it to RTF.
* The JSON format that Plover uses is not used or supported by other steno applications. If you want to move or copy your Plover JSON formatted dictionary to another steno software application, you will need to convert it to RTF.
* The Plover JSON format doesn't have support for stroke metadata. At the moment, Plover doesn't support reading/writing of RTF metadata.
* The Plover JSON format doesn't have support for stroke metadata. At the moment, Plover doesn't support reading/writing of RTF metadata.
=== json ===
The standard Plover format. Described at Dictionary format.
=== rtf (aka CRE) ===
A standard interchange format. Described at http://www.legalxml.org/workgroups/substantive/transcripts/cre-spec.htm .
RTF/CRE is an import/export format used by proprietary steno software. This means Plover can work with exported dictionaries from Eclipse, ProCAT, Case CATalyst, and other steno software applications.
=== dct (aka Stentura, Jet, MDB, Microsoft Access) ===
These are standard Microsoft Access databases (otherwise known as Microsoft Jet databases, or MDB files. They contain a single table named &quot;Steno&quot;, which has columns named &quot;Steno&quot;, &quot;English&quot;, and &quot;Flags&quot;. Each row represents a translation.
&quot;Steno&quot; is a text column containing the stroke, encoded as a concatenated sequence of six-digit hex strings representing bitmasks; each bit represents a key in the standard steno order
&quot;English&quot; is a text column giving the text translation of that stroke.
&quot;Flags&quot; is an integer bitmap. 0x8000 indicates a suffix; 0x4000 indicates a prefix; 0x2000 indicates that the next word should be capitalised.
Python lacks good cross-platform MDB support, so Plover reads the files using pure Python.
=== sgdct (CaseCat) ===
CaseCATalyst dictionaries have the extension &quot;.sgdct&quot;. There is often a corresponding &quot;.sgxml&quot; file, but this contains no dictionary data.
Much of the detail of the file format remains unknown. Contributions and corrections are very welcome. Thanks are due to Sooty, who provided example files for dissection.
The files begin with a 640-byte header, which begins with the magic number SGCAT32. Nothing is known about header fields at present.
One or more records follow the header. Each record gives a single translation from steno to text.
The record header is 21 bytes. header[18] contains the number of strokes, and header[19] gives the number of letters in the text. Each is an unsigned byte. The purpose of all other fields in the record header is unknown at present.
The stroke follows, as a sequence of four-byte unsigned integers. Each integer is a bitmap of keys in the standard steno order, with the first &quot;S&quot; as the most significant bit.
Then the text follows, as ordinary ASCII text. Nothing is currently known about coding of text outside the ASCII range. Various non-ASCII characters crop up, apparently as control codes.
Finally, there are zero to three padding bytes, in order to bring us up to a four-byte boundary.


== Plover Control Commands ==
== Plover Control Commands ==
Line 110: Line 144:


== Sending Symbols ==
== Sending Symbols ==
Since Plover 3.0.0, users can write full Unicode. You can use symbols in your JSON dictionary, or paste them into the "Add Translation" dialog (or into the dictionary manager). You can get symbols from a character insert panel in your operating system (if you have one), or you can copy and paste symbols from another application, such as a web browser.
Since Plover 3.0.0, users can write full Unicode. You can use symbols in your JSON dictionary, or paste them into the "<kbd><samp>Add Translation</samp></kbd>" dialog (or into the dictionary manager). You can get symbols from a character insert panel in your operating system (if you have one), or you can copy and paste symbols from another application, such as a web browser.
  <code>{
  <code>{
   "SHR*UG": "¯\\_(ツ)_/¯",
   "SHR*UG": "¯\\_(ツ)_/¯",
Line 207: Line 241:


The default dictionary for Plover should use these operators where appropriate.
The default dictionary for Plover should use these operators where appropriate.
  <code>{
  {
   "KW-GS": "{~|\"^}",
   "KW-GS": "{~|\"^}",
   "KR-GS": "{^~|\"}",
   "KR-GS": "{^~|\"}",
Line 213: Line 247:
   "PREPB": "{~|(^}",
   "PREPB": "{~|(^}",
   "PR*EPB": "{^~|)}"
   "PR*EPB": "{^~|)}"
  }</code>
  }
For a newline, the syntax would be <code>{^~|\n^}</code>.
For a newline, the syntax would be <code>{^~|\n^}</code>.


Line 471: Line 505:
|-
|-
|Common Named Keys
|Common Named Keys
|<code>= equal</code><nowiki><br /></nowiki><code>- minus</code><nowiki><br /></nowiki><code>[ bracketleft</code><nowiki><br /></nowiki><code>] bracketright</code><nowiki><br /></nowiki><code>/ slash</code><nowiki><br /></nowiki><code>\ backslash</code><nowiki><br /></nowiki><code>' quoteright</code><nowiki><br /></nowiki><code>, comma</code><nowiki><br /></nowiki><code>. period</code><nowiki><br /></nowiki><code>; semicolon</code><nowiki><br /></nowiki><code>~ asciitilde</code><nowiki><br /></nowiki><code>^ asciicircum</code><nowiki><br /></nowiki><code>` quoteleft</code><nowiki><br /></nowiki>[https://github.com/openstenoproject/plover/blob/master/plover/key_combo.py#L21 …and more]
|<code>= equal</code><code>- minus</code><code>[ bracketleft</code><code>] bracketright</code><code>/ slash</code><code>\ backslash</code><code>' quoteright</code><code>, comma</code><code>. period</code><code>; semicolon</code><code>~ asciitilde</code><code>^ asciicircum</code><code>` quoteleft</code>[https://github.com/openstenoproject/plover/blob/master/plover/key_combo.py#L21 …and more]
|-
|-
|Media Keys
|Media Keys
|'''Common''': <code>AudioRaiseVolume</code>, <code>AudioLowerVolume</code>, <code>AudioMute</code>, <code>AudioNext</code>, <code>AudioPrev</code>, <code>AudioStop</code>, <code>AudioPlay</code>, <code>AudioPause</code>, <code>Eject</code><nowiki><br /></nowiki>'''Mac''': <code>MonBrightnessUp</code>, <code>MonBrightnessDown</code>, <code>KbdBrightnessUp</code>, <code>KbdBrightnessDown</code><nowiki><br /></nowiki>'''Windows''': <code>Back</code>, <code>Forward</code>, <code>Refresh</code><nowiki><br /></nowiki>'''Linux''': XF86 key names are supported, for example <code>XF86_MonBrightnessUp</code> - refer to the [https://github.com/python-xlib/python-xlib/blob/master/Xlib/keysymdef/xf86.py definition file in <code>python-xlib</code>] for the key names.
|'''Common''': <code>AudioRaiseVolume</code>, <code>AudioLowerVolume</code>, <code>AudioMute</code>, <code>AudioNext</code>, <code>AudioPrev</code>, <code>AudioStop</code>, <code>AudioPlay</code>, <code>AudioPause</code>, <code>Eject</code>'''Mac''': <code>MonBrightnessUp</code>, <code>MonBrightnessDown</code>, <code>KbdBrightnessUp</code>, <code>KbdBrightnessDown</code>
'''Windows''': <code>Back</code>, <code>Forward</code>, <code>Refresh</code>'''Linux''': XF86 key names are supported, for example <code>XF86_MonBrightnessUp</code> - refer to the [https://github.com/python-xlib/python-xlib/blob/master/Xlib/keysymdef/xf86.py definition file in <code>python-xlib</code>] for the key names.
|}
|}
Consult the code for the [https://github.com/openstenoproject/plover/blob/master/plover/key_combo.py#L21 full list of supported keyboard shortcut keys].
Consult the code for the [https://github.com/openstenoproject/plover/blob/master/plover/key_combo.py#L21 full list of supported keyboard shortcut keys].
Line 514: Line 549:
Special case: <code>=content</code> might be interpreted as the invocation of a macro named <code>content</code>. Use <code>{#}=content</code> instead.
Special case: <code>=content</code> might be interpreted as the invocation of a macro named <code>content</code>. Use <code>{#}=content</code> instead.


If you edit the JSON file directly rather than with Plover's built-in editor/"Add translation" feature, you need to escape those characters in addition, according to JSON syntax:
If you edit the JSON file directly rather than with Plover's built-in editor/ [[File:Translation add.svg|link=|32px]][[Built-in_Tools#Add_translation_dialog|Add translation feature]], you need to escape those characters in addition, according to JSON syntax:
{| class="wikitable"
{| class="wikitable"
!Symbol
!Symbol
Line 592: Line 627:
|<code><\> <\> <n></code>
|<code><\> <\> <n></code>
|}
|}
Column explanation:
Column explanation:


* JSON: how the entry is stored in the JSON file.
; '''JSON:'''
* Plover show: how the entry is displayed in Plover "Add translation" dialog. (version 4)
:how the entry is stored in the JSON file.
* Plover input: how the entry can be added to the dictionary using Plover "Add translation" dialog. <code>(none)</code> means it's only possible to obtain the entry by editing the JSON in an external editor.
; '''Plover show:'''
* Plover output: what Plover will send to the emulated keyboard when that stroke is pressed.
:how the entry is displayed in Plover [[File:Translation add.svg|link=|32px]] "[[Built-in_Tools#Add_translation_dialog|Add translation]]" dialog. (version 4)
; '''Plover input:'''
:how the entry can be added to the dictionary using Plover "[[Built-in_Tools#Add_translation_dialog|Add translation]]" dialog. <code>(none)</code> means it's only possible to obtain the entry by editing the JSON in an external editor.
; '''Plover output:'''
:what Plover will send to the emulated keyboard when that stroke is pressed.


=== "Do Nothing" Translation ===
=== "Do Nothing" Translation ===
Line 687: Line 727:
  "TK-FPS":"{*!}"
  "TK-FPS":"{*!}"
  }</code>
  }</code>
<blockquote>'''Note:''' The final entry must not have a trailing comma.</blockquote>
<blockquote>{{Info-Info|text=''Note:'' The final entry '''must not''' have a trailing comma.}}</blockquote>
 
 
 
[[Category:Plover]]
[[Category:Plover]]

Latest revision as of 03:48, 17 August 2024

About Strokes and Dictionaries

If you are new to stenography:

  • A stroke is a group of keyboard keys that are pressed simultaneously to produce output. As soon as all keys on the keyboard are released, the steno machine sends out that entire chord of key presses as a stroke.
  • Plover converts that input into English words and phrases on the screen, by using dictionaries
  • with Plover, outputs are not limited to characters and punctuation symbols... Yes, a real stenographer chords emoji😅
  • Steno machines makes use of either defined software command, or a meta command, for controlling spacing and capitalization.
  • Every stenographer creates their own customized dictionary to supplement or amend the default dictionary that comes with a steno application, such as Plover. By default, you add your customizations to the user.json dictionary that comes with Plover.

Plover's Default Dictionaries

Plover comes supplied with three dictionaries:

  • main.json. This contains the default dictionary. It is based on Mirabai Knight's own personal dictionary, which follows a StenEd-style theory. It contains over 140,000 entries and is adequate for anyone learning stenography. Mirabai uses this dictionary professionally for her realtime work.
  • commands.json. This contains Plover Control Commands.
  • user.json. This is available for your personal customizations. user.json is a blank dictionary. By default, the user.json dictionary is at the bottom of the dictionary list and has the highest priority - it is the first dictionary Plover will use. When you define new strokes, they will get added to this dictionary. This means you can see which strokes you've defined yourself, instead of trying to locate them inside the default dictionaries.

You can add extra dictionaries to Plover, as well. Dictionaries may be located on your system in any directory/folder; they do not have to be in a subdirectory/subfolder of the Plover installation.

Note: We do not recommend you remove the commands.json dictionary from the dictionary list. This is because Plover has some concepts that users of other steno software will not be familiar with initially.

Dictionary priority

If two dictionaries contain the same steno strokes, Plover will use the one in the dictionary that has the highest priority. The dictionaries in the dictionary list are prioritised from the bottom up.

By default, the user.json dictionary is placed at the bottom of the dictionary list and has the highest priority. If you want new strokes to go to different dictionary (for example, you have your own dictionary already), make sure that dictionary is at the bottom of the list.

format=frameless
format=frameless

With Plover 4.0+, default dictionary priority is now top-down and can be changed. In the configuration settings, you can select your preferred ordering of dictionary priority to be bottom-up or top-down.

Dictionary File Formats

Plover is (or will be) able to import dictionaries from other steno programs. Here are some technical notes on each file format.

Some formats (including those not listed here) may require installation of a dedicated plugin.

format=frameless
format=frameless

There is a plugin plover-python-dictionary available in the plugins manager that allows you to use Python (.py) dictionaries. After installing the plugin, you will need to restart Plover before it will let you load Python dictionaries.

Limitations

There are some limitations with each format:

  • RTF dictionaries will cause Plover to take longer to start up and won't have Unicode support.
  • The JSON format that Plover uses is not used or supported by other steno applications. If you want to move or copy your Plover JSON formatted dictionary to another steno software application, you will need to convert it to RTF.
  • The Plover JSON format doesn't have support for stroke metadata. At the moment, Plover doesn't support reading/writing of RTF metadata.

json

The standard Plover format. Described at Dictionary format.

rtf (aka CRE)

A standard interchange format. Described at http://www.legalxml.org/workgroups/substantive/transcripts/cre-spec.htm .

RTF/CRE is an import/export format used by proprietary steno software. This means Plover can work with exported dictionaries from Eclipse, ProCAT, Case CATalyst, and other steno software applications.

dct (aka Stentura, Jet, MDB, Microsoft Access)

These are standard Microsoft Access databases (otherwise known as Microsoft Jet databases, or MDB files. They contain a single table named "Steno", which has columns named "Steno", "English", and "Flags". Each row represents a translation.

"Steno" is a text column containing the stroke, encoded as a concatenated sequence of six-digit hex strings representing bitmasks; each bit represents a key in the standard steno order

"English" is a text column giving the text translation of that stroke.

"Flags" is an integer bitmap. 0x8000 indicates a suffix; 0x4000 indicates a prefix; 0x2000 indicates that the next word should be capitalised.

Python lacks good cross-platform MDB support, so Plover reads the files using pure Python.

sgdct (CaseCat)

CaseCATalyst dictionaries have the extension ".sgdct". There is often a corresponding ".sgxml" file, but this contains no dictionary data.

Much of the detail of the file format remains unknown. Contributions and corrections are very welcome. Thanks are due to Sooty, who provided example files for dissection.

The files begin with a 640-byte header, which begins with the magic number SGCAT32. Nothing is known about header fields at present.

One or more records follow the header. Each record gives a single translation from steno to text.

The record header is 21 bytes. header[18] contains the number of strokes, and header[19] gives the number of letters in the text. Each is an unsigned byte. The purpose of all other fields in the record header is unknown at present.

The stroke follows, as a sequence of four-byte unsigned integers. Each integer is a bitmap of keys in the standard steno order, with the first "S" as the most significant bit.

Then the text follows, as ordinary ASCII text. Nothing is currently known about coding of text outside the ASCII range. Various non-ASCII characters crop up, apparently as control codes.

Finally, there are zero to three padding bytes, in order to bring us up to a four-byte boundary.

Plover Control Commands

You can control some aspects of Plover with strokes. Plover's default dictionary (commands.json) contains these commands:

Command name Command Default Stroke Description
Add Translation {PLOVER:ADD_TRANSLATION} TKUPT (think DUPT for "Dictionary UPdaTe") Opens a translation window where you can enter a stroke and translation text to create a new dictionary entry.
Disable Output {PLOVER:SUSPEND} PHRO*F (think PLOF for "PLover OFf") Stop translating steno. With a keyboard machine, you will be able to type normally again.
Enable Output {PLOVER:RESUME} PHRO*PB (think PLON for "PLover ON") Re-enable Plover's output. You can write this stroke to switch back from your keyboard into steno mode.
Toggle Output {PLOVER:TOGGLE} PHROLG (think PLOLG, for PLOver toGGLe) Toggle between output being enabled and disabled.

These commands are not in commands.json by default, but can be added to a dictionary:

Command name Command Suggested Stroke Description
Look Up Stroke {PLOVER:LOOKUP} PHR*UP Open a search dialog that you write a translation into to get a list of entries in your dictionaries.
Suggestions {PLOVER:SUGGESTIONS} PHROGS (think PLOSHUN) for PLOver suggesTION) Open and focus the plover suggestions window which will suggest alternative ways of writing
Configure {PLOVER:CONFIGURE} PHROFG (think PLOFG, for PLOver conFiG) Open and focus the Plover configuration window.
Focus {PLOVER:FOCUS} PHROFBGS (think PLOFKS, for PLOver focus) Open and focus the main Plover window.
Quit {PLOVER:QUIT} PHROBGT (think PLOKT, for PLOver quit) Quit Plover entirely.
Set configuration {PLOVER:SET_CONFIG:option:value}, {PLOVER:SET_CONFIG:option1:value1,option2:value2,...} Set Plover config option.

Example for SET_CONFIG Plover command:

  • {PLOVER:SET_CONFIG:'translation_frame_opacity':100}
  • {PLOVER:SET_CONFIG:'start_attached':True,'start_capitalized':True}

As a side effect, SET_CONFIG also reload the (changed) dictionaries.

Sending Symbols

Since Plover 3.0.0, users can write full Unicode. You can use symbols in your JSON dictionary, or paste them into the "Add Translation" dialog (or into the dictionary manager). You can get symbols from a character insert panel in your operating system (if you have one), or you can copy and paste symbols from another application, such as a web browser.

{
  "SHR*UG": "¯\\_(ツ)_/¯",
  "TR*PL": "{^}™",
  "TPHA*ES": "n̶o̶ yes"
}

Prefix strokes

It's possible to select the translation for a stroke depends on whether the previous word is finished.

Given the dictionary:

{
    "S": "word",
    "/S": "{prefix^}"
}

with a stroke S, the translation "/S": "{prefix^}" is chosen; unless the previous word is not finished (for example if the previous translation is {con^}), then the translation "S": "word" is chosen.

It's possible to explicitly mark a translation as "finished" with {$} (or equivalently {:word_end}).

See this blackbox test for an example.

Text Formatting

Prefixes, Infixes, and Suffixes

Strokes can be attached at the beginning and/or end using the "attach" operator. You can also use some of the built-in orthographic rules that Plover uses for creating intelligent strokes.

  • {^} is the attach operator.
  • {^ish} is an orthographic-aware suffix that will add "ish" to the end of the previous word. E.g. RED/EURB will output reddish. Note: addition of a second "d" caused by Plover's understanding of English orthography.
  • {^}ish is a suffix with the text outside the operator—this means that the text will simply be attached without grammar rules. Using this stroke in the previous example would give instead redish.
  • {^-to-^} is an infix, e.g. day-to-day.
  • {in^} is a prefix, e.g. influx.
  • Most custom punctuation entries will take advantage of the attach operator, e.g. {^—^} for an emdash.

Glue Operator (Numbers, Fingerspelling)

Glue is sort of like the attach operator above, except that "glued" strokes only attach to neighboring "glue" strokes.

Translations containing only digits are glued, allowing you to output multiple number strokes to make a large number.

  • {&} is the glue operator.
  • {&a}, {&b}, {&c}, etc. are how the fingerspelling alphabet is made.
  • {&th} is a multiletter glue stroke, which can be useful (TH* in the default dictionary)

Because glued translations only glue to other glued translations, they won't attach to regular words. This gives us some power because you can write:

THR/-R/#H/#A/KATS to get "there are 45 cats" and only #H (4) and #A (5) are "glued" to each other.

Capitalizing

Capitalizing a word means turning the first letter into a capital, e.g. proper nouns and in titles. Usually your dictionary has capitals pre-defined, but there are times when you need to capitalize a word on the go.

Capitalize Next Word

  • {-|}

The next word will have a capitalized first letter. In the default dictionary, we have "KPA": "{-|}", which will capitalize the next word; and "KPA*": "{^}{-|}" which omits a space and capitalizes the next word. That last stroke would let you writeLikeThis. This formatting style is called "camel case', which some programmers use in their work.

Capitalize next word can also be used in name titles, like Ms. {-|}.

Default strokes:

  • KPA: {-|} (think "cap")
  • KPA*: {^}{-|} (also suppresses space)

Capitalize Last Word

  • {*-|}

The last stroke word will have a capitalized first letter. This is useful in case you realize that a word should be capitalized after you've written it. It can also be used in a stroke, like in {*-|}{^ville}. This would capitalize the last word and attach to it. This would be useful for town names on the fly, such as Catville.

Suggested stroke: KA*PD

Uncapitalizing

Uncapitalize Next Word

  • {>}

Forces the next letter to be lowercase, e.g. {>}Ploverplover

Suggested stroke: HRO*ER (lower)

Uncapitalize Last Word

  • {*>}

Rewrite the last word to start with a lowercase letter, e.g. Plover{*>}plover

Suggested stroke: HRO*ERD (lowered)

Carrying Capitalization

  • {~|text} or {^~|text^} where the attach operator is optional and the text can be changed.

In English, we have punctuation that doesn't get capitalized, but instead the next letter gets the capitalization. For example, if you end a sentence in quotes, the next sentence still starts with a capital letter! "You can't eat that!" The baby ate on.

In order to support this, there is a special pre/in/suffix syntax that will "pass on" or "carry" the capitalized state. You might find this useful with quotes, parentheses, and words like 'til or 'cause.

The default dictionary for Plover should use these operators where appropriate.

{
  "KW-GS": "{~|\"^}",
  "KR-GS": "{^~|\"}",
  "KA*US": "{~|'^}cause",
  "PREPB": "{~|(^}",
  "PR*EPB": "{^~|)}"
}

For a newline, the syntax would be {^~|\n^}.

Uppercasing (CAPS)

See Output Modes for CAPS mode, which acts like CAPS lock on a regular keyboard. Alternatively, you can use a Keyboard Shortcut set to {#Caps_Lock} to activate the system CAPS lock like you can on your keyboard.

Suggested stroke: "KA*PS": "{MODE:CAPS}"

Uppercase Next Word

  • {<}

Output next stroke in capital letters, e.g. {<}catCAT

Suggested stroke: KPA*L (cap all)

Uppercase Last Word

  • {*<}

Rewrite last word in capital letters, e.g. cat{*<}CAT

Suggested stroke: *UPD

Spacing

Suppress Next Space

  • {^^} (or {^})

See also: Retroactively Delete Space

Default stroke: TK-LS (Delete Space)

This is a special case of an infix. See also Prefixes, Infixes, and Suffixes.

Manually Add a Space

  • {^ ^}

See also: Retroactively Add Space

Default stroke: S-P (SPace)

This is a special case of an infix. See also Prefixes, Infixes, and Suffixes.

Canceling Formatting of Next Word

In order to cancel formatting of the next word, use the empty meta tag as your definition:

  • {}

Using {} in front of a arrow key commands, as in {}{#Left}, is useful if the arrow key commands are used to move cursor to edit text. Canceling formatting actions for cursor movement prevents Plover from, for instance, capitalizing words in middle of a sentence if cursor is moved back when the last stroke, such as {.}, includes action to capitalize next word.

See also the "do nothing" translation

Format Currency

There is a built-in meta in Plover that allows you to format the last-written number as currency. The format is {*($c)} where $ is any currency symbol you'd like, and c is the amount, formatted in standard currency format, with either no decimals or two. Commas are added every 3 numbers before the decimal automatically.

  • {*($c)}: Standard English dollars
    • 23{*($c)} → $23
    • 2000.5{*($c)} → $2,000.50
  • {*($c CAD)}: You can include other text, e.g. when specifying a currency's country
    • 100{*($c CAD)} → $100 CAD
  • {*(c円)}: The symbol can be placed on either side of the number, which often happens in languages other than English and in certain regions.
    • 2345{*(c円)}: 2,345円

Here are some other currency symbols, in case you need to copy-paste them into your entries: £, ¥, €, $, ₩, ¢

Conditional

  • {=regex/text_if_match/text_if_no_match}

Conditional translation depending on the following text. Outputs text_if_match if the following text matches the regex, otherwise outputs text_if_no_match. Regex is case-sensitive. For example, {=[AEIOUaeiou]/an/a} outputs "a" unless the next word starts with a vowel, in which case it outputs "an".

Friendly Command Names

In a sufficiently-new Plover version, it's possible to use friendly names for some commands/metas.

For detailed descriptions of the commands, see the other sections.

Command/macro/meta Equivalent
{*} =retrospective_toggle_asterisk
{*!} =retrospective_delete_space
{*?} =retrospective_insert_space
{*+} =repeat_last_stroke
{^} {:attach}
{^word} {:attach:^word}
{word^} {:attach:word^}
{^word^} {:attach:word}
{&a} {:glue:a}
{-\|} {:case:cap_first_word}
{*-\|} {:retro_case:cap_first_word}
{~\|word} {:carry_capitalize:word}
{<} {:case:upper_first_word}
{*<} {:retro_case:upper_first_word}
{>} {:case:lower_first_char}
{*>} {:retro_case:lower_first_char}
{*($c)} {:retro_currency:$c}
{#shift(a)} {:key_combo:shift(a)}
{PLOVER:LOOKUP} {:command:LOOKUP}
{MODE:CAPS} {:mode:CAPS}
{.} {:stop:.}
{,} {:comma:,}
{$} {:word_end}

Note that currently the {#a} form will be interpreted literally in the "Strokes" text box of the Plover "Add Translation" dialog box, however entering a stroke mapped to {:key_combo:a} will enter the raw stroke into the text box.

Undoable Line Breaks and Tabs

When you use keyboard shortcuts, the asterisk/undo command on Plover will not have any effect. This is a limitation imposed by the fact that most commands will not have a meaningful undo. For example, you wouldn't "undo" a "copy" command. For this reason, {#return} and {#tab} don't work how many users would expect.

Instead, we must use special characters that can be undone by Plover for new paragraphs and erasable tabs. Specifically:

  • \n or \r for line breaks.
  • \t for tabs.

For example:

  • {^\n^}{-|} This translation would create a line break without spacing and then capitalize the next word. It can be removed with the asterisk key.
  • {^\t^} This translation presses the tab key without any other spacing. It can be undone with the asterisk key.

Macros

Macros can be mapped from a stroke and perform operations on the stroke-level. This means that it can perform actions based on previous strokes, not necessarily on previous words or translations.

Undo / Delete Last Stroke

  • =undo

The built-in "undo" macro is assigned to the asterisk key *. You can map other strokes to "undo" or "delete last stroke" by creating a stroke where the translation is =undo

Repeat Last Stroke

  • {*+} A stroke mapping to this macro will send the last stroke entered. A common stroke to map to repeat-last is the bare number bar; "#": "{*+}"; causing KAT/#/# to behave like KAT/KAT/KAT. Repeat last stroke {*+} is very useful for keys that you repeat. For example, when you are moving around text in a document.

Suggested stroke: #

Toggle asterisk

  • {*} A stroke mapping to this macro will toggle the asterisk key on the last stroke entered. For example, if you had this stroke in your dictionary as Number Bar + Asterisk, "#*": "{*}", when you write KAT/#* it will behave as if you wrote KA*T. Toggle asterisk {*} is useful for when you notice that you should have included an asterisk in your last stroke. For example, you wanted to write the name "Mark" (a person's name), but you wrote "mark" (the noun/verb). At this point, you can use Toggle asterisk {*} to correct it. You wouldn't have to erase the word and re-stroke it (this time, with you including the missing the asterisk).

Suggested stroke: #*

Retroactively Add Space

  • {*?} A stroke mapping to this macro will add a space between your last stroke and the one before that, splitting apart the two strokes. For example, if your dictionary contained PER as "Perfect", SWAEUGS as "Situation" and PER/SWAEUGS as "Persuasion". If you meant to write "Perfect situation", but saw your output was "Persuasion", you could force these two strokes to be split apart by using the {*?} stroke. This means your output would change on the screen from "Persuasion" to "Perfect situation".

Suggested stroke: AFPS (add space)

Retroactively Delete Space

  • {*!} A stroke mapping to this macro will delete the space between your last stroke and the one before that. If you wrote "Basket ball" but wanted it to be "Basketball", you could force these strokes together by using the {*!} stroke. Plover will go back and remove the space before your last stroke; As a result, your output would become "Basketball".

Suggested stroke: TK-FPS (delete space)

Keyboard Shortcuts

Most Plover strokes are just text and formatting operators. Plover handles standard strokes really well. This allows it to handle "undoing" with the asterisk key, as well as automatically handling case and spacing. However, Plover's text and formatting strokes can't send arbitrary key strokes, such as sending keyboard shortcuts.

Note: Plover 3.1 introduces new rules for commands that differ slightly from the previous implementation. Before Plover 3.1, commands were used to send symbols because Plover didn't have full Unicode support. It used to be possible to send "+" by writing {#plus}, but the system has been updated.

  • {#} is the command operator.

Inside of a command block, you write in what keys you want Plover to simulate. The keys hit in command blocks won't be "undone" when using the asterisk (because you can't backspace a keyboard shortcut). You select the keys by their name. All key names will only refer to the base key. For example, to use letter keys, you just use the corresponding letter (case insensitive) separated by spaces:

  • {#a b c d} will send "abcd" and will not affect Plover's text formatting or asterisk undo-buffer.

You can also use key names, which is needed when you are accessing a symbol key. For example, on the QWERTY layout there is an equal/plus key in the top right, which you can access by either of its names:

  • {#equal plus} will send "==". Plover doesn't send modifiers. It just hits the key based on the name.

If you want to send symbols, though, don't use commands. Commands should be used for keyboard shortcuts only. Instead, use the symbol in your dictionary entry.

Modifier Names

If you want to use a modifier, use it by name (e.g. Shift_L). For convenience, all key names are case insensitive and you can optionally default to the left modifier by dropping the side selector:

Modifier Command Key Names (case-insensitive)
Shift Shift_L, Shift_R, shift
Control Control_L, Control_R, control
Alt Alt_L, Alt_R, alt, option
Super Super_L, Super_R, super, windows, command

For modifiers, use parentheses to delimit where the keys are pressed down.

Shortcut Key Names

Here are the key names you'll want to use:

Keys Command Key Names (case-insensitive)
Letters a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
Accented Letters (international layouts) udiaeresis, eacute, etc.
Numbers 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
Control Keys Escape, Tab, Caps_Lock, space, BackSpace, Delete, Return, etc.
F-Keys F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12
Common Named Keys = equal- minus[ bracketleft] bracketright/ slash\ backslash' quoteright, comma. period; semicolon~ asciitilde^ asciicircum` quoteleft…and more
Media Keys Common: AudioRaiseVolume, AudioLowerVolume, AudioMute, AudioNext, AudioPrev, AudioStop, AudioPlay, AudioPause, EjectMac: MonBrightnessUp, MonBrightnessDown, KbdBrightnessUp, KbdBrightnessDown

Windows: Back, Forward, RefreshLinux: XF86 key names are supported, for example XF86_MonBrightnessUp - refer to the definition file in python-xlib for the key names.

Consult the code for the full list of supported keyboard shortcut keys.

Note: a key name will determine a key to emulate with no modifiers based on your keyboard layout. For example, let's say we want to make a keyboard shortcut to hit shift-2 which is "@" in QWERTY: {#at} will only press the 2 key. To get the @ symbol, we need to add the shift key: {#shift(at)}, which is functionally the same as {#shift(2)}.

Example Shortcuts

Here are some shortcuts. They are in JSON format:

  • "STPH-G": "{#right}" — right arrow on the keyboard, for moving the cursor to the right once
  • "SKWR-G": "{#shift(right)}" — shift and right arrow on the keyboard, for selecting one character
  • "SKWR-BG": "{#control(shift(right))}" — shift, control, and right arrow on the keyboard, for selecting one word to the right on Windows/Linux
  • "SKWR-BG": "{#option(shift(right))}" — option (alt), control, and right arrow on the keyboard, for selecting one word to the right on Mac

These next strokes are not particularly useful, but they show you what you can do with the command syntax:

  • "TKAO*UP": "{#control(c v v v)}" — copy, then paste 3 times
  • "SKPH-Z": "{#control(z shift(z))" — program-dependent, but possibly "undo/redo". Notice how the first z has only the control operator, and the second has both the control and the shift operator.

Commands are case insensitive - adding capitals will not affect the output. {#control(z shift(z)) is the same as "{#CONTROL_L(Z SHIFT(Z))}"

Escaping Special Characters

Most symbols (e.g. +, =, ~, r) can just be included directly in the definition. But some symbols are part of the dictionary syntax and so need to be escaped:

Symbol Escaped Form
\ \\
{ \{
} \}

\ is a special case. It must be escaped only if there's any possible ambiguity.

Special case: =content might be interpreted as the invocation of a macro named content. Use {#}=content instead.

If you edit the JSON file directly rather than with Plover's built-in editor/ Add translation feature, you need to escape those characters in addition, according to JSON syntax:

Symbol Escaped Form
\ \\
" \"

Example:

JSON Plover show Plover input Plover output
"ab" ab ab <a> <b>
"\\{" \{ \{ <{>
"\\\\{" \\{ \\{ <\> <{>
"\"" " " <">
"\\" \ \ <\>
"\\\\" \\ \\ <\> <\>
"\\\\\\" \\\ \\\ <\> <\> <\>
"\n" \n \n <\n>
"\\n" \\n \\n <\> <n>
"\\x" \x \x <\> <x>
"\\\n" \\n (none) <\> <\n>
"\\\\n" \\\n \\\n <\> <\> <n>

Column explanation:

JSON:
how the entry is stored in the JSON file.
Plover show:
how the entry is displayed in Plover "Add translation" dialog. (version 4)
Plover input:
how the entry can be added to the dictionary using Plover "Add translation" dialog. (none) means it's only possible to obtain the entry by editing the JSON in an external editor.
Plover output:
what Plover will send to the emulated keyboard when that stroke is pressed.

"Do Nothing" Translation

You can use the keyboard shortcut syntax ({#}) if you want a stroke that effectively does nothing. For example: a null or canceled stroke, which doesn't affect formatting, doesn't output anything, and cannot be "undone" with the asterisk key. A stroke mapped to {#} will effectively do nothing but show up in your logs.

  • {#} an effective "null" stroke.

See also: Canceling Formatting of Next Word

Output Modes

  • {MODE:} is the mode operator

Plover supports special character casing, such as CAPS LOCK and Title Case. It also supports replacing its implicit space with other characters. This is useful for when you want to write_in_snake_case.

Output modes are activated with a special syntax in your dictionary. They can be a stroke or just part of a stroke. They can then be turned off with a special reset command.

An example flow for CAPS LOCK might be:

  1. Turn on CAPS LOCK.
  2. Write in capital letters.
  3. Turn off CAPS LOCK.

However, there's nothing stopping you from building in output modes into your strokes. For example, you might want your new paragraph stroke to reset the case mode, no matter what.

Reset Command

You can reset the output mode to its default with {MODE:RESET}.

Important: We recommended you have a reset output mode command, so that you can always reset Plover's output mode. This is in case you change it by accident.

  • {MODE:RESET}: Reset the case and space character. We recommended this for getting out of any custom output mode. For example: "R-R": "{^~|\n^}{MODE:RESET}" and "TPEFBG": "{#escape}{MODE:RESET}"
  • {MODE:RESET_CASE}: Exit caps, lower, or title case.
  • {MODE:RESET_SPACE}: Use spaces as normal.

Modes

There are some built-in modes you can use:

Dictionary Syntax Sample Output
{MODE:CAPS} THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG.
{MODE:TITLE} The Quick Brown Fox Jumps Over The Lazy Dog.
{MODE:LOWER} the quick brown fox jumps over the lazy dog.
{MODE:CAMEL} theQuickBrownFoxJumpsOverTheLazyDog.
{MODE:SNAKE} The_quick_brown_fox_jumps_over_the_lazy_dog.

Custom Modes

You can define your own custom modes with the SET_SPACE: operator. This allows you to replace the space that Plover outputs with anything. Plover's snake-mode is the same as SET_SPACE:_.

Here are some other examples:

Dictionary Syntax Sample Output
{MODE:SET_SPACE:} Thequickbrownfoxjumpsoverthelazydog.
{MODE:SET_SPACE:-} The-quick-brown-fox-jumps-over-the-lazy-dog.
{MODE:SET_SPACE:😁} The😁quick😁brown😁fox😁jumps😁over😁the😁lazy😁dog.

Summary of suggested commands you can cut and paste into your dictionary

Here is a summary of the suggested commands you can cut and paste into your personal dictionary:

{
"PHR*UP":"{PLOVER:LOOKUP}",
"PHROFG":"{PLOVER:CONFIGURE}",
"PHROFBGS":"{PLOVER:FOCUS}",
"PHROBGT":"{PLOVER:QUIT}",
"KA*PD":"{*-|}",
"KA*PS":"{MODE:CAPS}",
"KPA*L":"{<}",
"*UPD":"{*<}",
"HRO*ER":"{>}",
"HRO*ERD":"{*>}",
"#":"{*+}",
"#*":"{*}",
"AFPS":"{*?}",
"TK-FPS":"{*!}"
}

Template:Info-Info