X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/7b1019e2781472c793d0bf74e2b9ee17894270b8..b1f23349eb103eba22f9e2181f97a5fc939f86e0:/doc/lispref/markers.texi?ds=sidebyside

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 6a02a95e03..e636ce9707 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -1,7 +1,7 @@
 @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
@@ -423,7 +423,11 @@ 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
+  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}.
 
@@ -555,13 +559,30 @@ 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}.
+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
@@ -594,8 +615,11 @@ Otherwise it does nothing.
 @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
@@ -626,6 +650,20 @@ more marks than this are pushed onto the @code{mark-ring},
 @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)