branch: externals/flymake-codespell
commit 816d7dd5d9919e9ff42c2b1dd1e6504fd553c17b
Author: Stefan Kangas <stefankan...@gmail.com>
Commit: Stefan Kangas <stefankan...@gmail.com>
Add README.org
---
README.org | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 99 insertions(+), 7 deletions(-)
diff --git a/README.org b/README.org
index 56aa35c1d5..185b716ac7 100644
--- a/README.org
+++ b/README.org
@@ -1,12 +1,100 @@
-#+TITLE: test
-#+DATE: 2022-12-09
-#+AUTHOR: Stefan Kangas
-#+EMAIL: stefankan...@gmail.com
-
* flymake-codespell
+This adds a [[https://github.com/codespell-project/codespell][codespell]]
backend for
[[https://www.gnu.org/software/emacs/manual/html_node/flymake/index.html][flymake-mode]]
in Emacs.
+
+In comparison to other spellcheckers, codespell does not have a
+dictionary of known words. Instead it has a list of common typos, and
+checks only for those. This means that it's far less likely to
+generate false positives, especially when used on source code, or
+technical documentation and research.
+
+* Prerequisites
+
+First, install ~codespell~. For example, if you're using Debian
+GNU/Linux, run this command in a terminal:
+
+: sudo apt install codespell
+
+For other distributions, it is something very similar to that.
+
+* Quick start
+
+If you're impatient, simply copy and paste this into your init file:
+
+: (use-package flymake-codespell
+: :ensure t
+: :hook (prog-mode . flymake-codespell-setup-backend))
+
+This will enable ~flymake-codespell~ in all programming language
+modes, and automatically install it the next time you restart Emacs.
+The above example works out-of-the-box on Emacs 29. For older
+versions, you must first install ~use-package~.
+
+* Installation
+
+You may also install codespell using ~pip~, or similar.
+
+Once codespell is installed, install this package by typing the
+following in Emacs:
+
+: M-x package-install RET codespell-flymake RET
+
+* Usage
+
+You must make sure the ~flymake-codespell-setup-backend~ function is
+called in the modes where you want to use it.
+
+For example, let's say you want to use it in all programming language
+modes. To make sure it is run in ~prog-mode~, which all programming
+language modes inherit, add the following line to your init file:
+: (add-hook 'prog-mode-hook 'flymake-codespell-setup-backend)
+You can substitute ~prog-mode-hook~ for the hook relevant to any mode
+you want. Some typical examples would be ~org-mode~, ~tex-mode~, and
+~markdown-mode~.
+
+* Usage with use-package
+
+With ~use-package~, available out-of-the-box in Emacs 29 and from GNU
+ELPA for older versions, simply add the following to your init file:
+
+: (use-package flymake-codespell
+: :ensure t
+: :hook (prog-mode . flymake-codespell-setup-backend))
+
+The ~:ensure t~ part makes sure the package is automatically installed
+when you're starting Emacs, if it isn't already.
+
+To add this to several modes, use something like the following:
+
+: (use-package flymake-codespell
+: :ensure t
+: :hook ((prog-mode . flymake-codespell-setup-backend)
+: (text-mode . flymake-codespell-setup-backend)))
+
+The ~text-mode~ hook will add this also to all modes inheriting
+~text-mode~ (but not special modes).
+
+You must also enable flymake, of course. This is documented in the
+~flymake~ manual, but here's a ~use-package~ declaration:
+
+: (use-package flymake
+: :hook prog-mode)
+
+* Alternatives
+
+Here are some alternatives to codespell-flymake:
+
+-
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Spelling.html#index-flyspell_002dprog_002dmode][flyspell-prog-mode]],
which comes with Emacs out-of-the-box.
+
+* Contribute
+
+This library is part of [[https://elpa.gnu.org/packages/url-scgi.html][GNU
ELPA]] and therefore requires a
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html][copyright
assignment]]
+to the [[https://www.fsf.org/][Free Software Foundation]] for any non-trivial
contributions.
+
+Please email me a patch, or open a pull request on GitHub, according
+to your preferences.
* Contact
@@ -14,5 +102,9 @@ You can find the latest version of flymake-codespell here:
https://www.github.com/skangas/flymake-codespell
-Bug reports, comments, and suggestions are welcome! Send them to Stefan Kangas
-<stefankan...@gmail.com> or report them on GitHub.
+Bug reports, comments, and suggestions are welcome! Send them to
+Stefan Kangas <stefankan...@gmail.com> or report them on GitHub.
+
+#+DATE: 2022-12-09
+#+AUTHOR: Stefan Kangas
+#+EMAIL: stefankan...@gmail.com
