GNU bug report logs - #79417
31.0.50; Improve ispell.el documentation

Previous Next

Full log

View this message in rfc822 format

From: Lockywolf <for_emacs_1 <at> lockywolf.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 79417 <at> debbugs.gnu.org, Lockywolf <for_emacs_1 <at> lockywolf.net>
Subject: bug#79417: 31.0.50; Improve ispell.el documentation
Date: Thu, 11 Sep 2025 09:52:03 +0800

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Thanks, but this is too massive an addition for it to be accepted
> as-is.  The "Spelling" node is already 200+ lines long, and your
> changes add 250 lines more.

Let us adjust it to make it acceptable then!

Personally I embarked on the job of implementing ispell.el tests with
the goal of writing good documentation, because I found the existing one
insufficient.  For years I failed to make ispell.el do what I expected
a spell-checker module to do.

As we can see, melpa has several packages essentially duplicating
ispell.el's (+flyspell) functionality, such as "jinx", or "spell-fu", or
"flycheck-ispell", largely because people, seemingly, failed to
understand how to use ispell.el.

>This is too much for these features,
> which are relatively minor, as Emacs features go.

While the feature itself is not large, it adds a lot of convenience if
implemented properly and a lot of frustration if it does not do what is
natural and expected.  I also think that alleged simplicity of the
feature is a mis-perception, because human languages vastly exceed
formal ones in complexity.  Moreover, Emacs is not just used by people
editing programs, it is also widely used by documentation writers and
publishers, for whom a customizable and flexible spell-checker is one of
the first things they are looking for in a text editor.

> Would you agree to make the patch smaller, only mention important
> features and issues, and describe those as succinctly as possible,
> leaving the rest to the doc strings of the relevant commands and
> variables?

I am quite happy to make the patch smaller, as long as it remains being
easily readable by people opening it while using Emacs for the first
time.  A spell-checker is such a commonplace feature that users are
often asking for it on the very first day.

> For example, why do we need to expand the documentation of
> ispell-kill-ispell beyond what it already says?

Firstly, I don think that there should be a need for a public
ispell-kill-ispell command, so I would be happy to delete this part
altogether. It should be called ispell--kill-ispell, and only be used
internally. But, unfortunately, the user, at the moment, needs to be
aware of it, because in a very common scenario the notification area is
full with messages "Ispell process killed" and "Starting new Ispell
process with ... dictionary". The scenario is the following: the user
has two buffers open, one editing text in language A, another editing
text in language B, and both have flyspell enabled.  This is not just
confusing, it also noticeably slows down buffer switching.  This is
probably not possible to avoid, because otherwise Emacs would have to
keep a running spell-checker process per buffer, which is too much, or
keep a pool of processes for the most recently used buffers, which is
complicated, but in any case, this is not the only use-case for making
the user aware of the fact that "some kind of background process is
running and you might have to kill it manually if something goes wrong".

Of course, it would have been much better if this function could be
entirely removed from the public interface and the two start/kill
messages be hidden from *Messages* unless some kind of a debug switch is
enabled, but doing that is hard, and having one paragraph in the manual
clariflying the issue seems like a small price to pay.

> And why do we need to
> describe how and in which directories to install dictionaries --
> people should either a distro or, if they know what they are doing,
> install the dictionaries themselves using the documentation provided
> with the speller; 

Because dictionaries are given to the user as completions in the
M-x change-ispell-dictionary command, which takes them from the
ispell-dictionary-base-alist variable, which contains dictionaries which
are not installed. This leads to a very confusing behaviour: the user is
suggested to use, say, a "british" dictionary, whereas, in fact such
a dicionary does not exist, and ispell.el generates errors. The
situation becomes even more confusing, because other engines might
actually have the "british" dictionary, so setting "british" with
International Ispell works (because it is in the
ispell-dictionary-base-alist) while using it fails, but with aspell
setting the "british" dictionary fails (because there is no such
dictionary in "aspell dicts") while actually using it (setf
ispell-dictionary "british" without ispell-change-dictionary) works,
because aspell is smart enough choose an english dictionary when called
like "aspell -d british -a".

Dictionary choice is a huge source of confusion, that is why I spend so
much text explaining it.

