Flyspell difficult to configure, documentation not honest

[R. Diez]

Hi there:

I have been trying to use Flyspell, and I found it difficult to configure.

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


Flyspell's documentation is made of a few source-code comments, and this page:

https://www.gnu.org/software/emacs/manual/html_node/emacs/Spelling.html


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


;; To enable Flyspell in text representing computer programs, type
;; M-x flyspell-prog-mode.
;; In that mode only text inside comments is checked.

The first big gotcha was trying to set up automatic language detection, which 
should arguably be part of Flyspell. I would say that a sizeable part of the 
population has to handle languages other than English everyday. Who wants to 
manually switch dictionaries every time? After some struggling, I found and 
configured another package to achieve that.


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 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. 
Well, I can manually recheck, however inconvenient. But the biggest surprise is 
trying to remove the spelling marks at the end. After some searching, I found 
out about flyspell-delete-all-overlays and flyspell-delete-region-overlays, but 
alas, they are not marked as 'interactive'. I wonder how Flyspell thinks users 
should remove those marks (how to end the flyspell-region command).


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.

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?


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

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


Please copy me on all the answers or comments, as I am not subscribed to this 
mailing list.


Thanks in advance,
  rdiez