@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.
-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}.
+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
+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
+@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
@code{push-mark} discards an old mark when it adds a new one.
@end defopt
+@defun handle-shift-selection &optional deactivate
+This function checks whether the current command was invoked via shift
+translation (@pxref{Key Sequence Input, shift-translation}), and if
+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-@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
+
@node The Region
@section The Region
@cindex region (between point and mark)