Subject: bug#1185 closed by Chong Yidong <[email-masked]> (23.0.60; Doc string of region-active-p considered unhelpful)

From: [email-masked] (Emacs bug Tracking System)

This is an automatic notification regarding your bug report
which was filed against the emacs package:

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

It has been closed by Chong Yidong <[email-masked]>.

Their explanation is attached below along with your original report.
If this explanation is unsatisfactory and you have not received a
better one in a separate message then please contact Chong Yidong <[email-masked]> by
replying to this email.

-- 
1185: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=1185
Emacs Bug Tracking System
Contact [email-masked] with problems
>From [email-masked] Tue Oct 21 10:04:41 2008
From: Chong Yidong <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked]
Subject: 23.0.60; Doc string of region-active-p considered unhelpful
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.

>From [email-masked] Thu Oct 16 12:43:30 2008
Date: Thu, 16 Oct 2008 21:42:28 +0200
From: Eli Zaretskii <[email-masked]>
Subject: 23.0.60; Doc string of region-active-p considered unhelpful
To: [email-masked]

Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your bug report will be posted to the [email-masked] mailing list.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

"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?

If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
If you would like to further debug the crash, please read the file
d:/gnu/emacs/etc/DEBUG for instructions.

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-16 on HOME-C4E4A596F7
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  value of $XMODIFIERS: nil
  locale-coding-system: cp1255
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  tooltip-mode: t
  tool-bar-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<help-echo> C-h f r <backspace> u e <backspace> s e 
- r e g <tab> <return> C-x o <down> <left> <left> <left> 
<left> <left> <left> <left> <return> <next> <up> <next> 
<prior> <prior> <prior> <prior> <next> <next> <next> 
<down> <down> <down> <C-right> <right> C-s C-w C-w 
C-w C-s C-s C-r C-r C-r <up> <help-echo> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <help-echo> C-x C-f a l l <tab> <return> 
C-s u s e - r e g <help-echo> <help-echo> <help-echo> 
C-x C-f <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> - 2 2 <tab> - <tab> e m <tab> 
/ l i s <tab> / a l l <tab> <return> C-s m a r k - 
a <up> C-x b s i m p <tab> <return> <next> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <help-echo> 
<help-echo> M-x r e p o r t - e <tab> <return>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Type C-x 1 to delete the help window.
Loading vc-cvs...done
Mark saved where search started
Making completion list...
Mark saved where search started