master b41942f: Improve the documentation of marker handling when reverting

[Lars Ingebrigtsen]

branch: master
commit b41942fac93b3a817a7b7848c2bd05ee15a4f6f2
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    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).
---
 doc/lispref/backups.texi | 6 +++++-
 lisp/files.el            | 3 +++
 src/fileio.c             | 7 ++++---
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index 3792795..c20ef68 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 a89d39e..093b5f9 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 283813f..702c143 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