@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
@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
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
@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}.
@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
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
@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
@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