@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/markers
@node Markers, Text, Positions, Top
@cindex mark, the
@cindex mark ring
- One special marker in each buffer is designated @dfn{the mark}. It
-specifies a position to bound a range of text for commands such as
-@code{kill-region} and @code{indent-rigidly}. Lisp programs should
-set the mark only to values that have a potential use to the user, and
-never for their own internal purposes. For example, the
-@code{replace-regexp} command sets the mark to the value of point
-before doing any replacements, because this enables the user to move
-back there conveniently after the replace is finished.
-
- Many commands are designed to operate on the text between point and
-the mark when called interactively. If you are writing such a
-command, don't examine the mark directly; instead, use
+ 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
+buffer yet. Subsequent commands can set the mark.
+
+ The mark specifies a position to bound a range of text for many
+commands, such as @code{kill-region} and @code{indent-rigidly}. These
+commands typically act on the text between point and the mark, which
+is called the @dfn{region}. If you are writing a command that
+operates on the region, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification. This provides the
values of point and the mark as arguments to the command in an
interactive call, but permits other Lisp programs to specify arguments
explicitly. @xref{Interactive Codes}.
- Each buffer has a marker which represents the value of the mark in
-that buffer, independent of any other buffer. When a buffer is newly
-created, this marker exists but does not point anywhere. That means
-the mark ``doesn't exist'' in that buffer as yet.
+ Some commands set the mark as a side-effect. Commands should do
+this only if it has a potential use to the user, and never for their
+own internal purposes. For example, the @code{replace-regexp} command
+sets the mark to the value of point before doing any replacements,
+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
-exist. However, it may become @dfn{inactive}, if Transient Mark mode is
-enabled. The variable @code{mark-active}, which is always buffer-local
-in all buffers, indicates whether the mark is active: non-@code{nil}
-means yes. A command can request deactivation of the mark upon return
-to the editor command loop by setting @code{deactivate-mark} to a
-non-@code{nil} value (but this causes deactivation only if Transient
-Mark mode is enabled).
-
- The main motivation for using Transient Mark mode is that this mode
-also enables highlighting of the region when the mark is active.
-@xref{Display}.
+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
+function @code{deactivate-mark} to deactivate the mark directly, or it
+can request deactivation of the mark upon return to the editor command
+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}.)
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
If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
@code{nil}, @code{mark} signals an error if the mark is inactive.
However, if @var{force} is non-@code{nil}, then @code{mark} disregards
-inactivity of the mark, and returns the mark position anyway (or
-@code{nil}).
+inactivity of the mark, and returns the mark position (or @code{nil})
+anyway.
@end defun
@defun mark-marker
results. We recommend that you not do it!
@end defun
-@ignore
-@deffn Command set-mark-command jump
-If @var{jump} is @code{nil}, this command sets the mark to the value
-of point and pushes the previous value of the mark on the mark ring. The
-message @samp{Mark set} is also displayed in the echo area.
-
-If @var{jump} is not @code{nil}, this command sets point to the value
-of the mark, and sets the mark to the previous saved mark value, which
-is popped off the mark ring.
-
-This function is @emph{only} intended for interactive use.
-@end deffn
-@end ignore
-
@defun set-mark position
This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.
@end example
@end defun
-@c for interactive use only
-@ignore
-@deffn Command exchange-point-and-mark
-This function exchanges the positions of point and the mark.
-It is intended for interactive use.
-@end deffn
-@end ignore
-
@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}. If
@end defun
@defopt transient-mark-mode
-@c @cindex Transient Mark mode Redundant
-This variable if non-@code{nil} enables Transient Mark mode, in which
-every buffer-modifying primitive sets @code{deactivate-mark}. The
-consequence of this is that commands that modify the buffer normally
-make the mark inactive.
-
-Lisp programs can set @code{transient-mark-mode} to @code{only} to
-enable Transient Mark mode for the following command only. During
-that following command, the value of @code{transient-mark-mode} is
-@code{identity}. If it is still @code{identity} at the end of the
-command, it changes to @code{nil}.
+This variable, if non-@code{nil}, enables Transient Mark mode. In
+Transient Mark mode, every buffer-modifying primitive sets
+@code{deactivate-mark}. As a consequence, most commands that modify
+the buffer also deactivate the mark.
+
+When Transient Mark mode is enabled and the mark is active, many
+commands that normally apply to the text near point instead apply to
+the region. Such commands should use the function @code{use-region-p}
+to test whether they should operate on the region. @xref{The Region}.
+
+Lisp programs can set @code{transient-mark-mode} to non-@code{nil},
+non-@code{t} values to enable Transient Mark mode temporarily. If the
+value is @code{lambda}, Transient Mark mode is automatically turned
+off after any action, such as buffer modification, that would normally
+deactivate the mark. If the value is @w{@code{(only . @var{oldval})}},
+then @code{transient-mark-mode} is set to the value @var{oldval} after
+any subsequent command that moves point and is not shift-translated
+(@pxref{Key Sequence Input, shift-translation}), or after any other
+action that would normally deactivate the mark.
@end defopt
@defopt mark-even-if-inactive
@end defun
@defvar mark-active
-The mark is active when this variable is non-@code{nil}. This variable
-is always buffer-local in each buffer.
+The mark is active when this variable is non-@code{nil}. This
+variable is always buffer-local in each buffer. Do @emph{not} use the
+value of this variable to decide whether a command that normally
+operates on text near point should operate on the region instead. Use
+the function @code{use-region-p} for that (@pxref{The Region}).
@end defvar
@defvar activate-mark-hook
possible that the region may have changed.
@end defvar
+@defun handle-shift-selection
+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}
+spec is invoked, before the command itself is executed
+(@pxref{Interactive Codes, ^}).
+
+If @code{shift-select-mode} is non-@code{nil} and the current command
+was invoked via shift translation (@pxref{Key Sequence Input,
+shift-translation}), this function sets the mark and temporarily
+activates the region, unless the region was already temporarily
+activated in this way. Otherwise, if the region has been activated
+temporarily, it deactivates the mark and restores the variable
+@code{transient-mark-mode} to its earlier value.
+@end defun
+
@defvar mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
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.
+@end defun
+
@ignore
arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
@end ignore