bug#69511: Restore any state after revert-buffer

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 69511@debbugs.gnu.org
> Date: Sun, 03 Mar 2024 09:59:24 +0200
> 
> >> This patch adds a new variable 'revert-buffer-state-functions'
> >> that will allow any state to be saved and restored,
> >> not only the currently hard-coded 'read-only' state:
> >
> > It isn't clear what you mean by "state" here.  It seems like you are
> > talking about functions to be called after reverting a buffer in order
> > to do whatever is appropriate after reverting.  And if so, why
> > "state"?  For example, one of your examples, with
> > outline-minor-mode-highlight-buffer, is not about "state", but about
> > re-highlighting the buffer after reverting it.
> 
> "state" here is in the same sense as is already used in 'revert-buffer':

"Two wrongs don't make a right", as the saying goes.  And the name of
a local variable is much less significant than the name of a public
variable.

> > So I would suggest calling this "revert-buffer-post-revert-functions",
> > and updating the doc string to make it clear that the purpose is more
> > general.
> 
> "post" can't be used because these functions are called
> before 'revert-buffer-function'.

According to your doc string, the lambdas these functions produce are
called _after_ reverting the buffer.  So I see no reason not to use
"post" here.

> "pre" would be better but still has no hint that the returned lambdas
> will be called after 'revert-buffer-function' to restore a state.

The doc string can make that evident, so that's not a problem IMO.
And again, "restore a state" doesn't describe what, for example,
outline-minor-mode-highlight-buffer does.  So this is not a good
source for a descriptive name of the variable.

> >> +(defvar-local revert-buffer-state-functions nil
> >> +  "Functions to save and restore any state during `revert-buffer'.
> >> +This variable is a list of functions that are called before
> >> +reverting the buffer.  These functions should return a lambda
> >> +that will be called after reverting the buffer
> >> +to restore a previous state saved in that lambda.")
> >
> > The last sentence needs to be reworded, because it is not clear how
> > functions (in plural) can return a lambda (in singular).  Also, the
> > doc string should describe how the function is called (with no
> > arguments, I guess?), and that all those functions will be called one
> > by one in the order of the list.
> 
> Here is an improved docstring:
> 
> (defvar-local revert-buffer-state-functions nil
>   "Functions to save and restore any state during `revert-buffer'.
> This variable is a list of functions that are called before reverting
  ^^^^^^^^^^^^^
"The value of this variable..."

> the buffer.  Each of these functions are called without arguments and
> should return a lambda that can restore a previous state of the buffer.
> Then after reverting the buffer each of these lambdas will be called
> one by one in the order of the list to restore previous states of the
> buffer.  An example of the buffer state is keeping the buffer read-only,
> or keeping minor modes, etc.")

Apart of the "state" thing, which I think is sub-optimal for the
reasons explained above, this is fine, thanks.