+++
date = "2021-03-29T22:55:17+00:00"
publishdate = "2023-12-29T07:08:55+00:00"
title = "Writing Articles with Vale"
slug = "writing-with-vale"
author = "Thedro"
tags = ["writing"]
type = "posts"
summary =  "If you've ever done any sort of continuous long form writing, you'll eventually discover that grammar and spell checking tools break down and become more of a distraction than a benefit."
draft =  ""
syntax =  "1"
toc =  ""
updated =  ""
+++

{{< image source="/images/writing-with-vale.png" title="Using Vale in the Vim text editor" >}}
Using Vale in the Vim text editor {{< /image >}}

If you've ever done any sort of continuous long form writing, you'll eventually
discover that grammar and spell checking
{{< sidenote mark="tools" set="right" >}} In Microsoft Word, LibreOffice Writer,
and other [`WYSIWYG`](https://en.wikipedia.org/wiki/WYSIWYG) (What You See Is What
You Get) editors. {{< /sidenote >}} break down and become more of a distraction
than a benefit. The "one size fits all" rules for grammar and spell checking
cannot hope to account for the indefinite amount of writing styles and
constantly evolving word constructions.

Writing is time consuming. How long does it take to write a long form document?
The answer not only depends on the writer, but also on the draft and review
process which often requires another pair of eyes. Many documents are checked by
hired professional editors and others yet
{{< sidenote mark="hire" set="left" >}} Don't have that luxury.
{{< /sidenote >}} freelancers to write for them.

For the soloist, and or casual writer, building a personal editor or another set
of eyes is useful, provided that you're willing to take on that time investment.
The idea is to target a specific writing style, construct the rules, and apply
it consistently to your documents.

[Vale](https://github.com/errata-ai/vale) is an
[open source](https://en.wikipedia.org/wiki/Open_source) program that
facilitates this approach --- it's a linter for writing documents. Vale offers
no opinion on how to write. You decide that for yourself by
{{< sidenote mark="collating" set="right" >}} Writing rules in
[`YAML`](https://yaml.org/) (YAML Ain't Markup Language). {{< /sidenote >}} a set
of grammatical rules and word primitives. Such flexibility allows you to emulate
the behaviour of applications like the
[Hemingway Editor.](https://hemingwayapp.com/) Vale is not the only program for
{{< sidenote mark="linting" set="left" >}} These linting tools seem to be very
popular among tech companies. {{< /sidenote >}} prose --- there are a plethora
of similar programs such as [textlint,](https://github.com/textlint/textlint)
[proselint,](https://github.com/amperser/proselint)
[redpen,](https://github.com/redpen-cc/redpen) or just basic
[regular expressions.](https://en.wikipedia.org/wiki/Regular_expression)

## Installation

Vale is available on {{< sidenote mark="most" set="left" >}} MacOS, Windows, and
Linux based operating systems. {{< /sidenote >}} major platforms. Install `vale`
for your specific operating system by following the install
[documentation.](https://docs.errata.ai/vale/install) Predefined style templates
are
[available for download](https://github.com/errata-ai/styles#available-styles)
if you need a starting point.

In my case, a wrapper in `~/.local/bin/vale` is setup around the canonical
`vale` to allow {{< sidenote mark="optionally" set="right" >}} Additional
argument for running `vale --update` at the command line level.
{{< /sidenote >}} downloading a few writing style templates and setting up my
configuration directory.

```shell {options="hl_lines=7-14"}
#!/bin/sh -eu

directory="$XDG_CONFIG_HOME/vale"
styles="$directory/styles"
mkdir -p "$directory" "$styles";

if [ "${1:-}" = "--update" ]; then
  svn export --force https://github.com/errata-ai/Google/trunk/Google         "$styles/google";
  svn export --force https://github.com/errata-ai/joblint/trunk/Joblint       "$styles/joblint";
  svn export --force https://github.com/errata-ai/Microsoft/trunk/Microsoft   "$styles/microsoft";
  svn export --force https://github.com/errata-ai/proselint/trunk/proselint   "$styles/proselint";
  svn export --force https://github.com/errata-ai/write-good/trunk/write-good "$styles/write-good";
  exit;
fi

$(which vale --all | grep --invert-match "local/bin" | head -n 1) --config "$directory/vale.ini" "$@";
```

The `vale.ini` configuration file is simple. Set a directory containing the
styles, adjust the minimum alerting level, and activate the desired writing
styles. The typical usage pattern is `vale document.txt` at the command line.

```ini {options="hl_lines=1-2 10-13"}
StylesPath = /home/thedro/.config/vale/styles
MinAlertLevel = suggestion

[*.{md,txt}]
#BasedOnStyles = google
#BasedOnStyles = joblint
#BasedOnStyles = microsoft
#BasedOnStyles = proselint
#BasedOnStyles = write-good
BasedOnStyles = hemingway
BasedOnStyles = dickens
BasedOnStyles = technical
BasedOnStyles = thedro
```

Emulating a [style](https://docs.errata.ai/vale/styles#existence) requires
reading {{< sidenote mark="deeply" set="right" >}} Many
[popular style guides](https://en.wikipedia.org/wiki/List_of_style_guides) are
out there if you'd rather not. {{< /sidenote >}} into the patterns of an
author's writing. Here is a snippet of a rule set taken from the `write-good`
[style](https://github.com/errata-ai/write-good/tree/master/write-good) that
checks for [weasel words.](https://en.wikipedia.org/wiki/Weasel_word)

```yaml
extends: existence
message: "'%s' is a weasel word!"
ignorecase: true
level: warning
tokens:
  - absolutely
  - accidentally
  - additionally
  - allegedly
  - alternatively
  - angrily
  - anxiously
  - approximately
```

Styles are the named directories that contain a set of `YAML` rule sets.
Construct as many rules as you want to complement the desired style.

```shell
$ tree -L 3 ~/.config/vale
___ styles
|   |__ google
|   |   |__ Contractions.yml
|   |__ joblint
|   |   |__ Acronyms.yml
|   |__ microsoft
|   |   |__ Wordiness.yml
|   |__ proselint
|   |   |__ Spelling.yml
|   |__ write-good
|       |__ Weasel.yml
|__ vale.ini
```

## Conclusion

This approach obviously requires time as you work to build up a robust rule set
for a particular style. The general idea is to correct mistakes, tokenize them
as rules, and iterate constantly. You'll have a tight feedback loop that at a
minimum guards the consistency of your writing, and improves your writing speed
over time. Perhaps we should take my work in progress clickbait writing style
for {{< sidenote mark="spin" set="right" >}} Not really. {{< /sidenote >}}
sometime.

```ini
BasedOnStyles = clickbait
```