* markers.texi (Moving Marker Positions): Clarify guidance about

when to move markers and when to create a new one, as discussed at
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16818#17

2 files changed, 12 insertions, 4 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e87272401d6..bd13a7d56ed 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2014-03-02  Barry O'Reilly <gundaetiapo@gmail.com>
+
+        * markers.texi (Moving Marker Positions): Clarify guidance about
+        when to move markers and when to create a new one, as discussed at
+        http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16818#17
+
 2014-03-02  Glenn Morris  <rgm@gnu.org>
 
         * text.texi (Decompression): New node.
diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 51b87ab1e5b..19386d638fe 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -344,10 +344,12 @@ specify the insertion type, create them with insertion type
 @section Moving Marker Positions
 
   This section describes how to change the position of an existing
-marker.  When you do this, be sure you know whether the marker is used
-outside of your program, and, if so, what effects will result from
-moving it---otherwise, confusing things may happen in other parts of
-Emacs.
+marker.  When you do this, be sure you know how the marker is used
+outside of your program.  For example, moving a marker to an unrelated
+new position can cause undo to later adjust the marker incorrectly.
+Often when you wish to relocate a marker to an unrelated position, it
+is preferable to make a new marker and set the prior one to point
+nowhere.
 
 @defun set-marker marker position &optional buffer
 This function moves @var{marker} to @var{position}