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

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

[Eli Zaretskii]

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 emacs-pretest-bug@gnu.org 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

bug#1185: marked as done (23.0.60; Doc string of region-active-p considered unhelpful)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 876 bytes --]


Your message dated Tue, 21 Oct 2008 13:04:40 -0400
with message-id <87d4htswuv.fsf@cyd.mit.edu>
and subject line 23.0.60; Doc string of region-active-p considered unhelpful
has caused the Emacs bug report #1185,
regarding 23.0.60; Doc string of region-active-p considered unhelpful
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
1185: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=1185
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 4813 bytes --]

From: Eli Zaretskii <eliz@gnu.org>
To: emacs-pretest-bug@gnu.org
Subject: 23.0.60; Doc string of region-active-p considered unhelpful
Date: Thu, 16 Oct 2008 21:42:28 +0200
Message-ID: <uvdvsmimz.fsf@gnu.org>


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 emacs-pretest-bug@gnu.org 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



[-- Attachment #3: Type: message/rfc822, Size: 1892 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 1185-done@emacsbugs.donarmstrong.com
Subject: 23.0.60; Doc string of region-active-p considered unhelpful
Date: Tue, 21 Oct 2008 13:04:40 -0400
Message-ID: <87d4htswuv.fsf@cyd.mit.edu>

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