doomemacs/modules/checkers/spell/README.org

checkers/spell

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
  • Aspell
  • Hunspell
• Features
• Configuration
  • Changing how quickly spell-fu spellchecks after changes
    • Spell-fu users
    • Flyspell users
  • Reducing false positives by disabling spelling on certain faces
    • Spell-fu users
    • Flyspell users
  • Adding or removing words to your personal dictionary
• Troubleshooting

Description

This modules provides spellchecking powered by aspell or hunspell.

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.

Maintainers

This module has no dedicated maintainers.

Module Flags

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

Plugins

• if +flyspell

  • flyspell-correct
  • flyspell-correct-ivy (completion/ivy)
  • flyspell-correct-helm (completion/helm)
  • flyspell-correct-popup (if neither completion/ivy or completion/helm)
  • flyspell-lazy

• else

  • spell-fu

Prerequisites

This module requires one of aspell or hunspell 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 enabled. This is because spell-fu does not support generating the word list with anything other than aspell yet.

Aspell

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

• NixOS:

  {
    environment.systemPackages = with pkgs; [
      aspell
      aspellDicts.en
      aspellDicts.en-computers
      aspellDicts.en-science
    ];
  }

TODO Hunspell

Features

• Spell checking and correction using aspell or hunspell.
• 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.

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

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

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))

Reducing false positives by disabling spelling on certain faces

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))

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)))))

Adding or removing words to your personal dictionary

Spell-fu users can call M-x spell-fu-word-add and M-x spell-fu-word-remove to whitelist words that you know are not misspellings. These are on zq and zw, respectively, for users with Evil enabled.

Neither ispell nor +flyspell support managing personal dictionaries within Emacs.

TODO Troubleshooting