From beb54dc1b2b00cb4541b82acf6ead8a8075c3011 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 21 Aug 2021 10:58:24 +0300
Subject: [PATCH] Improve documentation of 'file-preserve-symlinks-on-save'

* lisp/files.el (file-precious-flag): Mention
'file-preserve-symlinks-on-save' in the doc string.

* doc/lispref/files.texi (Saving Buffers): Move the description of
'file-preserve-symlinks-on-save' from here...
* doc/emacs/files.texi (Customize Save): ...to here.  Improve
wording.

* etc/NEWS: Fix wording of 'file-preserve-symlinks-on-save' entry.
---
 doc/emacs/files.texi   | 11 +++++++++++
 doc/lispref/files.texi |  7 -------
 etc/NEWS               |  4 ++--
 lisp/files.el          |  2 +-
 4 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 207c951a875..9aae0e9a0b3 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -742,6 +742,17 @@ always supposed to end in newlines.  Such major modes set the variable
 setting the latter variable, you can control how these modes handle
 final newlines.
 
+@vindex file-preserve-symlinks-on-save
+If this option is non-@code{nil} and you're visiting a file via a
+symbolic link, Emacs will break the symbolic link upon saving the
+buffer, and will write the buffer to a file with the same name as the
+symbolic link, if the value of @code{file-precious-flag} is
+non-@code{nil} (@pxref{Saving Buffers, file-precious-flag,, elisp, The
+Emacs Lisp Reference Manual}).  If you want Emacs to save the buffer
+to the file the symbolic link points to (thereby preserving the link)
+in these cases, customize the variable
+@code{file-preserve-symlinks-on-save} to @code{t}.
+
 @vindex write-region-inhibit-fsync
   Normally, when a program writes a file, the operating system briefly
 caches the file's data in main memory before committing the data to
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 12c06111374..266501d46d0 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -503,13 +503,6 @@ all hard links between the file you save and other file names.
 
 Some modes give this variable a non-@code{nil} buffer-local value
 in particular buffers.
-
-@vindex file-preserve-symlinks-on-save
-If this option is non-@code{nil} and you're visiting files via a
-symbolic link, Emacs break the symbolic link and write the buffer to a
-file with the same name as the symbolic link.  To instead write to the
-file the symbolic link points to (and thereby preserving the link),
-set @code{file-preserve-symlinks-on-save} to @code{t}.
 @end defopt
 
 @defopt require-final-newline
diff --git a/etc/NEWS b/etc/NEWS
index cdc70d6fef0..ec7e54e2dde 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2462,8 +2462,8 @@ images are marked.
 
 +++
 *** New user option 'file-preserve-symlinks-on-save'.
-This controls what Emacs does when saving buffers visited via a
-symbolic link, and 'file-precious-flag' is non-nil.
+This controls what Emacs does when saving buffers that visit files via
+symbolic links, and 'file-precious-flag' is non-nil.
 
 +++
 *** New user option 'copy-directory-create-symlink'.
diff --git a/lisp/files.el b/lisp/files.el
index 6a617feca49..f0baa4fac6d 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -257,7 +257,7 @@ This feature is advisory: for example, if the directory in which the
 file is being saved is not writable, Emacs may ignore a non-nil value
 of `file-precious-flag' and write directly into the file.
 
-See also: `break-hardlink-on-save'."
+See also: `break-hardlink-on-save' and `file-preserve-symlinks-on-save'."
   :type 'boolean
   :group 'backup)
 
-- 
2.39.5