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

Previous Next

To reply to this bug, email your comments to 79417 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

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

From: Lockywolf <for_emacs_1 <at> lockywolf.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 31.0.50; Improve ispell.el documentation
Date: Wed, 10 Sep 2025 10:12:57 +0800

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

Dear Emacs developers,

The following patch contains what I consider to be an improvement to the
Emacs Manual with respect to the ~ispell.el~ spell-checking component.

The patch is attached.

[0001-Add-tests-to-inspell.el-interactive-functions.patch (text/x-patch, attachment)]

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

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

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

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

From: Lockywolf <for_emacs_1 <at> lockywolf.net>
To: 79417 <at> debbugs.gnu.org.
Cc: Lockywolf <for_emacs_1 <at> lockywolf.net>
Subject: Re: 31.0.50; Improve ispell.el documentation
Date: Wed, 10 Sep 2025 10:43:00 +0800

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

Apologies, the previous patch got mangled, please see the patch attached
to this message.

[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)]

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

Message #11 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: Wed, 10 Sep 2025 16:25:58 +0300

> Cc: Lockywolf <for_emacs_1 <at> lockywolf.net>
> From: Lockywolf <for_emacs_1 <at> lockywolf.net>
> Date: Wed, 10 Sep 2025 10:43:00 +0800
> 
> Apologies, the previous patch got mangled, please see the patch attached
> to this message.

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.  This is too much for these features,
which are relatively minor, as Emacs features go.

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?  For example, why do we need to expand the documentation of
ispell-kill-ispell beyond what it already says?  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; we don't want to track changes in those
installations and update our manual each time they change.  Or why
expand the description of local and personal dictionaries so much --
does the existing text lack some important information?  Same question
about selecting dictionaries for non-default languages.  Or why
describe the Ispell faces in the manual?  Or the complete new section
about word-completion using ispell -- is that really so important to
warrant so much text?

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?

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.

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.

Thanks.

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

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: Re: 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)

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.