bug#30028: 24.5; behavior and doc of `revert-buffer' wrt markers

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> That markers are typically restored when you revert is important.
> This behavior is not very well documented, I think.
>
> 1. Doc: The elisp manual (node `Reverting'), but not the doc string,
>    mentions that markers at the beginning and end of the buffer (after
>    changes) are generally preserved (restored).  The doc string should
>    mention this also - it says nothing about markers.

I've now mentioned this in the doc string (and punting to the manual for
details).

> 2. Doc: This restoring of markers happens for visited files, but not
>    necessarily for other buffers, presumably.  The doc in at least the
>    manual should make this clear.

Yes, it's up to the specific `revert-buffer-function'.  I've now
mentioned this in the manual.

> 3. Behavior: The manual says that preserving other markers, besides
>    those described, "would be problematical".  (You might want to change
>    that to "problematic", but this is not important -
>    http://grammarist.com/usage/problematic-problematical)

Done.

>    I can understand that in some cases restoring a marker would not
>    position it correctly.  But I don't see why Emacs wouldn't/couldn't
>    restore all markers anyway.  Or does it?  The doc does not make clear
>    whether markers that are not "preserved" are deleted or just not
>    necessarily in the correct positions.  Please make clear just how
>    (all) markers are handled.
>
>    What criteria does Emacs use for filtering out markers that it
>    decides not to restore?

The manual says:

---
If they are not identical, reverting does change the buffer; in that
case, it preserves the markers in the unchanged text (if any) at the
beginning and end of the buffer.
---

So it restores markers in identical text at the start and end.  I don't
see what's unclear about that.

> 4. Trying to track down where the marker handling
>    (e.g. saving/restoring) takes place sent me down multiple levels
>    of code.  My guess (I don't have the C sources) is that it is
>    actually done in `insert-file-contents'.  But the doc for that
>    function (both (elisp) `Reading from Files' and doc string) says even
>    less about marker handling than does the doc for `revert-buffer'.
>    Can we please get more informative doc about this handling?

The Reverting node is actually describing what's happening in that
function, which is why that section starts with:

---
Reverting tries to preserve marker positions in the buffer by using the
replacement feature of @code{insert-file-contents}.
---

The `insert-file-contents' doc string is more vague here...  I'll add
the sentence about the start/end bits.

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