:checkers spell

Tasing you for misspelling mispelling

1. Description

This modules provides spellchecking powered by aspell, hunspell or enchant.

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

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

+aspell
Use aspell as a backend for correcting words.
+enchant
Use enchant-2 as a backend for correcting words.
+everywhere
Spell check in programming modes as well (in comments).
+flyspell
Use flyspell instead of spell-fu. It’s significantly slower, but supports multiple languages and dictionaries.
+hunspell
Use hunspell as a backend for correcting words.

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

This module requires one of aspell, hunspell or enchant-2 installed on your system and in your $PATH. They also need dictionaries for your language(s).

If you are not using +flyspell, you will need aspell (and a dictionary) installed whether or not you have +hunspell or +enchant enabled. This is because spell-fu does not support generating the word list with anything other than aspell yet.

2.1. Aspell

  • Ubuntu: $ apt-get install aspell aspell-en
  • macOS: $ brew install aspell
  • Arch Linux: $ pacman -S aspell aspell-en

  • NixOS:

    # ⎘
    {
  environment.systemPackages = with pkgs; [
    (aspellWithDicts (dicts: with dicts; [ en en-computers en-science ]))
  ];
}

2.2. Hunspell

  • Ubuntu: $ apt-get install hunspell
  • macOS: $ brew install hunspell
  • Arch Linux: $ pacman -S hunspell

  • NixOS:

    # ⎘
    {
  environment.systemPackages = with pkgs; [
    hunspell
  ];
}

2.3. Enchant

  • Ubuntu: $ apt-get install enchant-2
  • macOS: $ brew install enchant
  • Arch Linux: $ pacman -S enchant

  • NixOS:

    # ⎘
    {
  environment.systemPackages = with pkgs; [
    enchant
  ];
}

    Enchant is just a wrapper for other spelling libraries and you will need to have at least one of the supported backends installed as well.

3. Usage

  • Spell checking and correction using aspell, hunspell or enchant.
  • Ignores source code inside org or markdown files.
  • Lazily spellchecking recent changes only when idle.
  • Choosing suggestions using completion interfaces (ivy or helm).

When using +everywhere, spell checking is performed for as many major modes as possible, and not only text-mode derivatives. e.g. in comments for programming major modes.

4. Configuration

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

4.1. Changing how quickly spell-fu spellchecks after changes

4.1.1. Spell-fu users

Adjust spell-fu-idle-delay to change how long Emacs waits to spellcheck after recent changes:

# ⎘
(after! spell-fu
  (setq spell-fu-idle-delay 0.5))  ; default is 0.25

4.1.2. Flyspell users

Lazy spellcheck is provided by flyspell-lazy package.

flyspell-lazy-idle-seconds sets how many idle seconds until spellchecking recent changes (default as 1), while flyspell-lazy-window-idle-seconds sets how many seconds until the whole window is spellchecked (default as 3).

# ⎘
(after! flyspell
  (setq flyspell-lazy-idle-seconds 2))

4.2. Reducing false positives by disabling spelling on certain faces

4.2.1. Spell-fu users

Users can exclude what faces to preform spellchecking on by adjusting +spell-excluded-faces-alist in a buffer-local hook:

# ⎘
(setf (alist-get 'markdown-mode +spell-excluded-faces-alist)
      '(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))

4.2.2. Flyspell users

Flyspell will run a series of predicate functions to determine if a word should be spell checked. You can add your own with set-flyspell-predicate!:

# ⎘
(set-flyspell-predicate! '(markdown-mode gfm-mode)
  #'+markdown-flyspell-word-p)

Flyspell predicates take no arguments and must return a boolean to determine if the word at point should be spell checked. For example:

# ⎘
(defun +markdown-flyspell-word-p ()
  "Return t if point is on a word that should be spell checked.

Return nil if on a link url, markup, html, or references."
  (let ((faces (doom-enlist (get-text-property (point) 'face))))
    (or (and (memq 'font-lock-comment-face faces)
	     (memq 'markdown-code-face faces))
	(not (cl-loop with unsafe-faces = '(markdown-reference-face
					    markdown-url-face
					    markdown-markup-face
					    markdown-comment-face
					    markdown-html-attr-name-face
					    markdown-html-attr-value-face
					    markdown-html-tag-name-face
					    markdown-code-face)
		      for face in faces
		      if (memq face unsafe-faces)
		      return t)))))

4.3. Adding or removing words to your personal dictionary

Use M-x +spell/add-word and M-x +spell/remove-word to whitelist words that you know are not misspellings. For evil users these are bound to z g and z w, respectively. +flyspell users can also add/remove words from the flyspell-correct popup interface (there will be extra options on the list of corrections for “save word to dictionary”).

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?