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

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

[Drew Adams]

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.

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.

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)

   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?

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?



In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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