>we don't want to track changes in those
> installations and update our manual each time they change.

We are already doing that with the variable
ispell-dictionary-base-alist, and the other code to get dictionary lists
from the backends.  And, of course, it is de-synchronised with the
upsteam of the spell-checker programs.  In my experience, explaining it
in the manual with a necessary warning "things may change, examine the
spell-checker documentation" is better than trying to be overly too
smart in the code. After all, if the user just gives us the path to the
correct dictionary, and we have to avoid extracting that info from the
backends, it reduces the amount of heuristics in our code and makes
things simpler. The user is doing it just once, and we have to ensure
and test the work of ispell.el in various environments and different
circumstances.

> Or why
> expand the description of local and personal dictionaries so much --
> does the existing text lack some important information?

Yes. When I was reading it the first time, I thought that
"ispell-dictionary" is the dictionary shipped by the OS vendor, and the
"ispell-personal-dictionary" is the dictionary I have to purchase
elsewhere. For example, ispell-dictionary would be the systemwide
English, and ispell-personal-dictionary would be the dictionary for
Russian I could buy from, say, Abbyy or PROMT.

In fact, ispell-personal-dictionary is not even a dictionary, it is a
wordlist.

It is also not immediately obvious whether it is better to have a
personal dictionary per language (or per the spell-checking program), or
the same personal dictionary for all dictionaries (or spell-checking
programs).

Moreover, the information about "Local Words" as a great alternative to
a personal dictionary is entirely missing from the manual.

> Same question
> about selecting dictionaries for non-default languages.

This is very important. Firstly, the information about the "Local
IspellDict:" keyword is entirely missing from the present manual, even
though it is a very useful tool.

There is a huge confusion with the local dictionary variable.

When both ispell-dictionary and ispell-local-dictionary are nil, ispell
would use the so-called "default" dictionary, that is call the
spell-checker program without the "-d" switch, which is fine in many
cases.

Now assume your ispell-dictionary is fr_FR, and your
ispell-local-dictionary is ru_RU, and you call M-x
ispell-change-dictionary RET nil RET.

You would expect that ispell be called with a "default" dictionary,
without -d switch, but, in fact, the opposite happens, ispell is called
with -d fr_FR.

This issue would not have appeared if ispell-dictionary would just
become buffer-local when set, but this is not the case.

The original design of ispell.el expects this issue to be solved by the
"Local IspellDict: " keyword most of the time, but the information about
it is missing from the manual.

> Or why
> describe the Ispell faces in the manual?

Well, I added it because flyspell-mode changes the ispell.el highlight
face from default "isearch" to "flyspell-error". This is
hugely confusing, and I wanted to explain to the readers why this
happens. And documenting this behaviour for flyspell-mode, I found
myself referring to ispell-highlight-face, therefore needing to document
it as well.

If this behaviour is removed, ispell-highlight-face and flyspell-error
become completely disjoint, this elaboration is unnecessary and can be
removed.

> Or the complete new section
> about word-completion using ispell -- is that really so important to
> warrant so much text?

Yes, it is very important.

At the moment, ispell.el has five dictionary defcustoms:
ispell-dictionary, ispell-local-dictionary, ispell-personal-dictionary,
ispell-complete-word-dict, and ispell-alternate-dictionary, and asome of
them can become buffer-local.

This is VERY confusing for a user, and deserves a thorough explanation.

Completion functionality, while itself being very simple, appears in a
lot of places: in the ispell menu, in CAPF functions, in
hippie-expansion, and various third-party packages, such as
company-mode, various completion frameworks, which are too numerous to
enumerate.

So, suppose, in the simplest default case, I am editing a file written
in French, and invoke some completion command: my word is completed in
Spanish. Bah! I made a mistake, my ispell-complete-word-dict is set to a
Spanish wordlist. I run (setq-local ispell-complete-word-dict nil), and
retry completion. Ah, what is going on, my word is completed in English,
because ispell-alternate-dictionary is pointing to the Webster
/usr/share/dict/words, which I didn't even know existed.

It is better to be safe than sorry and to tell the user precisely what
is going on.

