@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-2016 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Markers
@chapter Markers
* Marker Insertion Types:: Two ways a marker can relocate when you
insert where it points.
* Moving Markers:: Moving the marker to a new buffer or position.
-* The Mark:: How "the mark" is implemented with a marker.
-* The Region:: How to access "the region".
+* The Mark:: How the mark is implemented with a marker.
+* The Region:: How to access the region.
@end menu
@node Overview of Markers
@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
@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
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
@node Information from Markers
@section Information from Markers
+@cindex marker information
This section describes the functions for accessing the components of a
marker object.
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))
@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
@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
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}.
@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
-not point anywhere; this means that the mark ``doesn't exist'' in that
+not point anywhere; this means that the mark doesn't exist in that
buffer yet. Subsequent commands can set the mark.
The mark specifies a position to bound a range of text for many
because this enables the user to move back there conveniently after
the replace is finished.
- Once the mark ``exists'' in a buffer, it normally never ceases to
+ Once the mark exists in a buffer, it normally never ceases to
exist. However, it may become @dfn{inactive}, if Transient Mark mode
is enabled. The buffer-local variable @code{mark-active}, if
non-@code{nil}, means that the mark is active. A command can call the
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
@end defvar
@defun handle-shift-selection
-This function implements the ``shift-selection'' behavior of
+This function implements the shift-selection behavior of
point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs
Manual}. It is called automatically by the Emacs command loop
whenever a command with a @samp{^} character in its @code{interactive}
@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
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
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
cases, you should not use @code{region-active-p}, since if the region
is empty it is often more appropriate to operate on point.
@end defun
-