X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a9685db74e15f9c6336850ffda8932ed208c76cd..62d81bd7cb144c30c25739d40e4fd3208e6987f5:/doc/lispref/markers.texi

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index b199dba979..19386d638f 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -1,9 +1,9 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@setfilename ../../info/markers
-@node Markers, Text, Positions, Top
+@node Markers
 @chapter Markers
 @cindex markers
 
@@ -206,7 +206,7 @@ chapter.
 @end example
 @end defun
 
-@defun copy-marker marker-or-integer &optional insertion-type
+@defun copy-marker &optional marker-or-integer insertion-type
 If passed a marker as its argument, @code{copy-marker} returns a
 new marker that points to the same place and the same buffer as does
 @var{marker-or-integer}.  If passed an integer as its argument,
@@ -216,11 +216,14 @@ new marker that points to the same place and the same buffer as does
 The new marker's insertion type is specified by the argument
 @var{insertion-type}.  @xref{Marker Insertion Types}.
 
+@c This behavior used to be documented until 2013/08.
+@ignore
 If passed an integer argument less than 1, @code{copy-marker} returns a
 new marker that points to the beginning of the current buffer.  If
 passed an integer argument greater than the length of the buffer,
 @code{copy-marker} returns a new marker that points to the end of the
 buffer.
+@end ignore
 
 @example
 @group
@@ -279,6 +282,8 @@ This function returns the position that @var{marker} points to, or
 This function returns the buffer that @var{marker} points into, or
 @code{nil} if it points nowhere.
 
+@c FIXME: The `buffer' argument of `set-marker' already defaults to
+@c the current buffer, why use `(current-buffer)' explicitly here?
 @example
 @group
 (setq m (make-marker))
@@ -308,11 +313,6 @@ This function returns the buffer that @var{marker} points into, or
 @end example
 @end defun
 
-@defun buffer-has-markers-at position
-This function returns @code{t} if one or more markers
-point at position @var{position} in the current buffer.
-@end defun
-
 @node Marker Insertion Types
 @section Marker Insertion Types
 
@@ -344,21 +344,27 @@ 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}
 in @var{buffer}.  If @var{buffer} is not provided, it defaults to
 the current buffer.
 
+@c This behavior used to be documented until 2013/08.
+@ignore
 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
 to the beginning of the buffer.  If @var{position} is greater than the
-size of the buffer, @code{set-marker} moves marker to the end of the
-buffer.  If @var{position} is @code{nil} or a marker that points
-nowhere, then @var{marker} is set to point nowhere.
+size of the buffer (@pxref{Point}), @code{set-marker} moves marker to
+the end of the buffer.
+@end ignore
+If @var{position} is @code{nil} or a marker that points nowhere, then
+@var{marker} is set to point nowhere.
 
 The value returned is @var{marker}.
 
@@ -389,7 +395,7 @@ This is another name for @code{set-marker}.
 @node The Mark
 @section The Mark
 @cindex mark, the
-@cindex mark ring
+@c @cindex the mark?
 
   Each buffer has a special marker, which is designated @dfn{the
 mark}.  When a buffer is newly created, this marker exists but does
@@ -428,6 +434,7 @@ the mark is active.  This is the main motivation for using Transient
 Mark mode.  (Another is that this enables highlighting of the region
 when the mark is active.  @xref{Display}.)
 
+@cindex mark ring
   In addition to the mark, each buffer has a @dfn{mark ring} which is a
 list of markers containing previous values of the mark.  When editing
 commands change the mark, they should normally save the old value of the
@@ -595,8 +602,16 @@ the function @code{use-region-p} for that (@pxref{The Region}).
 @defvarx deactivate-mark-hook
 These normal hooks are run, respectively, when the mark becomes active
 and when it becomes inactive.  The hook @code{activate-mark-hook} is
-also run at the end of a command if the mark is active and it is
-possible that the region may have changed.
+also run at the end of the command loop if the mark is active and it
+is possible that the region may have changed.
+@ignore
+This piece of command_loop_1, run unless deactivating the mark:
+  if (current_buffer != prev_buffer || MODIFF != prev_modiff)
+    {
+      Lisp_Object hook = intern ("activate-mark-hook");
+      Frun_hooks (1, &hook);
+    }
+@end ignore
 @end defvar
 
 @defun handle-shift-selection
@@ -641,7 +656,12 @@ more marks than this are pushed onto the @code{mark-ring},
 
 @node The Region
 @section The Region
-@cindex region (between point and mark)
+@c The index entry must be just ``region'' to make it the first hit
+@c when the user types ``i region RET'', because otherwise the Info
+@c reader will present substring matches in alphabetical order,
+@c putting this one near the end, with something utterly unrelated as
+@c the first hit.
+@cindex region
 
   The text between point and the mark is known as @dfn{the region}.
 Various functions operate on text delimited by point and the mark, but
@@ -665,6 +685,7 @@ integer).  This is the position of either point or the mark, whichever is
 larger.
 @end defun
 
+@c FIXME: Mention it in tips.texi?
   Instead of using @code{region-beginning} and @code{region-end}, a
 command designed to operate on a region should normally use
 @code{interactive} with the @samp{r} specification to find the
@@ -677,6 +698,8 @@ mark is active, and there is a valid region in the buffer.  This
 function is intended to be used by commands that operate on the
 region, instead of on text near point, when the mark is active.
 
+@cindex empty region
+@vindex use-empty-active-region
 A region is valid if it has a non-zero size, or if the user option
 @code{use-empty-active-region} is non-@code{nil} (by default, it is
 @code{nil}).  The function @code{region-active-p} is similar to