[elpa] externals/jit-spell 0184eaef11 5/7: Add a README and commentary section

[ELPA Syncer]

branch: externals/jit-spell
commit 0184eaef11539ec4c37560d0506aff774bcf3acb
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Add a README and commentary section
---
 README.org   | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 jit-spell.el | 24 ++++++++++++++++++++--
 2 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..722ec6db1b
--- /dev/null
+++ b/README.org
@@ -0,0 +1,66 @@
+#+title: jit-spell --- Just-in-time spell checking
+
+#+html: <p align="center"><a 
href="http://elpa.gnu.org/packages/jit-spell.html";><img alt="GNU ELPA" 
src="https://elpa.gnu.org/packages/jit-spell.svg"/></a></p>
+#+html: <p align="center"><a 
href="http://elpa.gnu.org/devel/jit-spell.html";><img alt="GNU ELPA" 
src="https://elpa.gnu.org/devel/jit-spell.svg"/></a></p>
+
+jit-spell is a spell-checking package for Emacs.  It highlights all
+misspelled words in a window, just like a word processor or web
+browser does.
+
+#+caption: Correcting a misspelling with jit-spell
+[[https://raw.githubusercontent.com/astoff/jit-spell/images/screenshot.png]]
+
+This behavior is different from the built-in Flyspell package, which
+only checks words as the cursor moves over them.  Moreover, unlike
+Flyspell, jit-spell communicates with the spell-checking subprocess
+entirely asynchronously, which can lead to a noticeable performance
+improvement.
+
+jit-spell is part of [[https://elpa.gnu.org][GNU ELPA]] and can be installed 
with
+=M-x package-install RET jit-spell RET=.
+
+** Usage
+
+To enable spell checking in a buffer, type =M-x jit-spell-mode RET=.
+To correct a misspelling, you can right-click the word (assuming you
+have =context-menu-mode= activated) or call the command
+=jit-spell-correct-word=, which uses the minibuffer to read a
+correction or accept the word.
+
+To make your settings permanent, you may wish to add some variant of
+the following to your init file:
+
+#+begin_src emacs-lisp
+(add-hook 'text-mode-hook 'jit-spell-mode)
+(add-hook 'prog-mode-hook 'jit-spell-mode)
+(with-eval-after-load 'jit-spell
+  (define-key jit-spell-mode-map (kbd "C-;") 'jit-spell-correct-word))
+#+end_src
+
+To pick a spell checker and dictionaries, jit-spell uses Emacs's
+built-in ispell support code.  Try =M-x customize-group ispell RET=
+to see a listing of all possible settings.
+
+** Major mode support
+
+Some major modes require special settings to avoid checking irrelevant
+parts of the buffer.
+
+The simplest mechanism to achieve that is the user option
+=jit-spell-ignored-faces=.  Any word fontified with one of these faces
+is ignored for spell-checking purposes.  To find out which faces are
+present on a given character, you can use =M-x describe-char=.
+
+In all programming language modes, spell checking is restricted to
+comments, docstring and strings.  This can be modified by customizing
+the variable =jit-spell-prog-mode-faces=.
+
+Some modes, such as Org and TeX-related modes, require more extensive
+adaptations.  This is not yet provided as I am evaluating the possible
+approaches.
+
+** Contributing
+
+Discussions, suggestions and code contributions are welcome! Since
+this package is part of GNU ELPA, contributions require a copyright
+assignment to the FSF.
diff --git a/jit-spell.el b/jit-spell.el
index 62e61e7839..a1e048e903 100644
--- a/jit-spell.el
+++ b/jit-spell.el
@@ -1,6 +1,6 @@
 ;;; jit-spell.el --- Just-in-time spell checking      -*- lexical-binding: t; 
-*-
 
-;; Copyright (C) 2023  Augusto Stoffel
+;; Copyright (C) 2023  Free Software Foundation, Inc.
 
 ;; Author: Augusto Stoffel <arstoffel@gmail.com>
 ;; Keywords: tools, wp
@@ -23,7 +23,27 @@
 
 ;;; Commentary:
 
-;; TODO
+;; This package provides `jit-spell-mode', a local minor mode to
+;; highlight all misspelled words in a window, just like a word
+;; processor or web browser does.
+;;
+;; This behavior is different from Flyspell, which only checks words
+;; as the cursor moves over them.  Moreover, unlike Flyspell,
+;; jit-spell communicates with the spell-checking subprocess entirely
+;; asynchronously, which can lead to a noticeable performance
+;; improvement.
+;;
+;; To set up jit-spell, add your desired variation of the following to
+;; your init file:
+;;
+;;   (add-hook 'text-mode-hook 'jit-spell-mode)
+;;   (add-hook 'prog-mode-hook 'jit-spell-mode)
+;;   (with-eval-after-load 'jit-spell
+;;     (define-key jit-spell-mode-map (kbd "C-;") 'jit-spell-correct-word))
+;;
+;; jit-spell relies on the `ispell' library to pick a spell checking
+;; program and dictionaries.  Try `M-x customize-group ispell' to see
+;; a listing of all possible settings.
 
 ;;; Code: