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

[Drew Adams <drew.adams@oracle.com>]

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'