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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lockywolf <for_emacs_1 <at> lockywolf.net>
Cc: 79417 <at> debbugs.gnu.org
Subject: 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.

Previous Next

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