merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,149 +1,154 @@
|
|||
#+TITLE: checkers/spell
|
||||
#+DATE: February 20, 2017
|
||||
#+SINCE: v2.0
|
||||
#+STARTUP: inlineimages nofold
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :checkers spell
|
||||
#+subtitle: Tasing you for misspelling mispelling
|
||||
#+created: February 20, 2017
|
||||
#+since: 2.0.0
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#maintainers][Maintainers]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#aspell][Aspell]]
|
||||
- [[#hunspell][Hunspell]]
|
||||
- [[#enchant][Enchant]]
|
||||
- [[#features][Features]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#changing-how-quickly-spell-fu-spellchecks-after-changes][Changing how quickly spell-fu spellchecks after changes]]
|
||||
- [[#spell-fu-users][Spell-fu users]]
|
||||
- [[#flyspell-users][Flyspell users]]
|
||||
- [[#reducing-false-positives-by-disabling-spelling-on-certain-faces][Reducing false positives by disabling spelling on certain faces]]
|
||||
- [[#spell-fu-users-1][Spell-fu users]]
|
||||
- [[#flyspell-users-1][Flyspell users]]
|
||||
- [[#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=, =hunspell= or =enchant=.
|
||||
* Description :unfold:
|
||||
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.
|
||||
|
||||
- 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 ([[doom-package:][ivy]] or [[doom-package:][helm]]).
|
||||
|
||||
** Maintainers
|
||||
This module has no dedicated maintainers.
|
||||
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** 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.
|
||||
+ =+enchant= Use =enchant-2= as a backend for correcting words.
|
||||
+ =+everywhere= Spell check in programming modes as well (in comments).
|
||||
** 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 only).
|
||||
- +flyspell ::
|
||||
Use [[doom-package:][flyspell]] instead of [[doom-package:][spell-fu]]. It's significantly slower, but supports
|
||||
multiple languages and dictionaries.
|
||||
- +hunspell ::
|
||||
Use =hunspell= as a backend for correcting words.
|
||||
|
||||
** Plugins
|
||||
+ if =+flyspell=
|
||||
+ [[https://github.com/d12frosted/flyspell-correct][flyspell-correct]]
|
||||
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-ivy-interface][flyspell-correct-ivy]] (=completion/ivy=)
|
||||
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-helm-interface][flyspell-correct-helm]] (=completion/helm=)
|
||||
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-popup-interface][flyspell-correct-popup]] (if *neither* =completion/ivy=, =completion/helm= or =completion/vertico=)
|
||||
+ [[https://github.com/rolandwalker/flyspell-lazy][flyspell-lazy]]
|
||||
+ else
|
||||
+ [[https://gitlab.com/ideasman42/emacs-spell-fu][spell-fu]]
|
||||
** Packages
|
||||
- if [[doom-module:][+flyspell]]
|
||||
- [[doom-package:][flyspell-correct]]
|
||||
- [[doom-package:][flyspell-correct-ivy]] if [[doom-module:][:completion ivy]]
|
||||
- [[doom-package:][flyspell-correct-helm]] if [[doom-module:][:completion helm]]
|
||||
- [[doom-package:][flyspell-correct-popup]] unless [[doom-module:][:completion ivy]], [[doom-module:][:completion helm]], or
|
||||
[[doom-module:][:completion vertico]]
|
||||
- [[doom-package:][flyspell-lazy]]
|
||||
- else
|
||||
- [[doom-package:][spell-fu]]
|
||||
|
||||
* 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).
|
||||
** Hacks
|
||||
/No hacks documented for this module./
|
||||
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
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).
|
||||
|
||||
#+begin_quote
|
||||
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.
|
||||
🚧 If you *are not* using [[doom-module:][+flyspell]], you will need =aspell= (and a dictionary)
|
||||
installed whether or not you have [[doom-module:][+hunspell]] or [[doom-module:][+enchant]] enabled. This is
|
||||
because [[doom-package:][spell-fu]] does not support generating the word list with anything
|
||||
other than =aspell= yet.
|
||||
#+end_quote
|
||||
|
||||
** Aspell
|
||||
+ Ubuntu: ~apt-get install aspell aspell-en~
|
||||
+ macOS: ~brew install aspell~
|
||||
+ Arch Linux: ~pacman -S aspell aspell-en~
|
||||
+ NixOS:
|
||||
#+BEGIN_SRC nix
|
||||
- Ubuntu: ~$ apt-get install aspell aspell-en~
|
||||
- macOS: ~$ brew install aspell~
|
||||
- Arch Linux: ~$ pacman -S aspell aspell-en~
|
||||
- NixOS:
|
||||
#+begin_src nix
|
||||
{
|
||||
environment.systemPackages = with pkgs; [
|
||||
(aspellWithDicts (dicts: with dicts; [ en en-computers en-science ]))
|
||||
];
|
||||
}
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** Hunspell
|
||||
+ Ubuntu: ~apt-get install hunspell~
|
||||
+ macOS: ~brew install hunspell~
|
||||
+ Arch Linux: ~pacman -S hunspell~
|
||||
+ NixOS:
|
||||
#+BEGIN_SRC nix
|
||||
- Ubuntu: ~$ apt-get install hunspell~
|
||||
- macOS: ~$ brew install hunspell~
|
||||
- Arch Linux: ~$ pacman -S hunspell~
|
||||
- NixOS:
|
||||
#+begin_src nix
|
||||
{
|
||||
environment.systemPackages = with pkgs; [
|
||||
hunspell
|
||||
];
|
||||
}
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** Enchant
|
||||
+ Ubuntu: ~apt-get install enchant-2~
|
||||
+ macOS: ~brew install enchant~
|
||||
+ Arch Linux: ~pacman -S enchant~
|
||||
+ NixOS:
|
||||
#+BEGIN_SRC nix
|
||||
- Ubuntu: ~$ apt-get install enchant-2~
|
||||
- macOS: ~$ brew install enchant~
|
||||
- Arch Linux: ~$ pacman -S enchant~
|
||||
- NixOS:
|
||||
#+begin_src nix
|
||||
{
|
||||
environment.systemPackages = with pkgs; [
|
||||
enchant
|
||||
];
|
||||
}
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
* Features
|
||||
+ 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=).
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
When using =+everywhere=, spell checking is performed for as many major modes as
|
||||
When using [[doom-module:][+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=.
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
** Changing how quickly spell-fu spellchecks after changes
|
||||
Dictionary is set by ~ispell-dictionary~ variable. Can be changed locally with
|
||||
the function ~ispell-change-dictionary~.
|
||||
|
||||
** Changing how quickly spelling is checked after changes
|
||||
*** Spell-fu users
|
||||
Adjust ~spell-fu-idle-delay~ to change how long Emacs waits to spellcheck after
|
||||
recent changes.
|
||||
#+BEGIN_SRC elisp
|
||||
recent changes:
|
||||
#+begin_src emacs-lisp
|
||||
(after! spell-fu
|
||||
(setq spell-fu-idle-delay 0.5)) ; default is 0.25
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
*** Flyspell users
|
||||
Lazy spellcheck is provided by =flyspell-lazy= package.
|
||||
Lazy spellcheck is provided by [[doom-package:][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).
|
||||
#+BEGIN_SRC elisp
|
||||
~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):
|
||||
#+begin_src emacs-lisp
|
||||
(after! flyspell
|
||||
(setq flyspell-lazy-idle-seconds 2))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** 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:
|
||||
#+BEGIN_SRC elisp
|
||||
#+begin_src emacs-lisp
|
||||
(setf (alist-get 'markdown-mode +spell-excluded-faces-alist)
|
||||
'(markdown-code-face
|
||||
markdown-reference-face
|
||||
|
|
@ -153,18 +158,19 @@ Users can exclude what faces to preform spellchecking on by adjusting
|
|||
markdown-html-attr-value-face
|
||||
markdown-html-attr-name-face
|
||||
markdown-html-tag-name-face))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
*** 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!~:
|
||||
#+BEGIN_SRC elisp
|
||||
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!~:
|
||||
#+begin_src emacs-lisp
|
||||
(set-flyspell-predicate! '(markdown-mode gfm-mode)
|
||||
#'+markdown-flyspell-word-p)
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
Flyspell predicates take no arguments and must return a boolean to determine if
|
||||
the word at point should be spell checked. For example:
|
||||
#+BEGIN_SRC elisp
|
||||
#+begin_src emacs-lisp
|
||||
(defun +markdown-flyspell-word-p ()
|
||||
"Return t if point is on a word that should be spell checked.
|
||||
|
||||
|
|
@ -183,13 +189,46 @@ Return nil if on a link url, markup, html, or references."
|
|||
for face in faces
|
||||
if (memq face unsafe-faces)
|
||||
return t)))))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** 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 =zg= and =zw=,
|
||||
respectively. =+flyspell= users can also add/remove words from the
|
||||
~flyspell-correct~ popup interface (there will be extra options on the list of
|
||||
you know are not misspellings. For evil users these are bound to [[kbd:][zg]] and [[kbd:][zw]],
|
||||
respectively. [[doom-module:][+flyspell]] users can also add/remove words from the
|
||||
[[doom-package:][flyspell-correct]] popup interface (there will be extra options on the list of
|
||||
corrections for "save word to dictionary").
|
||||
|
||||
* TODO Troubleshooting
|
||||
* Troubleshooting
|
||||
[[doom-report:][Report an issue?]]
|
||||
|
||||
** spell-fu highlights every single word
|
||||
[[doom-package:][spell-fu]] caches its word list. If it was activated before your dictionaries were
|
||||
installed, it will generate an empty word list, causing it to highlight all
|
||||
words as incorrect. Delete its cache files in =$EMACSDIR/.local/etc/spell-fu/=
|
||||
to fix this.
|
||||
|
||||
** Cannot add [word] to any active dictionary
|
||||
*** Aspell
|
||||
If ~M-x +spell/add-word~ results in the above error this mean that the
|
||||
personal dictionary file was not created for some reason. This can be
|
||||
fixed by creating the required file manually.
|
||||
#+begin_example shell
|
||||
mkdir -p ~/.emacs.d/.local/etc/ispell
|
||||
echo personal_ws-1.1 en 0 > ~/.emacs.d/.local/etc/ispell/.pws
|
||||
#+end_example
|
||||
|
||||
Where ~personal_ws-1.1 en 0~ is the required header format for the personal
|
||||
dictionary file. ~en~ is the language you're writing in and have a dict
|
||||
installed and ~0~ is the number of added words in the dictionary. If you are
|
||||
planning of updating the file with the list of words, update the number
|
||||
accordingly.
|
||||
|
||||
After the file is created, restart emacs and adding words should work.
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue