@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 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.
-@setfilename ../../info/markers
-@node Markers, Text, Positions, Top
+@node Markers
@chapter Markers
@cindex 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
@section Overview of Markers
- A marker specifies a buffer and a position in that buffer. The
-marker can be used to represent a position in the functions that
+ A marker specifies a buffer and a position in that buffer. A
+marker can be used to represent a position in functions that
require one, just as an integer could be used. In that case, the
marker's buffer is normally ignored. Of course, a marker used in this
way usually points to a position in the buffer that the function
A marker has three attributes: the marker position, the marker
buffer, and the insertion type. The marker position is an integer
that is equivalent (at a given time) to the marker as a position in
-that buffer. But the marker's position value can change often during
-the life of the marker. Insertion and deletion of text in the buffer
-relocate the marker. The idea is that a marker positioned between two
-characters remains between those two characters despite insertion and
-deletion elsewhere in the buffer. Relocation changes the integer
-equivalent of the marker.
+that buffer. But the marker's position value can change during
+the life of the marker, and often does. Insertion and deletion of
+text in the buffer relocate the marker. The idea is that a marker
+positioned between two characters remains between those two characters
+despite insertion and deletion elsewhere in the buffer. Relocation
+changes the integer equivalent of the marker.
@cindex marker relocation
Deleting text around a marker's position leaves the marker between the
relocate them if necessary. This slows processing in a buffer with a
large number of markers. For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
-Unreferenced markers are garbage collected eventually, but until then
-will continue to use time if they do point somewhere.
+Markers that can no longer be accessed are eventually removed
+(@pxref{Garbage Collection}).
@cindex markers as numbers
Because it is common to perform arithmetic operations on a marker
-position, most of the arithmetic operations (including @code{+} and
+position, most of these operations (including @code{+} and
@code{-}) accept markers as arguments. In such cases, the marker
stands for its current position.
@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
(point-min-marker)
@result{} #<marker at 1 in markers.texi>
(point-max-marker)
- @result{} #<marker at 15573 in markers.texi>
+ @result{} #<marker at 24080 in markers.texi>
@end group
@group
@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,
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
@end group
@group
-(copy-marker 20000)
- @result{} #<marker at 7572 in markers.texi>
+(copy-marker 90000)
+ @result{} #<marker at 24080 in markers.texi>
@end group
@end example
@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
loop by setting the variable @code{deactivate-mark} to a
non-@code{nil} value.
- If Transient Mode is enabled, certain editing commands that normally
-apply to text near point, apply instead to the region when 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}.)
+ If Transient Mark mode is enabled, certain editing commands that
+normally apply to text near point, apply instead to the region when
+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
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}. If
@var{position} is @code{nil}, then the value of point is used.
-@code{push-mark} returns @code{nil}.
+@c Doesn't seem relevant.
+@c @code{push-mark} returns @code{nil}.
The function @code{push-mark} normally @emph{does not} activate the
mark. To do that, specify @code{t} for the argument @var{activate}.
that mark become the buffer's actual mark. This does not move point in
the buffer, and it does nothing if @code{mark-ring} is empty. It
deactivates the mark.
-
-The return value is not meaningful.
+@c
+@c Seems even less relevant.
+@c The return value is not meaningful.
@end defun
@defopt transient-mark-mode
@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
-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}
@code{push-mark} discards an old mark when it adds a new one.
@end defopt
+@c There is also global-mark-ring-max, but this chapter explicitly
+@c does not talk about the global mark.
+
@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
- Few programs need to use the @code{region-beginning} and
-@code{region-end} functions. A command designed to operate on a region
-should normally use @code{interactive} with the @samp{r} specification
-to find the beginning and end of the region. This lets other Lisp
-programs specify the bounds explicitly as arguments. (@xref{Interactive
-Codes}.)
+@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
+beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments. @xref{Interactive Codes}.
@defun use-region-p
This function returns @code{t} if Transient Mark mode is enabled, the
-mark is active, and there's a valid region in the buffer. Commands
-that operate on the region (instead of on text near point) when
-there's an active mark should use this to test whether to do that.
+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
+@code{use-region-p}, but considers all regions as valid. In most
+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