@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
@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.
(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
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
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
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
@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
+
HCoop / bpt / emacs.git / blobdiff