bug#69511: Restore any state after revert-buffer

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Sat, 02 Mar 2024 19:55:50 +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.

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.

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

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

Thanks.