Spellcheck using Aspell and Makefiles

With an international community surrounding Kazoo it is important to provide tools that help everyone stay on the same page with the development cycle.

One of the challenges, as a native speaker of English, is how easily our brains 'fix' misspelt words without us realizing it. Often enough, PRs are accepted where a key into a JSON structure is misspelled and goes unnoticed, time passes until someone realizes the error, and now JSON documents using that key must be supported to prevent previously working data from failing to work now (ask about Kazoo's history with 'wednesday' in the temporal routes callflow action!).

Fortunately there's a nice command line tool, GNU Aspell, that provides spell checking capabilities and custom dictionaries. Aspell does a great job suggesting alternatives when finding a potentially misspelt word, making it easy to find the correct word (or add a word to a personal dictionary).

Personal dictionary

A personal dictionary is helpful to maintain a word list separate and apart from the "default" English dictionary Aspell provides, especially concerning acronyms and jargon specific to the project. When you spellcheck files and find words that are correct but unknown to Aspell, you can add them so Aspell knows not to highlight them again. These words are added to the personal dictionary. Being a plaintext file, the personal dictionary is also easily included in source control so you can distribute it with your project.

Personal replacements

The replacement file can contain automatic replacements; when Aspell encounters a word in the replacement file, it will replace it automatically with the replacement word. Really handy for oft-misspelt words.

Installation

Aspell should be available through most GNU/Linux distros.

Makefile setup

You can easily add a make target to spellcheck a project. Create a splchk.mk file and add: 

.PHONY = splchk

DICT = .aspell.en.pws
REPL = .aspell.en.prepl

$(DICT):
	@$(file >$(DICT),personal_ws-1.1 en 0 utf-8)

$(REPL):
	@$(file >$(REPL),personal_repl-1.1 en 0 utf-8)

splchk: $(DICT) $(REPL) $(addsuffix .chk,$(basename $(shell find . -name "*.md" )))

%.chk: %.md
	aspell --home-dir=. --personal=$(DICT) --repl=$(REPL) --lang=en -x check $<

Replace the $(shell find . -name "*.md") with whatever you want to use to find files to spellcheck.

When you run make splchk you will get the opportunity to check the spelling for each file found (if the file doesn't have any issues you won't deal with it). If you find a word that is correct but Aspell highlights it for repair, you can 'a'dd it which will include it in your personal dictionary.