Re: Flyspell difficult to configure, documentation not honest

[Eli Zaretskii]

> Date: Thu, 12 Jul 2018 14:59:01 +0000 (UTC)
> From: "R. Diez" <rdiezmail-emacs@yahoo.de>
> 
> I have been trying to use Flyspell, and I found it difficult to configure.

I hear you, but FWIW I find Flyspell very easy to use.

> You have to search the Internet in order to find good tips. After some time, 
> I found this page, which summarises Flyspell's shortcomings:
> 
> http://ergoemacs.org/emacs/emacs_spell_checker_problems.html

It is outdated and partially incorrect (e.g., right mouse click does
work on Flyspell).

> If the documentation were honest, it would mention those shortcomings itself, 
> maybe as part of a CAVEATS section. Otherwise, you are lead to believe that 
> Flyspell is fine and dandy, which clearly is not the case. After all, we are 
> all used to 'proper' spell checkers all around us (for example, in 
> LibreOffice).

I added a few sentences to the Emacs manual to that effect.

> I am using Emacs 26.1. The source code comments are outdated. For example:
> 
> 
> ;; Some user variables control the behavior of flyspell.  They are
> ;; those defined under the `User variables' comment.
> 
> However, I found no "user variables" comment anywhere on that file.
> 
> Furthermore, this comment does not mention anything about literal strings 
> being checked too (more on that further below):

I fixed both of those.  However, I must say that

  M-x customize-group RET flyspell RET

would have brought you faster to the stuff you need than reading the
comments.  My suggestion is to use the built-in documentation (the doc
strings, the manual, and the customizable options) first, and only if
they don't provide enough info, to read the code.

> The first big gotcha was trying to set up automatic language detection, which 
> should arguably be part of Flyspell.

This is a general issue in Emacs: we don't yet have any notion of
language of the text.  In a plain-text editor such as Emacs that is
capable of mixing any number of different languages and scripts in the
same buffer, this is not an easy job.  For now, you must change
dictionaries whenever you need to spell-check text in a different
language, unless you are using Hunspell, which can load more than one
dictionary at the same time.

> I have a big text file with all my assorted notes (I haven't learnt Org Mode 
> yet). I cannot spell-check all of it, that would turn up too many spurious 
> errors.

I usually find the Ispell facilities to accept "misspelled" words
either temporarily or permanently, quite adequate.  Type SPC or 'a' to
do any of those, when spell-checking a region or the whole buffer.
(Flyspell is not the right feature for this job; use ispell-region
instead.  Flyspell is mainly meant to check what you type on the fly.)

> I tried flyspell-region, and that is one of the biggest surprises: the spell 
> check is performed just once, and is not updated as I type inside that region.

Like everything else in Flyspell, misspelled words are re-checked when
you move across them or modify them.  That's a feature.  If you don't
like that, I suggest to use ispell-region instead.

> Well, I can manually recheck, however inconvenient. But the biggest surprise 
> is trying to remove the spelling marks at the end.

If the word is still a misspelling, why should the mark be removed?

> I nevertheless tried to push forwards with Flyspell, because alternatives 
> like Wcheck Mode or Speck did not seem quite ready yet. Next step was 
> flyspell-prog-mode . And here I found the next big drawback: it checks 
> literal strings too, even the filenames inside C's #include <blah/blah-h> 
> preprocessor directives, littering too much source code with error marks.

They are strings, aren't they?  How should Flyspell know that some
string is a file name?

> Trying to limit spell checking to just source-code comments is hard. I found 
> this page that explains how to do it:
> 
> http://blog.binchen.org/posts/effective-spell-check-in-emacs.html
> 
> But I haven't quite understood it yet (I am no Lisp expert). How about adding 
> a simple customizable variable to turn literal string checking on and off?

I suggest to submit a feature request for that, using
report-emacs-bug.

> To top it all, there is one little surprise in store: disabling 
> flyspell-persistent-highlight renders flyspell-region useless.

Disabling flyspell-persistent-highlight turns off highlight once point
moves off the misspelled word.  I've now added that to the doc string.

> The whole experience reminds me of the expression "death by a thousand paper 
> cuts".

Sorry to hear that.