GNU bug report logs - #49661
(patches) Improve docs for revert-buffer and auto-revert-mode

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 49661 in the body.
You can then email your comments to 49661 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Konstantin Kharlamov <hi-angel <at> yandex.ru>
To: bug-gnu-emacs <at> gnu.org
Subject: (patches) Improve docs for revert-buffer and auto-revert-mode
Date: Tue, 20 Jul 2021 16:21:57 +0300

[Message part 1 (text/plain, inline)]

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

[0001-Mention-that-revert-buffer-isn-t-best-for-markers-pr.patch (text/x-patch, attachment)]

[0002-Mention-that-auto-revert-mode-may-break-markers.patch (text/x-patch, attachment)]

Message #8 received at 49661 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Konstantin Kharlamov <hi-angel <at> yandex.ru>
Cc: 49661 <at> debbugs.gnu.org
Subject: Re: bug#49661: (patches) Improve docs for revert-buffer and
 auto-revert-mode
Date: Tue, 20 Jul 2021 16:39:54 +0200

Konstantin Kharlamov <hi-angel <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.