From: dbucklin@sdf.org
Date: 2019-06-15
Subject: Quick, Fix Your Diction

Writing is an important skill.  Writing well gives your words cred-
ibility and helps readers absorb your message.  Many tools will an-
alyze  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[1].  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 <leader>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.  Er-
ror 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  mes-
sages.   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  mis-
used.   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  sim-
ple.   Each  line  contains a phrase/suggestion pair separated by a
tab.  Here, I'm representing a literal tab with <TAB>.

     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 dic-
tion  can  be  used  to address some of my personal pet peeves.  My
database file will start out like this:

     learnings<TAB>(No.)
     operationalize<TAB>(Don't do this.)
     solutioning<TAB>(Please, no.)
     synergy<TAB>(Stop.)
     utilize<TAB>use

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 jar-
gon-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[2],  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.

References

[1]: https://www.gnu.org/software/diction/diction.html
[2]: https://github.com/w0rp/ale