From 2de17c73f345b7ad3030e7575a3c82fcff1e9da9 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 16 Oct 2008 20:06:38 +0000 Subject: [PATCH] (The Mark): Document use-region-p. --- doc/lispref/ChangeLog | 4 ++++ doc/lispref/markers.texi | 26 +++++++++++++++++++++++--- etc/NEWS | 1 + 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e8139afdb2a..26da4b8e781 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2008-10-16 Eli Zaretskii + + * markers.texi (The Mark): Document use-region-p. + 2008-10-15 Eli Zaretskii * internals.texi (Writing Emacs Primitives): The interactive spec diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 54bf0bf2a3d..2793346c521 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -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,6 +559,11 @@ every buffer-modifying primitive sets @code{deactivate-mark}. The 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 @@ -566,6 +575,14 @@ any subsequent command that moves point and is not shift-translated action that would normally deactivate the mark. @end defopt +@deffn 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. +@end deffn + @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 @@ -598,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 diff --git a/etc/NEWS b/etc/NEWS index 22ff4f8496d..727beb346cd 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1177,6 +1177,7 @@ interactive forms to subroutines. ** Region changes ++++ *** Commands should use `use-region-p' to test whether there is an active region that they should operate on. -- 2.39.5