bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical

bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical

[MON KEY]

docstring of `region-active-p' is nonsensical.

"Most commands that act on the region if it is active and
Transient Mark mode is enabled, and on the text near point
otherwise, should use `use-region-p' instead.  That function
checks the value of `use-empty-active-region' as well."

In particular, this clause;
", and on the text near point otherwise,"

I am a native english speaker and have _NO CLUE_ what this is trying to say.

While I am somewhat aware of the idiosyncrasies of transient mark,
region, etc. and the baggage involved in this particular arena of
documentation. There doesn't seem to be any good reason for this
docstring to be quit so obtuse.

I believe this was touched upon (and/or skirted around) here:
(URL `http://lists.gnu.org/archive/html/emacs-devel/2009-05/msg00563.html')

Was there any resolution?

;;; ==============================
In GNU Emacs 23.1.50.1 (i386-mingw-nt5.1.2600)
 of 2009-06-30 on LENNART-69DE564 (patched)
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'

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: cp1252
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  show-point-mode: t
  show-paren-mode: t
  display-time-mode: t
  auto-image-file-mode: t
  server-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  noticeable-minibuffer-prompts-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical

[Lennart Borgman]

On Fri, Jul 17, 2009 at 8:05 PM, MON KEY<monkey@sandpframing.com> wrote:
> "Most commands that act on the region if it is active and
> Transient Mark mode is enabled, and on the text near point
> otherwise, should use `use-region-p' instead.  That function
> checks the value of `use-empty-active-region' as well."

To me it would be more clear with something like:

"Most commands that act on the visibly selected region text, and on
the text near point otherwise, should use `use-region-p' instead.
That function checks the value of `use-empty-active-region' as well.

Note: In Emacs the region is visible if it is active and Transient
Mark mode is enabled. To make this work as in most other editing
environtments today you can use `cua-mode'."

bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical

[MON KEY]

On Fri, Jul 17, 2009 at 2:28 PM, Lennart
Borgman<lennart.borgman@gmail.com> wrote:
> To me it would be more clear with something like:
>
> Mark mode is enabled. To make this work as in most other editing
> environtments today you can use `cua-mode'."
>
Lennart, I appreciate the `cua-mode' plug :)
However, this is not the issue nor the solution and can only introduce
additional confusion...

My proposal:

"`region-active-p'

Return t if Transient Mark mode is enabled and the mark is active.

Commands which act on the region may require to test if it is active;
if Transient Mark mode is enabled; or if it is otherwise at the text
near point should use `use-region-p' instead.

This function is usually the wrong thing to use when testing if
the region is active and if it is appropriate to act on it.
It can return incorrect results when used with commands which act on the
region by disregarding the value of `use-empty-active-region'."

s_P

bug#3873: marked as done (23.1.50; docstring of `region-active-p' is nonsensical)

[Emacs bug Tracking System]

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


Your message dated Sat, 18 Jul 2009 13:40:53 -0400
with message-id <873a8trisa.fsf@stupidchicken.com>
and subject line Re: bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical
has caused the Emacs bug report #3873,
regarding 23.1.50; docstring of `region-active-p' is nonsensical
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 owner@emacsbugs.donarmstrong.com
immediately.)


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

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

From: MON KEY <monkey@sandpframing.com>
To: emacs-pretest-bug@gnu.org
Subject: 23.1.50; docstring of `region-active-p' is nonsensical
Date: Fri, 17 Jul 2009 14:05:02 -0400
Message-ID: <d2afcfda0907171105y7f34f68fsa35d37211ceaef8f@mail.gmail.com>

docstring of `region-active-p' is nonsensical.

"Most commands that act on the region if it is active and
Transient Mark mode is enabled, and on the text near point
otherwise, should use `use-region-p' instead.  That function
checks the value of `use-empty-active-region' as well."

In particular, this clause;
", and on the text near point otherwise,"

I am a native english speaker and have _NO CLUE_ what this is trying to say.

While I am somewhat aware of the idiosyncrasies of transient mark,
region, etc. and the baggage involved in this particular arena of
documentation. There doesn't seem to be any good reason for this
docstring to be quit so obtuse.

I believe this was touched upon (and/or skirted around) here:
(URL `http://lists.gnu.org/archive/html/emacs-devel/2009-05/msg00563.html')

Was there any resolution?

;;; ==============================
In GNU Emacs 23.1.50.1 (i386-mingw-nt5.1.2600)
 of 2009-06-30 on LENNART-69DE564 (patched)
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'

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: cp1252
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  shell-dirtrack-mode: t
  diff-auto-refine-mode: t
  show-point-mode: t
  show-paren-mode: t
  display-time-mode: t
  auto-image-file-mode: t
  server-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  noticeable-minibuffer-prompts-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t


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

From: Chong Yidong <cyd@stupidchicken.com>
To: MON KEY <monkey@sandpframing.com>
Cc: Lennart Borgman <lennart.borgman@gmail.com>, 3873-done@emacsbugs.donarmstrong.com
Subject: Re: bug#3873: 23.1.50; docstring of `region-active-p' is nonsensical
Date: Sat, 18 Jul 2009 13:40:53 -0400
Message-ID: <873a8trisa.fsf@stupidchicken.com>

> Commands which act on the region may require to test if it is active;
> if Transient Mark mode is enabled; or if it is otherwise at the text
> near point should use `use-region-p' instead.

I'm afraid this sentence is even more confusing.

I checked a different fix into CVS.