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 379279575caf05ee851dfca4a7024b4685fa5468..c20ef6830adb233a125c16144d1a14dddfcb9361 100644 (file)
--- 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 a89d39e784de3ff5d7e8a041c7d7f7b426ef8a22..093b5f92e58e1429c2172997dba0934b3c3721cf 100644 (file)
--- 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 283813ff89ed98cf206758eccf50f0275fd2bca0..702c143828330369b9902f5009d99c3846b028e2 100644 (file)
--- 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