master d8d9504: ; Fix wording of recent changes in documentation

[Eli Zaretskii]

branch: master
commit d8d9504c5a9f1b6d22eae131334b981c65881f0e
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix wording of recent changes in documentation
    
    * lisp/files.el (query-about-changed-file):
    * doc/emacs/files.texi (Visiting):
    * etc/NEWS: Fix the wording of a recent change.  (Bug#10755)
---
 doc/emacs/files.texi | 13 +++++++------
 etc/NEWS             |  7 ++++---
 lisp/files.el        | 11 ++++++-----
 3 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index b57618f..54ffcd3 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -228,12 +228,13 @@ actually contains wildcard characters.  You can disable 
the wildcard
 feature by customizing @code{find-file-wildcards}.
 
 @vindex query-about-changed-file
-  If you're asking to visit a file that's already in a buffer, but the
-file has changed externally, Emacs will ask you whether you want to
-re-load the file or not.  If you set @code{query-about-changed-file}
-to @code{nil}, Emacs won't query you, but instead just display the
-buffer and issue a message telling you how to revert the buffer from
-the file.
+  If you're asking to visit a file that's already visited in a buffer,
+but the file has changed externally, Emacs normally asks you whether
+you want to re-read the file from disk.  But if you set
+@code{query-about-changed-file} to @code{nil}, Emacs won't query you,
+but will instead just display the buffer's contents before the
+changes, and show an echo-area message telling you how to revert the
+buffer from the file.
 
 @kindex C-x C-v
 @findex find-alternate-file
diff --git a/etc/NEWS b/etc/NEWS
index cfa6a4e..e18b3d0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -311,9 +311,10 @@ prompt, and how you can tweak the file size threshold.
 +++
 ** New user option 'query-about-changed-file'.
 If non-nil (the default), users are prompted as before when
-re-visiting a file that has changed externally.  If nil, the user is
-not prompted, but instead the buffer is opened, and the user is given
-an instruction on how to revert the uffer.
+re-visiting a file that has changed externally after it was visited
+the first time.  If nil, the user is not prompted, but instead the
+buffer is opened with its contents before the change, and the user is
+given instructions how to revert the buffer.
 
 +++
 ** Improved support for terminal emulators that encode the Meta flag.
diff --git a/lisp/files.el b/lisp/files.el
index 253a289..862982b 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -2154,12 +2154,13 @@ think it does, because \"free\" is pretty hard to 
define in practice."
   :type '(choice integer (const :tag "Never issue warning" nil)))
 
 (defcustom query-about-changed-file t
-  "If non-nil, query the user when opening a file that has changed.
-This happens if the file is already visited in a buffer, and the
-file has changed, and the user re-visits the file.
+  "If non-nil, query the user when re-visiting a file that has changed.
+This happens if the file is already visited in a buffer, the
+file was changed externally, and the user re-visits the file.
 
-If nil, the user isn't prompted, but instead given a warning
-after switching to the buffer."
+If nil, don't prompt the user, but instead provide instructions for
+reverting, after switching to the buffer with its contents before
+the external changes."
   :group 'files
   :group 'find-file
   :version "28.1"