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.

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 207c951a875f5341970d37b0b03a89b10fb229ce..9aae0e9a0b3445c338efca06cb27dcdae18ca49b 100644 (file)
--- 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 12c06111374b5ee74537a5ba1a2d07ac92e61cf2..266501d46d0f3c9c6b4203622593609e0841677a 100644 (file)
--- 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 cdc70d6fef0b94c8d4d5e6f21521aa968208a3b1..ec7e54e2ddeb791a1cec00456dd1e7e4272d3aa8 100644 (file)
--- 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 6a617feca49cc625a45f81c980bcbc05c1792bad..f0baa4fac6dd292d65d2bfaf14e89066e552dc5c 100644 (file)
--- 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)