Flyspell difficult to configure, documentation not honest

["R. Diez" <rdiezmail-emacs@yahoo.de>]

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