* debugging.texi (Error Debugging): Don't mislead the reader into

[gnu-emacs] / doc / lispref / markers.texi

diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 6a02a95e0388e6037e8d2ec094043ff59daf068a..e636ce97078e9e8e6d4c2cedc6830ace71a27361 100644 (file)
--- 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 -*-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
 @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).
 
 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}.
 
 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.
 
 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
 
 @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
 @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
 @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
 @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
 
 @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)
 @node The Region
 @section The Region
 @cindex region (between point and mark)