[Emacs-diffs] Changes to emacs/doc/lispref/markers.texi,v

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    08/10/16 20:05:32

Index: markers.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/markers.texi,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- markers.texi        15 Oct 2008 19:53:00 -0000      1.5
+++ markers.texi        16 Oct 2008 20:05:32 -0000      1.6
@@ -423,7 +423,11 @@
 address@hidden 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,6 +559,11 @@
 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 address@hidden,
 address@hidden values to enable Transient Mark mode temporarily.  If the
 value is @code{lambda}, Transient Mark mode is automatically turned
@@ -566,6 +575,14 @@
 action that would normally deactivate the mark.
 @end defopt
 
address@hidden Subroutine 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.
address@hidden deffn
+
 @defopt mark-even-if-inactive
 If this is address@hidden, Lisp programs and the Emacs user can use the
 mark even when it is inactive.  This option affects the behavior of
@@ -598,8 +615,11 @@
 @end defun
 
 @defvar mark-active
-The mark is active when this variable is address@hidden  This variable
-is always buffer-local in each buffer.
+The mark is active when this variable is address@hidden  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