bug#69511: Restore any state after revert-buffer

[Juri Linkov]

>> 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':

  (let ((state (and (boundp 'read-only-mode--state)
                    (list read-only-mode--state))))
    (prog1 (funcall (or revert-buffer-function #'revert-buffer--default)
                    ignore-auto noconfirm)
      (when state
        (setq buffer-read-only (car state))
        (setq-local read-only-mode--state (car state)))))

> 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'.

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

>> +(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 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.")

> Finally, this needs to be documented in NEWS and the ELisp reference
> manual.

If this docstring is ok, then it could be adapted to the ELisp reference
manual.