bug#49661: (patches) Improve docs for revert-buffer and auto-revert-mode

bug#49661: (patches) Improve docs for revert-buffer and auto-revert-mode

[Konstantin Kharlamov]

[-- Attachment #1: Type: text/plain, Size: 1084 bytes --]

Patches attached.

The reasoning behind the changes as follow:

1. `revert-buffer`: its current docs only mention that it tries its best to keep markers, but it does not mention that it may fail to do so, and that there is a slower but better alternative to this function. The lack of it being mentioned resulted in me researching its code down to C, and also another maintainer testing a bug, and yet another contributor writing up a large post about the new alternative revert functions…¹ All of that could've been avoided had `revert-function` referred to the new alternative, so that's what the patch does.
2. `auto-revert-mode`: Even with the change in 1 it's still unclear how to make use of that for `auto-revert-mode`. It does not even mention that the mode may break markers, so a person would have to debug it and find out revert-buffer, which in turn mentions about the problem, but doesn't really mention how to fix the auto-revert-mode specifically. So let's save people time, and just have a paragraph about it as well.

1: https://github.com/magit/magit/issues/4442

[-- Attachment #2: 0001-Mention-that-revert-buffer-isn-t-best-for-markers-pr.patch --]
[-- Type: text/x-patch, Size: 1164 bytes --]

From 2c2236155e54e248b1182efe66dafc6f862ceae4 Mon Sep 17 00:00:00 2001
From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
Date: Tue, 20 Jul 2021 15:52:48 +0300
Subject: [PATCH 1/2] Mention that (revert-buffer) isn't best for markers
 preservation

* lisp/files.el (revert-buffer): mention that there is
  revert-buffer-with-fine-grain that is better suited for markers
preservation
---
 lisp/files.el | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lisp/files.el b/lisp/files.el
index 59077cd266a..c2cec4dc2a2 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -6274,8 +6274,9 @@ revert-buffer
 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.
+Reverting a buffer will try to preserve markers in the buffer,
+but for better results see `revert-buffer-with-fine-grain'. For
+details see the Info node `(elisp)Reverting'.
 
 This command also implements an interface for special buffers
 that contain text that doesn't come from a file, but reflects
-- 
2.32.0


[-- Attachment #3: 0002-Mention-that-auto-revert-mode-may-break-markers.patch --]
[-- Type: text/x-patch, Size: 1131 bytes --]

From c0d5e765708f5ecd0dcc5b97e46dee50429df46b Mon Sep 17 00:00:00 2001
From: Konstantin Kharlamov <Hi-Angel@yandex.ru>
Date: Tue, 20 Jul 2021 16:02:16 +0300
Subject: [PATCH 2/2] Mention that auto-revert-mode may break markers

lisp/autorevert.el (auto-revert-mode): Mention that auto-revert-mode may
break markers
---
 lisp/autorevert.el | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/lisp/autorevert.el b/lisp/autorevert.el
index edd4c7e5e45..0037e1185d1 100644
--- a/lisp/autorevert.el
+++ b/lisp/autorevert.el
@@ -391,6 +391,12 @@ auto-revert-mode
 When a buffer is reverted, a message is generated.  This can be
 suppressed by setting `auto-revert-verbose' to nil.
 
+Reverting may also break markers in the buffer. To avoid that you
+may set `revert-buffer-insert-file-contents-function' to the
+slower function
+`revert-buffer-insert-file-contents-delicately'. See its
+description for details.
+
 Use `global-auto-revert-mode' to automatically revert all buffers.
 Use `auto-revert-tail-mode' if you know that the file will only grow
 without being changed in the part that is already in the buffer."
-- 
2.32.0

bug#49661: (patches) Improve docs for revert-buffer and auto-revert-mode

[Lars Ingebrigtsen]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> Patches attached.

Thanks; applied to Emacs 28 (with some trivial white-space changes -- we
prefer two spaces after "." in doc strings).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no