@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
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
+ Certain editing commands that normally apply to text near point,
+work on the region when Transient Mode is enabled and the mark is
+active. This is the main motivation for using Transient Mark mode.
+
+ Another motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active.
@xref{Display}.
consequence of this is that commands that modify the buffer normally
make the mark inactive.
+Certain commands normally apply to text near point, but in Transient
+Mark mode when the mark is active, they apply to the region instead.
+These commands should call @code{use-region-p} to test whether they
+should operate on 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
action that would normally deactivate the mark.
@end defopt
+@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 subroutine to test whether to
+do that.
+@end defun
+
@defopt mark-even-if-inactive
If this is non-@code{nil}, Lisp programs and the Emacs user can use the
mark even when it is inactive. This option affects the behavior of
@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 @code{use-region-p} subroutine (see above) for that.
@end defvar
@defvar activate-mark-hook
so, sets the mark and temporarily activates the region, unless the
region is already temporarily activated in this way. If the command
was invoked without shift translation, or if the optional argument
-@var{deactivate} is non-nil, the function deactivates the mark. This
-function is called whenever a command with a @samp{^} character in its
-@code{interactive} spec (@pxref{Interactive Codes, ^}) is invoked
-while @code{shift-select-mode} (@pxref{Shift Selection,,, emacs, The
-GNU Emacs Manual}) is non-@code{nil}.
+@var{deactivate} is non-@code{nil}, the function deactivates the mark.
+This function is called whenever a command with a @samp{^} character
+in its @code{interactive} spec (@pxref{Interactive Codes, ^}) is
+invoked while @code{shift-select-mode} (@pxref{Shift Selection,,,
+emacs, The GNU Emacs Manual}) is non-@code{nil}.
@end defun