all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#30028: 24.5; behavior and doc of `revert-buffer' wrt markers
@ 2018-01-08 17:35 Drew Adams
  2020-12-12 11:20 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 2+ messages in thread
From: Drew Adams @ 2018-01-08 17:35 UTC (permalink / raw)
  To: 30028

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'





^ permalink raw reply	[flat|nested] 2+ messages in thread

* bug#30028: 24.5; behavior and doc of `revert-buffer' wrt markers
  2018-01-08 17:35 bug#30028: 24.5; behavior and doc of `revert-buffer' wrt markers Drew Adams
@ 2020-12-12 11:20 ` Lars Ingebrigtsen
  0 siblings, 0 replies; 2+ messages in thread
From: Lars Ingebrigtsen @ 2020-12-12 11:20 UTC (permalink / raw)
  To: Drew Adams; +Cc: 30028

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





^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2020-12-12 11:20 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-01-08 17:35 bug#30028: 24.5; behavior and doc of `revert-buffer' wrt markers Drew Adams
2020-12-12 11:20 ` Lars Ingebrigtsen

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.