Merge from origin/emacs-24

[gnu-emacs] / doc / lispref / markers.texi

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 80136f2e6f42e4a10986471ac4c4f08914834922..5902a3a836ffe1a96ec7f3e2d22606882d243afb 100644 (file)
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -1,6 +1,7 @@
 @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.
 @node Markers
 @chapter Markers
@@ -117,6 +118,8 @@ m1
 
 @node Predicates on Markers
 @section Predicates on Markers
+@cindex predicates for markers
+@cindex markers, predicates for
 
   You can test an object to see whether it is a marker, or whether it is
 either an integer or a marker.  The latter test is useful in connection
@@ -140,6 +143,8 @@ integer or floating point) or a marker, @code{nil} otherwise.
 
 @node Creating Markers
 @section Functions that Create Markers
+@cindex creating markers
+@cindex marker creation
 
   When you create a new marker, you can make it point nowhere, or point
 to the present position of point, or to the beginning or end of the
@@ -215,11 +220,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
@@ -265,6 +273,7 @@ if they both point nowhere.
 
 @node Information from Markers
 @section Information from Markers
+@cindex marker information
 
   This section describes the functions for accessing the components of a
 marker object.
@@ -278,6 +287,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))
@@ -307,11 +318,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
 
@@ -341,6 +347,8 @@ specify the insertion type, create them with insertion type
 
 @node Moving Markers
 @section Moving Marker Positions
+@cindex moving markers
+@cindex marker, how to move position
 
   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
@@ -353,11 +361,15 @@ 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 (@pxref{Point}), @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.
+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}.
 
@@ -388,7 +400,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
@@ -427,6 +439,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
@@ -648,7 +661,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
@@ -672,6 +690,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
@@ -684,6 +703,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