[elpa] externals/jinx 6ea7a861c4 6/8: editorial changes to readme (#26)

[ELPA Syncer]

branch: externals/jinx
commit 6ea7a861c44bdc4dc418abcefffd146883f58b63
Author: Lambda Coder <sjLambda@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    editorial changes to readme  (#26)
    
    * Update README.org
    
    * Update README.org
    
    * Cleaned out the language
    
    fixed obvious gaps, added sample config
---
 README.org | 112 ++++++++++++++++++++++++++++---------------------------------
 1 file changed, 51 insertions(+), 61 deletions(-)

diff --git a/README.org b/README.org
index 792a561e16..7baa18a73d 100644
--- a/README.org
+++ b/README.org
@@ -12,39 +12,37 @@
 #+html: <a href="https://melpa.org/#/jinx";><img alt="MELPA" 
src="https://melpa.org/packages/jinx-badge.svg"/></a>
 #+html: <a href="https://stable.melpa.org/#/jinx";><img alt="MELPA Stable" 
src="https://stable.melpa.org/packages/jinx-badge.svg"/></a>
 
-Jinx provides just-in-time spell-checking via 
[[https://abiword.github.io/enchant/][libenchant]]. The package aims to
-achieve high performance and low resource usage, without impacting your editing
-experience. Overall Jinx should just work out of the box without much
-intervention.
-
-Jinx highlights misspellings lazily only in the visible part of the text. The
-window boundaries and text folding are taken into account. Jinx binds directly
-to the native libenchant API, such that process communication with a backend
-Aspell process can be avoided. Libenchant is widely used as spell-checking API
-by text editors and supports [[https://nuspell.github.io/][Nuspell]], 
[[http://hunspell.github.io/][Hunspell]], [[http://aspell.net/][Aspell]] and a 
few lesser known
-backends. Jinx automatically compiles =jinx-mod.c= and loads the dynamic 
module at
-startup.
-
-Jinx supports multiple languages in a buffer at the same time via the
-=jinx-languages= customization variable. It offers flexible settings to ignore
-misspellings via faces (=jinx-exclude-faces= and =jinx-include-faces=), regular
-expressions (=jinx-exclude-regexps=) and programmable predicates. Jinx comes
-preconfigured for the most important major modes.
+Jinx is a just-in-time spell-checker for Emacs. Jinx highlights misspelled 
words in the text of the visible portion of the buffer. Each misspelling can 
then be corrected from a list of dictionary words presented as the usual 
completion candidates in a list.
+
+Installing Jinx is straight-forward and configuring takes not much 
intervention. Jinx can safely co-exist with Emacs's built-in spell-checker.
+
+Jinx's high performance and low resource usage comes from directly calling the 
widely-used API of the Enchant library (see 
[[https://abiword.github.io/enchant/][libenchant]]).  Jinx package 
automatically compiles =jinx-mod.c= and loads the dynamic module at startup. 
+
+Jinx highlights misspellings lazily, recognizes window boundaries and text 
folding, if any. By binding directly to the native libenchant API, Jinx avoids 
the slower backend process communication with Aspell. Thanks to libenchant API, 
this method is widely used by text editors and supports 
[[https://nuspell.github.io/][Nuspell]], 
[[http://hunspell.github.io/][Hunspell]], [[http://aspell.net/][Aspell]] and a 
few lesser known
+backends.  
+
+Jinx supports spell-checking multiple languages in the same buffer. See the 
=jinx-languages= variable to customize for multiple languages.
+
+Jinx can flexibly ignore misspellings via faces (=jinx-exclude-faces= and 
=jinx-include-faces=), regular
+expressions (=jinx-exclude-regexps=), and programmable predicates. Jinx comes 
preconfigured for the most important Emacs major modes.
 
 #+html: <img 
src="https://github.com/minad/jinx/blob/screenshots/screenshot.png?raw=true";>
 
-* Installation
+* Installing Jinx
+
+Jinx can be installed from GNU ELPA and MELPA directly or with 
=package-install=. 
+
+Jinx requires =libenchant=. Enchant library is a required dependency for Jinx 
to compile its module at install time. If =pkg-config= is available when 
installing Jinx, Jinx will use =pkg-config= to locate =libenchant=. 
+
+On Debian or Ubuntu, install packages =libenchant-2-2=, =libenchant-2-dev= and 
=pkg-config=.
 
-The package is available on GNU ELPA and MELPA and can be installed with
-=package-install=. Libenchant must be installed on your system for 
compilation. If
-=pkg-config= is available it will be used to locate libenchant. On Debian or
-Ubuntu, install the packages =libenchant-2-2=, =libenchant-2-dev= and 
=pkg-config=.
 On Fedora or RHEL, install the package =enchant2-devel=.
 
-* Usage
+On Mac or Darwin systems, install =enchant2= and =pkgconfig=.
 
-Jinx offers two modes =global-jinx-mode= and =jinx-mode=. You can either enable
-=global-jinx-mode= or add =jinx-mode= to the hooks of the modes.
+* Using Jinx
+
+Jinx has two modes: the command, =global-jinx-mode= activates globally; and 
the command, =jinx-mode=, for activiating for specific modes.  
 
 #+begin_src emacs-lisp
   (add-hook 'emacs-startup-hook #'global-jinx-mode)
@@ -53,48 +51,40 @@ Jinx offers two modes =global-jinx-mode= and =jinx-mode=. 
You can either enable
     (add-hook hook #'jinx-mode))
 #+end_src
 
-Furthermore Jinx brings two auto-loaded commands =jinx-correct= and
-=jinx-languages=. In order to correct misspellings bind =jinx-correct= to a
-convenient key in your configuration. Jinx is independent of the Ispell 
package,
-so you can reuse the binding =M-$= which is bound to =ispell-word= by default. 
When
-pressing =M-$=, Jinx offers correction suggestions for the misspelling next to
-point. If the prefix key =C-u= is pressed, the entire buffer is spell-checked.
+A sample configuration with the popular =use-package= macro is shown here:
+
+#+begin_src emacs-lisp
+(use-package jinx
+  :commands (jinx-correct jinx-languages)
+  :hook (emacs-startup . global-jinx-mode)
+  :bind ([remap ispell-word] . jinx-correct))
+#+end_src
+
+Jinx autoloads the commands =jinx-correct= and =jinx-languages=. Invoking 
=jinx-correct= corrects the misspellings. Binding =jinx-correct= to =M-$= chord 
takes over that chord from Emacs's default assignment to =ispell word=. Since 
Jinx is independent of the Emacs's Ispell package, =M-$= can be re-used. The 
=use-package= definition above shows that. The same reassignment using regular 
keymap is shown below:
 
 #+begin_src emacs-lisp
   (keymap-global-set "<remap> <ispell-word>" #'jinx-correct)
 #+end_src
 
+=M-$= triggers correction for the misspelled word next to point. 
+
+=C-u M-$= triggers correction for the entire buffer. 
+
 * Enchant backends and personal dictionaries
 
-Enchant uses different backends depending on the language. The ordering of the
-backends is configured by the file =~/.config/enchant/enchant.ordering=. For 
most
-languages Hunspell is used by default. Depending on the backend the personal
-dictionary will be taken from different locations, e.g., =~/.aspell.LANG.pws= 
or
-=~/.config/enchant/=. It is possible to symlink different personal dictionaries
-such that they are shared by different spell checkers. See the 
[[https://abiword.github.io/enchant/src/enchant.html][Enchant manual]]
-for more details.
-
-* Alternatives
-
-- [[https://github.com/astoff/jit-spell][jit-spell]]: Jinx offers a similar UI 
as Augusto Stoffel's jit-spell package and
-  borrows ideas from it. Jit-spell uses Ispell process communication instead of
-  a native API. It does not restrict the highlighting to the visible text. In 
my
-  setup I observed an increase in load and latency as a consequence, in
-  particular in combination with stealth locking and commands which trigger
-  fontification eagerly like =consult-line= from my 
[[https://github.com/minad/consult][Consult]] package.
-
-- [[https://codeberg.org/ideasman42/emacs-spell-fu][spell-fu]]: The technique 
to spell-check only the visible text was inspired by
-  Campbell Barton's spell-fu package. Spell-fu maintains the dictionary itself
-  via a hash table, which results in high memory usage for languages with
-  compound words or inflected word forms. In Jinx we avoid the complexity of
-  managing the dictionary and access the advanced spell-checker algorithms
-  directly via libenchant (affixation, compound words, etc.).
-
-- flyspell: Flyspell is a builtin package which highlight misspellings while
-  typing and when you move the cursor to a word. Jinx uses a different mode of
-  operation, where the entire visible text of the buffer is checked always.
+Enchant uses different backends for different languages (to be spell-checked). 
The backends are ordered as specified in the configuration file 
=~/.config/enchant/enchant.ordering=. For most languages, Enchant uses Hunspell 
by default. 
+
+Depending on the backend the personal dictionary will be taken from different 
locations, e.g., =~/.aspell.LANG.pws= or =~/.config/enchant/=. It is possible 
to symlink different personal dictionaries
+such that they are shared by different spell checkers. See the 
[[https://abiword.github.io/enchant/src/enchant.html][Enchant manual]] for 
details.
+
+* Alternate spell check programs
+
+- [[https://github.com/astoff/jit-spell][jit-spell]]: Jinx UI borrows ideas 
from Augusto Stoffel's jit-spell even if Jit-spell uses Ispell process 
communication instead Jinx's calling native API. Since jit-spell highlights 
misspellings in the entire buffer and does not confine to just the visible 
text, jit-spell has load and latency consequences especially in stealth locking 
and eager fontification. This overhead is similar to =consult-line= from my 
[[https://github.com/minad/consult][Co [...]
+
+- [[https://codeberg.org/ideasman42/emacs-spell-fu][spell-fu]]: The idea to 
highlight misspellings just in the visible text portion of the buffer came from 
Campbell Barton's spell-fu package. Spell-fu however incurrs high memory 
overhead on account of its dictionary in a hash table. For languages with 
compound words and inflected word forms, this memory overhead magnifies. By 
accessing the enchant API directly, Jinx avoids this overhead. Jinx also 
benefits from enchant's advanced spell-c [...]
 
+- flyspell: Flyspell is Emacs's built-in package. Flyspelll highlights 
misspellings realt-time, while typing. Each word under the cursor is 
spell-checked and underlined if mistyped. Jinx, on the other hand, is a bit 
more efficient because it checks for misspellings in the entire visible text of 
the buffer at once.
+  
 * Contributions
 
-Since this package is part of [[https://elpa.gnu.org/packages/jinx.html][GNU 
ELPA]] contributions require a copyright
-assignment to the FSF.
+Since this package is part of [[https://elpa.gnu.org/packages/jinx.html][GNU 
ELPA]] contributions require a copyright assignment to the FSF.