> And I'm not sure I understand the need for so much reshuffling of the
> existing text.  Perhaps if we don't extend existing descriptions so
> much, the need to move the text around so much will also disappear?

The current narrative of the manual starts from a seldom-expected
nowadays feature of querying the backend to correct a word. This is not
what most people expect from a spell-checking tool in 2025. First and
foremost people expect to have their typos highlighted. Most people
never even use the corrective feature, preferring to re-write the word
themselves instead.

However, using (asynchronous) flyspell-mode in Emacs is impossible
without understanding the logic of synchronous spell-checking of
ispell.el.

Therefore, I tried to re-structure the narrative of the section in a
layered way: more advanced features, building on top of simpler
features, come later.

Hence, the structure is the following:

1. Set up the engine. This is impossible to avoid, for any of the
use-cases covered by the section. This section is short.
2. Set up the dictionaries. This is extremely confusing, and without
properly set up dictionaries nothing else works, so it is better to give
this subsubsection to the user first, while they is not yet tired and
capable of reading attentively.
2a. In fact, the user may already stop here, if they are using some
other front-end, not flyspell-mode or ispell.el's interactive features.
3. Proofreading section describes the actual paradigm of working with
UNIX spellcheckers as backends. Of course it requires the engine and the
dictionary to be configured correctly, but does not require
flyspell-mode, hence comes earlier. It is also quite in handy to the
users of flyspell, because, even though flyspell-mode has its own
correction features, those open a GUI menu, which are not that
convenient to use, so I suspect that most people would still use M-$ to
open the ispell.el's corrections buffer, so it is better to introduce it
earlier.
4. The Completion section describes a part of ispell.el, but is not as
important as the Proofreading part, and hence comes later as it is a
dedicated subsubsection, it can be skipped, and the user can go to the
flyspell-mode directly.
5. Flyspell-mode is the most high-level layer, with asynchronous process
running, and GUI menus involved, hence comes last.

Now that I am writing it, I am realising that the Prooofreading
functionality calls the Completion functionality (the "l" key in the
interactive buffer), but not the other way round. It might be better to
make the Completion subsubsection to come earlier.

> I also don't like using @subsections that have no nodes: they make the
> manual harder to navigate.  If we must introduce new subsections,
> let's make each one of them a separate node.

No problem. New patch attached (nodes added, but faces not yet removed).

[signature.asc (application/pgp-signature, inline)]

[0001-Improve-ispell-mode-and-flyspell-mode-documentation.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

> May I suggest that, instead of posting a jumbo patch, you post a list
> of problems you see with important details and aspects of
> spell-checking, as they are currently documented (or not documented)
> in the manual, and we could then discuss these one by one and decide
> whether and how each one of them should be fixed?  If nothing else, it
> will allow us to discuss the problems first, rather than start from a
> full-blown solution.

I never thought about this patch as "jumbo". As you said, it's just 250
lines, less than a single function of ispell.el (ispell-command-loop is
279 lines, ispell-region is 153 lines), and is less than 5% of
ispell.el+flyspell.el, which are 4345+2411=6756 lines long (5096 without
comments and empty lines).

After all, the whole documentation to Elisp ratio for Emacs is

find lisp -iname '*.el' -exec cat {} + | \
  grep --binary-files=text -v '^;' | \
  grep --binary-files=text -v '^$' | wc -l
1671287

find doc -iname '*.texi' -exec cat {} + | \
  grep --binary-files=text -v '^%' |  \
  grep --binary-files=text -v '^$' | wc -l
354929

echo '354929/1671287' | bc -l
.21

So, roughly speaking ispell.el's documentation is 4 times terser than
Emacs' on average.

Even if you add all of the C code (which is much sparser documented)
without removing comments:

find src lisp \( -iname '*.el' -or -iname '*.c' \) -exec cat {} + | \
  grep --binary-files=text -v '^;' | \
  grep --binary-files=text -v '^$' | wc -l
2110316

echo '354929/2110316' | bc -l
.16

This is still three times more elaborate and detailed than the spelling
documentation in fixit.texi


-- 
Your sincerely,
Vladimir Nikishkin (MiEr, lockywolf)
(Laptop)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.