#+TITLE:   checkers/spell
#+DATE:    January 9, 2020
#+SINCE:   v3.0.0
#+STARTUP: inlineimages nofold

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#maintainers][Maintainers]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
  - [[#changing-how-quickly-spell-fu-spellchecks-after-changes][Changing how quickly spell-fu spellchecks after changes]]
  - [[#reducing-false-positives-by-disabling-spelling-on-certain-faces][Reducing false positives by disabling spelling on certain faces]]
  - [[#adding-or-removing-words-to-your-personal-dictionary][Adding or removing words to your personal dictionary]]
- [[#troubleshooting][Troubleshooting]]

* Description
This modules provides spellchecking powered by =aspell= or =hunspell=.

Spellcheck is automatically loaded in all ~text-mode~ derivatives, which
includes ~org-mode~, ~markdown-mode~, the Git Commit buffer (from magit),
~mu4e-compose-mode~, and others.

** Maintainers
This module has no dedicated maintainers.

** Module Flags
+ =+aspell= Use =aspell= as a backend for correcting words.
+ =+hunspell= Use =hunspell= as a backend for correcting words.
+ =+everywhere= Use spellcheck in prog-mode and conf-mode derivatives as well as
  text-mode. Basically, enable =spell-fu-mode= everywhere.

** Plugins
+ [[https://gitlab.com/ideasman42/emacs-spell-fu][spell-fu]]

* Prerequisites
This module requires =aspell= to be installed, whether or not you intend to use
=hunspell= as the word correction backend. =spell-fu= does not yet support
generating the word list with a custom command or =hunspell=, but =hunspell= can
still be used to provide correction suggestions when invoking ~ispell-word~.

You will need =hunspell= installed (via your OS package manager) to use it as a
correction backend.

* Features
+ Spellchecking based on =aspell=.
+ Spell correction using =aspell= or =hunspell= (through ~M-x ispell-word~).
+ Ignores source code inside org or markdown files.

When using =+everywhere=, ~spell-fu-mode~ is activated for as many major modes
as possible, and not only ~text-mode~ derivatives. =spell-fu= will only spell
check comments in programming major modes.

* Configuration
Dictionary is set by =ispell-dictionary= variable. Can be changed locally with
the function =ispell-change-dictionary=.

** Changing how quickly spell-fu spellchecks after changes
Adjust ~spell-fu-idle-delay~ to change how long spell-fu waits to spellcheck
after recent changes (its default value as ~0.25~).

#+BEGIN_SRC elisp
(after! spell-fu
  (setq spell-fu-idle-delay 0.5))
#+END_SRC

** Reducing false positives by disabling spelling on certain faces
Exclude what faces to not preform spellchecking on by setting
~spell-fu-faces-exclude~ in a buffer-local hook:

#+BEGIN_SRC elisp
(setq-hook! 'markdown-mode-hook
  spell-fu-faces-exclude '(markdown-code-face
                           markdown-reference-face
                           markdown-link-face
                           markdown-url-face
                           markdown-markup-face
                           markdown-html-attr-value-face
                           markdown-html-attr-name-face
                           markdown-html-tag-name-face))
#+END_SRC

** Adding or removing words to your personal dictionary
Use ~M-x spell-fu-word-add~ and ~M-x spell-fu-word-remove~ to whitelist words
that you know are not misspellings.

* TODO Troubleshooting