Quick, Fix Your Diction

Writing is an important skill. Writing well gives your words credibility and helps readers absorb your message. Many tools will analyze your writing and suggest improvements. If the command line is your milieu, GNU diction deserves a place in your toolchain.

To get started, install GNU diction. If your distribution uses apt, try:

apt install diction

GNU diction source is available at gnu.org. Once installed, run diction followed by a filename to get a list of suggestions.

You can use the output from diction to populate the quickfix list in Vim. To do this for the current buffer,

:cex system('diction -s '.expand('%'))

I have this mapped to i. This runs diction and gives it the file name of the current buffer. Results are loaded into the quickfix list and Vim will move the cursor to the first error. Error messages will appear below the status line where you can see them as you make adjustments to your document. Now you can jump from one error location to the next, fixing things up as you go.

To make navigation easier, I stole the following mappings from Tim Pope.

nnoremap ]q :cnext<cr>
nnoremap ]Q :clast<cr>
nnoremap [q :cprev<cr>
nnoremap [Q :cfirst<cr>

Some of the error messages given by diction can be quite long. These errors will be abbreviated when shown below the status line. To see the full message, open the quickfix window with :copen. Within the quickfix window, you can browse through the error messages. Using :.cc or pressing enter on a quickfix item will take you to the corresponding location. Close the quickfix window with :cclose.

Characterizing diction's output as “errors” isn't really accurate. Diction identifies common phrases that are overused or often misused. It gives you the opportunity to focus on these problem phrases and to improve your writing. With the -s option, diction also provides guidance and specific suggestions.

The database that diction uses to generate errors and suggestions lives in /usr/share/diction/en (for English). The format is simple. Each line contains a phrase/suggestion pair separated by a tab. Here, I'm representing a literal tab with .

in terms of<TAB>in, for, about (or avoid)

Phrases can be aliased to another phrase by starting the suggestion value with an ‘=’ followed by a space and the target phrase.

alluded<TAB>= allude

With diction, we can specify our own database file to be used in addition to, or instead of, the provided database. That means diction can be used to address some of my personal pet peeves. My database file will start out like this:

operationalize<TAB>(Don't do this.)
solutioning<TAB>(Please, no.)

It's short, but my other pet peeves, “in terms of” and “comprise”, are already included in diction's database.

With the -n option, diction will bypass the default dictionary. This lets us use only our own custom dictionary. This opens up some interesting possibilities. For example, if your work is jargon-heavy, you could create a custom database to provide guidance on usage. For certain kinds of configuration files, diction could be used to provide guidance on setting configuration values.

If you are already using Ale for Vim, I believe linters are available for prose. I haven't used this, but the goal is the same. Once set up, I'll bet using Ale provides a more integrated, if not better, experience. Where diction only matches your writing against a list of pre-determined phrases, a linter should be able to recognize parts of speech and provide guidance on syntax and spelling all in one go.