Subject: 23.0.60; Doc string of region-active-p considered unhelpful

From: Chong Yidong <[email-masked]>
Date: Tue, 21 Oct 2008 13:04:40 -0400

> "C-h f region-active-p RET" produces the following documentation:
>
>   Return t if Transient Mark mode is enabled and the mark is active.
>   This is NOT the best function to use to test whether a command should
>   operate on the region instead of the usual behavior -- for that,
>   use `use-region-p'.
>
> This is not really helpful: it does not tell why would a Lisp program
> want to use this function.  Are there any circumstances where this
> function is useful, or do we keep it for compatibility reasons?

The reason to use use-region-p is because that checks whether the region
is empty and compares that with use-empty-active-region.  That's what we
want for most commands that have the behavior "do X on the region if
it's active".  But in some circumstances, we don't care about whether or
not the region is empty; e.g., some commands want to deactivate the mark
if region-active-p is non-nil.

I checked in a doc fix.