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

Previous Next

Full log

Message #17 received at 79417 <at> debbugs.gnu.org (full text, mbox):

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

> From: Lockywolf <for_emacs_1 <at> lockywolf.net>
> Cc: Lockywolf <for_emacs_1 <at> lockywolf.net>,  79417 <at> debbugs.gnu.org
> Date: Thu, 11 Sep 2025 09:52:03 +0800
> 
> > 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.

If the problem is the messages emitted by ispell-kill-ispell, we could
make it do its job silently when invoked non-interactively.  Would
that solve the problem, and allow us to leave the description of
ispell-kill-ispell in the manual alone?  (We cannot easily remove or
rename what has been an interactive command for so long, but if the
problem is the messages, I don't think removal or renaming is
necessary.)

We could also make ispell-change-dictionary be silent when invoked
non-interactively, although in this case I'd think the message is
useful (so maybe we should have a user option to disable it, for those
who are annoyed).

IOW, this doesn't sound like a documentation problem.

> > 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.

If that is the problem, let's change ispell-change-dictionary not to
suggest dictionaries that aren't installed, or show something like
"(not installed)" after dictionaries that are not installed.  This is
not a documentation problem, either.

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

If our commands cause confusion, we should fix those commands, not
explain their confusing operation.

> >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.

With any backend but Ispell, ispell-dictionary-base-alist is filled by
querying the speller.  This is exactly what we should do, and it
doesn't entail stating the results in the manual.  The speller will
always correctly tell Emacs what are the dictionaries, so asking it
doesn't add any maintenance burden for us.  Having the directories in
the manual _is_ a maintenance burden, and I'd like to avoid it.

If we can do something similar with the recent versions of Ispell,
let's do it (in the code).  In any case, concluding from this that we
need to describe in the manual the directories where dictionaries are
installed is IMO wrong.

> 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.

Users should not need to specify the directories where dictionaries
are installed, they should only specify the name of the dictionary to
use.  The code in ispell.el should be able to find the directory.
AFAIK, with all the backends except Ispell, it already does so; if
there are problems with that, let's fix the code to eliminate those
problems.

> > 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.

Maybe we should just say that the personal dictionary adds the user's
personal words to the standard dictionary.  Would that be sufficient?
We could say that in the doc string of ispell-personal-dictionary.

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

This is an implementation detail, not really relevant to users.  We
don't (and shouldn't) explain how the standard dictionary is
implemented, so neither should we explain how personal dictionaries
are implemented.

> 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).

The default is spell-checker dependent, AFAIK.  Hunspell, for example,
creates a personal dictionary for each language.  If necessary for
people who customize this option, we can recommend in the doc string
to use separate values for different languages (although this is not
convenient if one changes languages frequently, and thus best left to
the backend).  In any case, it should be enough to document this in
the doc string.

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

We could add that, but the description should be much shorter.  All
that's needed is a mention of the local variable and its usage by
ispell.e.

> > 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.

Again, a single sentence should be enough.

> 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.

It doesn't make much sense to do this, but again, the place to
document what this special case does is in the doc string, not in the
manual.  FWIW, I spell-check in several languages, but never invoke
ispell-change-dictionary with the argument of nil.

> > 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.

I see no reason to have this in the manual.  Not everything that has
relevance to spell-checking must be in the manual: we have other
documentation facilities in Emacs that can and should be used by
someone who studies the spell-checking capabilities.

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

They can be found by apropos commands and customize-group.  We do
this with most (all?) of the other faces.

> > 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.

Why is that confusing?  If their doc strings do a poor job, let's
improve those doc strings.

> 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.

Let's first see how the related doc strings can be improved, and take
it from there.  I'm not yet convinced we need to dedicate so much text
to word completion.  The completion command(s) (which you didn't name
in the above, btw) should tell in their doc strings which dictionaries
and word lists they use, and in what order.  If they don't, let's
first improve that, instead of putting that burden on the manual.

> > 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).

I suggest first to discuss an agree on what should and shouldn't be in
the manual, and what should be fixed in other places (code and doc
strings).  Only after we have an agreement, it would make sense to
post a patch according to the agreements.

Thanks.

Previous Next

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