Prose linting with Vale and Flycheck in Emacs on FreeBSD
========================================================

Vale prose linting
------------------
Vale is a prose linting tool that runs on your local system.
Because Vale is build in Go, it can run on most operating
systems.

Vale works with so-called "style guides". Several style guides
are available, for example, from Microsoft, Google, RedHat,
and others. See [1].

Prose linting org mode files in Emacs on FreeBSD
------------------------------------------------
Emacs can be set up for prose linting of org-mode files with
Flycheck.

Below follows a description of how to set this up on FreeBSD.

Installation of Vale on FreeBSD
-------------------------------
Install Vale on FreeBSD with "pkg install vale".

Create a directory "~/.vale/styles" and populate it with
one or more style guides.

Clone the style guides from [2].

The cloned repository has a sub-directory with the style
guide.

An example how to install the write-good package:

    cd /tmp
    git clone https://github.com/errata-ai/write-good /tmp/write-good
    mv /tmp/write-good/write-good ~/.vale/styles/
    rm -rf /tmp/write-good

Repeat this for other packages you want to use.

Create the file ~/.vale.ini with the following contents:

    StylesPath = ~/.vale/styles

    MinAlertLevel = suggestion

    [*.org]
    BasedOnStyles = Vale, proselint, write-good, Readability

The line with "BasedOnStyles" should contain "Vale", and the packages
you have installed, separated with commas.

Test that Vale works
--------------------
Now test that Vale works. Take a text file, for example, "sample.txt"
and call Vale with this file:

    vale sample.txt
    
flycheck-org-vale
-----------------
Clone the Emacs package "flycheck-org-vale" from [3].

Add the configuration to your ~/.emacs file:

    (use-package flycheck
      :ensure t
      :init (global-flycheck-mode))

    (use-package flycheck-title
      :ensure t
      :after flycheck
      :config
      (flycheck-title-mode))

    (add-to-list 'load-path "~/.emacs.d/manualpackages/flycheck-org-vale")
    (require 'flycheck-org-vale)

Evaluate the ~/.emacs buffer or restart Emacs to activate the
added configuration.

Test the working
----------------
Open a org-mode file in Emacs. It should now show some words
in yellow or red.

Open the Flycheck error buffer, with "C-c ! l" (lowercase L).

Editing org-mode files
----------------------
Editing the org-mode file erases the Flycheck error buffer.
Saving the org-mode file (C-x C-s) updates the Flycheck error buffer.

Use "C-c ! n" and "C-c ! p" to jump to the next or previous Flycheck
error.

The Flycheck error buffer synchronizes with the position of the point
in the org-mode file.

Hit Enter on a line in the Flycheck error buffer to jump to the
specific line in the org-mode buffer.

Disable Flycheck for the current buffer with "C-c ! x".

[1]: https://vale.sh/hub/ Packages with style guides for Vale
[2]: https://github.com/errata-ai/packages Git repositories with style guides
[3]: https://github.com/grettke/flycheck-org-vale Git repository of flycheck-org-vale


Last edited: $Date: 2023/10/22 19:39:15 $