From 9b49a8ed4a39c5d24336bda2ee0ee070ebe08221 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 12 Jul 2018 18:59:18 +0300
Subject: [PATCH] Improve documentation of Flyspell

For the background, see
http://lists.gnu.org/archive/html/help-gnu-emacs/2018-07/msg00099.html.

* doc/emacs/fixit.texi (Spelling): Add a couple of caveats.
* lisp/textmodes/flyspell.el: Update commentary.
---
 doc/emacs/fixit.texi       | 14 +++++++++-----
 lisp/textmodes/flyspell.el |  4 ++--
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index fe2da7ae4f1..7bbaa0016ba 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -408,11 +408,15 @@ dictionary.
 @cindex mode, Flyspell
 @findex flyspell-mode
   Flyspell mode is a minor mode that performs automatic spell-checking
-as you type.  When it finds a word that it does not recognize, it
-highlights that word.  Type @kbd{M-x flyspell-mode} to toggle Flyspell
-mode in the current buffer.  To enable Flyspell mode in all text mode
-buffers, add @code{flyspell-mode} to @code{text-mode-hook}.
-@xref{Hooks}.
+of the text you type as you type it.  When it finds a word that it
+does not recognize, it highlights that word.  Type @kbd{M-x
+flyspell-mode} to toggle Flyspell mode in the current buffer.  To
+enable Flyspell mode in all text mode buffers, add
+@code{flyspell-mode} to @code{text-mode-hook}.  @xref{Hooks}.  Note
+that, as Flyspell mode needs to check each word across which you move,
+it will slow down cursor motion and scrolling commands.  It also
+doesn't automatically check the text you didn't type or move across;
+use @code{flyspell-region} or @code{flyspell-buffer} for that.
 
 @findex flyspell-correct-word
 @findex flyspell-auto-correct-word
diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el
index 24e424c663c..3bad41ab7a4 100644
--- a/lisp/textmodes/flyspell.el
+++ b/lisp/textmodes/flyspell.el
@@ -31,10 +31,10 @@
 ;;
 ;; To enable Flyspell in text representing computer programs, type
 ;; M-x flyspell-prog-mode.
-;; In that mode only text inside comments is checked.
+;; In that mode only text inside comments and strings is checked.
 ;;
 ;; Some user variables control the behavior of flyspell.  They are
-;; those defined under the `User variables' comment.
+;; those defined under the `User configuration' comment.
 
 ;;; Code:
 
-- 
2.39.2