para_chording

beta version: 0.5.7 (Feb 27, 2022)

Find me on:
Twitter: Joe Penna [@MysteryGuitarM]
Discord: Joe Penna (MysteryGuitarMan)#7614

Listen, I’m not a coder/hacker either. I’m a screenwriter.

Thing is… these programs below are so easy to figure out that I was able to code this entire chording solution by fumbling through
beginner example codes online. (And asking for help a couple times. Many times.)

Default Commands

First time here? Don’t worry about these yet.

⌃ control + ⌥ option + ⌘ command + i ► add instant chord
⌃ control + ⌥ option + ⌘ command + - ► open program folder
⌃ control + ⌥ option + ⌘ command + = ► update karabiner chord_list

Installation

Two [or three] programs you need to install:

Karabiner-Elements
- download link
- free / open source
- more instructions, if you need it
Keyboard Maestro
- download link
- technically a free trial, but you can use it indefinitely
- more instructions, if you need it

Note: Both Karabiner-Elements and Keyboard Maestro interact with your keyboard, so Mac OS will force you to give it 100 different permissions in:
System Preferences > Security and Privacy

[ Optional – Sublime Text 4 ]
- download link
- also technically a free trial, but you can use it indefinitely
- Sublime is expensive, but is a powerful text editor. It’ll help you write your chords later, but it’s easy enough to use TextEdit for free.

para_chording installation

para_chording installation
- download link
- These are the files I made to get you chording.

Sublime Text

I recommend you try out Sublime at first. Just download from the link above, unzip the file, and move Sublime Text to your Applications folder

Keyboard Maestro

run para_chording.kmmacros for the latest version
click installation, then Run
Keyboard Maestro will install para_chording for you. Then, it’ll open:

Karabiner-Elements

Under Devices
- Click the left-most checkmark on the keyboard you’d like to use.
- Mine is called Apple Internal Keyboard / Trackpad (Apple Inc.)
Under Complex Modifications
- Click ⊕ Add rule.
Next to para_chording
- Click the needlessly small Enable All button.
You’re done with installation!

Let’s Start Chording!

Open any text editor. I recommend TextEdit for now.

First, type t. Then, type h. Then, type e. Then, add a space.

How slow.

Instead, try to mash the all together — that’s your chord.

You should have gotten the + space — that’s your output.

By default, this program adds a space at the end of every output.

Other Ways of Chording

Now try to chord fj together.

You get the same output: the + space .

The letters of the chord don’t have to match the letters of the output.

You can have multiple chords with the same output (but each chord can only have one output).

fj for the seems like an odd choice, but consider the following:

The word the is the most common word in the English language.
It’s probably the word you type the most.
The keyboard in front of you probably has two easy-to-find nibs on the F and the J keys.
The index fingers usually rest on those two keys.
The term “semantic satiation” describes how you might be feeling about the word “the”.

Repeats and Shifts
Try chording fj repeatedly. You should get the the the.

If you press-and-hold fj, you just get the.

Try holding ⇧ shift down, then chord fj.

You get The. Repeatedly, you get The The The.

By default, I made it so that only the first letter is capitalized.
We’ll talk about how to capitalize the entire output in a bit.

Long Chords
Back in your text editor, move your fingers around until you press thm altogether. You get:

To Whom It May Concern,
►

Note the lack of space added.

Now chord obed, which will output:

I have the honor to be your obedient servant,

A.Ham

Also, note that you don’t have to hold a long chord while it types.

Unless you’re typing around 600 words per minute, you shouldn’t run into an issue with how long it takes to type.

Special Actions
If you mess up, try chording J + K. It’ll backspace one character.

Since your two strongest fingers are already resting on those keys, I find it way easier than reaching your pinky over to the delete button.

If you really mess up, try chording J + K + L. It’ll delete your whole word.

You can chord S + D + F to join the two previous words together.

Right now, you’ll get thethethethe — but try chording out… then side… then join those two chords together to create outside.

That’s three keystrokes instead of eight for the same output. Right now, it’ll feel a lot slower than just typing. In time, chording will be a time-saver.

There’s a reason stenographers chord everything into their steno machines (and can type way faster than the both of us combined).

Adding Your Own Chords

Try this keystroke (doesn’t need to be chorded):

⌃ control + ⌥ option + ⌘ command + i

This opens up:

Before you add any chords…

Numbers, lowercase and uppercase letters are allowed.
You can only use the symbols ! @ # $ % ^ & * ( ) { } = + and < . > / ? ; : ' " _ (underscore) - (hyphen) – (en-dash)
꧁ •𝕹𝖔 𝖜𝖊𝖎𝖗𝖉 𝖈𝖍𝖆𝖗𝖆𝖈𝖙𝖊𝖗𝖘 𝖔𝖗 𝖊𝖒𝖔𝖏𝖎𝖘• ꧂
Words in square brackets will be added before a chord as a [pre]fix.
~ means backspace (delete). We’ll get to why that’s important in a sec.

I’m not a good enough coder to stop you from breaking your chord list.
So, just try to stick to letters and numbers the simple stuff!

Try adding one now!

I did:

chord: luv
output: love

If you don’t want a space at the end of your output, add a # symbol to the end of your chord.
output: love will get you love+space.
output: love# will get you love.

More Advanced Concepts

If you wanna add lots of chords more easily, or to change / delete any chords, type:
⌃ control + ⌥ option + ⌘ command + - (hyphen)

This opens your program folder in Finder.

