From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Sat, 12 Dec 2020 11:20:38 +0000 (+0100)
Subject: Improve the documentation of marker handling when reverting
X-Git-Tag: emacs-28.0.90~4766
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=b41942fac93b3a817a7b7848c2bd05ee15a4f6f2;p=emacs.git

Improve the documentation of marker handling when reverting

* doc/lispref/backups.texi (Reverting): Mention markers from
non-file sources (bug#30028).

* lisp/files.el (revert-buffer): Mention what happens with markers
(bug#30028).

* src/fileio.c (Finsert_file_contents): Say a bit more about what
markers are restored (bug#30028).
---

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 379279575ca..c20ef6830ad 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -706,7 +706,11 @@ contents and the file contents are identical before the revert
 operation, reverting preserves all the markers.  If they are not
 identical, reverting does change the buffer; in that case, it preserves
 the markers in the unchanged text (if any) at the beginning and end of
-the buffer.  Preserving any additional markers would be problematical.
+the buffer.  Preserving any additional markers would be problematic.
+
+When reverting from non-file sources, markers are usually not
+preserved, but this is up to the specific @code{revert-buffer-function}
+implementation.
 @end deffn
 
 @defvar revert-buffer-in-progress-p
diff --git a/lisp/files.el b/lisp/files.el
index a89d39e784d..093b5f92e58 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6119,6 +6119,9 @@ This undoes all changes since the file was visited or saved.
 With a prefix argument, offer to revert from latest auto-save file, if
 that is more recent than the visited file.
 
+Reverting a buffer will try to preserve markers in the buffer;
+see the Info node `(elisp)Reverting' for details.
+
 This command also implements an interface for special buffers
 that contain text that doesn't come from a file, but reflects
 some other data instead (e.g. Dired buffers, `buffer-list'
diff --git a/src/fileio.c b/src/fileio.c
index 283813ff89e..702c1438283 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -3757,9 +3757,10 @@ characters in the buffer.  If VISIT is non-nil, BEG and END must be nil.
 If optional fifth argument REPLACE is non-nil, replace the current
 buffer contents (in the accessible portion) with the file contents.
 This is better than simply deleting and inserting the whole thing
-because (1) it preserves some marker positions and (2) it puts less data
-in the undo list.  When REPLACE is non-nil, the second return value is
-the number of characters that replace previous buffer contents.
+because (1) it preserves some marker positions (in unchanged portions
+at the start and end of the buffer) and (2) it puts less data in the
+undo list.  When REPLACE is non-nil, the second return value is the
+number of characters that replace previous buffer contents.
 
 This function does code conversion according to the value of
 `coding-system-for-read' or `file-coding-system-alist', and sets the