chord_lists
- Lots of .para that mesh together to create your chord library.
- More info about these below.
chord_lists backups
- backups of the chord_lists are made every time you:
  - add an instant chord.
  - run the manual chord_list update command.
  - If you’re changing your files often, a new backup of all folders is only made every hour.
documentation
- links to this document, and a document for developers.
full_chord_list_reference.csv
- this file gives you a full list of every chord in your library, in alphabetical order.
- you can open it with Excel or Numbers or Google Sheets.
- I wanted it to warn you about duplicate chords, and tell you which file each chord came from… but I don’t know how to do that.
  - please, developers — read the file above! I need help!

chord_list directory

Open it up. Inside, you’ve got a bunch of files.

You can just skim this info now and delve deep into later.

instant — February 21, 2022 – 2:57 PM
chord	output

instant_chords.para
- a list of chords added, with date and time as comments (see box above).

read_me examples.para
- The examples from this read_me.
- Feel free to delete this after you’re done reading through this document.

100 most common english words.txt
- A bunch of chords to get you started.
- Note the lack of two-letter words.

2-letter words.para
- chords for words like be, to, at, etc.
- read the notes here about why two-letter words can’t be chorded by themselves.

3-letter words.para
- chords for words like are, who, one, etc.
- Note the lack of non-three-letter words.

contractions.para
- chords for almost all common contractions like I'm, we'll, hasn't, etc.
- read the notes here about your options to use semi/colon vs. spacebar

emojis.para
- turns right_option + 12345... into 😊😟😃😅👍😡😮😛😂😬🤘🤷‍♂️
- change these defaults in Keyboard Maestro > para_emojis

numbers.para
- turns spacebar + 123... into one, two, three, etc.
- idea from lamb#9364 on Discord

punctuation.para
- adds prefixes [in brackets] and suffixes preceded by ~,
- prefixes like [pre], [un], [anti], etc.
  - as in prefix, unjust, antigen
- suffixes like ~ly, ~s, ~able, etc.
  - as in prefixly, unjusts, antigenable
- read the notes about the special ing and s/es macros

prefixes and suffixes.para
- adds prefixes [in brackets] and suffixes preceded by ~,
- prefixes like [pre], [un], [anti], etc.
  - as in prefix, unjust, antigen
- suffixes like ~ly, ~s, ~able, etc.
  - as in prefixly, unjusts, antigenable
- read the notes about the special ing and s/es macros

.para File Format

This program’s expecting text files in the chord_list directory with the following pattern:

The syntax of the file above was automatically highlighted with Sublime Text.

When you’re done changing your .para files around, you can update Karabiner with:
⌃ control + ⌥ option + ⌘ command + = (equal sign)

This (and other) key commands are at the top of this document.

Modifier Keys

I coded a few extra keys for you.

Modifiers For Chords and Outputs

backspace is the ~tilde key. Useful for suffixes.
:enter: can also be used either in chords or outputs.

Examples:

abon	abandon
ing		~ing

chording abon then ing outputs:
abandon+space then backspace+ing
abandoning

Lastly, the examples from earlier:

thm,To Whom It May Concern,:enter::enter:#
obed,I have the honor to be your obedient servant,:enter::enter:A.Ham

Your output must be an unbroken line.

Modifiers For Chords Only
These symbols can ONLY be part of your chord:

^ :left_control:
^ :right_control:

⌥ :left_option:
⌥:right_option:

⌘ :left_command:
⌘ :right_command:

⇧ :left_shift:
⇧ :right_shift:

They can be useful to differentiate chords for anagrammatic words. Remember that you could also use the spacebar as part of your chord:

	the					the
	the:right_option:	Theodore
	 the 				The Space Between Us
	//note the space before the chord above

Additional Keyboard Maestro Macros

para_chording was coded into Keyboard Maestro using three macro groups:

para_chording
- the main macro group, including installation, program folder shortcut, and chord_list manipulations.
- most people won’t have to touch this folder

para_emojis
- an easy way for you to change the default outputs accessed by chording right_option+123...

para_autofixes
- There are four macros in here that work in tandem with the main chording functionality of this program. If you find that the functionality of any of these macros doesn’t work with your typing style, right-click and choose Disable Macro.
- Delete extra space !?.,
  - Automatically deals with the extra space between a chord and punctuation .
- DOuble CAps REmoval
  - A way to fix common this common mistake while using character entry.
  - Avoids a few common exceptions like CDs OKs CCs BFs GFs TVs
- Replace ;tab with tab
  - Many applications use the tab key as navigation, which makes it hard to use things like Google Sheets to create chord lists.
  - This macro automatically replaces the typed string ;tab with the character.
- jkg ~ing and jks ~s/es
  - These are a work in progress. They attempt to add ing and s/es to words based on grammatical rules.
  - I’ve personally found these to be too slow to use while typing.
  - So, I disabled these, and enabled chords with the outputs:
    - ~d (e.g. love→loved)
    - ~ed (e.g. want→wanted)
    - ~ing (e.g. film → filming)
    - ~~ing (e.g. dance → dancing)

Final Remarks

This program is a work in progress.

Lots of people right now are trying to figure out what the best ways of chording with QWERTY / COLEMAK / DVORAK / etc.

Contact me – I’d love to hear your input on this!

Support The Little Guys
If you get some good use out of this program:

buy the Karabiner peeps a nice coffee
toss the Keyboard Maestro folks a few bucks
check out my PayPal page

Written with StackEdit.

Danc2050/para_chording