unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
@ 2015-08-21 17:17 Drew Adams
  2015-12-04 18:06 ` Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2015-08-21 17:17 UTC (permalink / raw)
  To: 21315

In Emacs 24.4 you changed not only the signature of these commands but
also their interactive behavior, by adding optional arg REGION and
giving users control over it with the prefix arg.

Unfortunately, the doc for this new behavior is horribly inadequate.

1. The Emacs manual says nothing about the new behavior.  It should
   cover it.

2. The doc strings are awful in this regard.  They say only "The
   optional argument REGION if non-nil, indicates that we're not just
   copying some text between BEG and END, but we're copying the region."

   That's worse than saying nothing - a complete cop-out.  If the doc is
   going to say something like "we're copying the region" and if that
   phrase is expected to mean anything then the doc needs to say what it
   means by that.  Describe the user-observable behavior difference
   between using a prefix arg and not using it.

   Currently, the use of a prefix arg is not even mentioned.  As bad as
   the description of parameter REGION is, it is not even connected with
   the use of a prefix arg.

3. The command is not documented at all in the Elisp manual.  It need
   not be, but the current state is that a user has no real information
   about this at all, and that is not good.

4. I find nothing in NEW for Emacs 24.4 (when this was released) about
   this.  User-observable behavior changes like this should be
   documented there.

<rant>Developers should not be allowed to commit program changes like
this without updating the doc appropriately.  Yes, leader resources are
scarce, and people are overworked.  But it's too bad, as it fosters bad
habits, unless the person who committed the code change happens to be
the one who fixes this doc bug, and can thus learn from the
mistake.</rant>

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-07-31 on LEG570
Bzr revision: 8d332aeccab2208e6c6bd434738565e6abf12043
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-08-21 17:17 Drew Adams
@ 2015-12-04 18:06 ` Drew Adams
  2015-12-05 23:12   ` Juri Linkov
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2015-12-04 18:06 UTC (permalink / raw)
  To: 21315

ping

At least make clear that what is said about REGION is only
for calls from Lisp.  REGION is always non-nil when used
interactively.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-04 18:06 ` Drew Adams
@ 2015-12-05 23:12   ` Juri Linkov
  2015-12-06  2:13     ` Drew Adams
  2015-12-06 16:15     ` Eli Zaretskii
  0 siblings, 2 replies; 9+ messages in thread
From: Juri Linkov @ 2015-12-05 23:12 UTC (permalink / raw)
  To: Drew Adams; +Cc: 21315

> ping
>
> At least make clear that what is said about REGION is only
> for calls from Lisp.  REGION is always non-nil when used
> interactively.

Maybe REGION should be non-nil only when used on a non-contiguous
(rectangular) region?





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-05 23:12   ` Juri Linkov
@ 2015-12-06  2:13     ` Drew Adams
  2015-12-06 16:15       ` Eli Zaretskii
  2015-12-06 16:15     ` Eli Zaretskii
  1 sibling, 1 reply; 9+ messages in thread
From: Drew Adams @ 2015-12-06  2:13 UTC (permalink / raw)
  To: Juri Linkov; +Cc: 21315

> > At least make clear that what is said about REGION is only
> > for calls from Lisp.  REGION is always non-nil when used
> > interactively.
> 
> Maybe REGION should be non-nil only when used on a non-contiguous
> (rectangular) region?

Maybe; dunno.  The doc is not clear; that's all I can tell.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-06  2:13     ` Drew Adams
@ 2015-12-06 16:15       ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2015-12-06 16:15 UTC (permalink / raw)
  To: Drew Adams; +Cc: 21315, juri

> Date: Sat, 5 Dec 2015 18:13:37 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21315@debbugs.gnu.org
> 
> > > At least make clear that what is said about REGION is only
> > > for calls from Lisp.  REGION is always non-nil when used
> > > interactively.
> > 
> > Maybe REGION should be non-nil only when used on a non-contiguous
> > (rectangular) region?
> 
> Maybe; dunno.  The doc is not clear; that's all I can tell.

Would it become clear if instead of this:

  The optional argument REGION if non-nil, indicates that we're not
  just copying some text between BEG and END, but we're copying the
  region.

it would say this:

  The optional argument REGION non-nil means to ignore BEG and END and
  copy the region instead.

Also, we should tell that this distinction is only relevant to
invoking these functions from Lisp programs, not interactively.

As for the argument, AFAICT it makes no difference in interactive
usage.  kill-region make it very clear:

    (interactive (list (mark) (point) 'region))

Does documenting the above clarify the issue?





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-05 23:12   ` Juri Linkov
  2015-12-06  2:13     ` Drew Adams
@ 2015-12-06 16:15     ` Eli Zaretskii
  2015-12-08  0:49       ` Juri Linkov
  1 sibling, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2015-12-06 16:15 UTC (permalink / raw)
  To: Juri Linkov; +Cc: 21315

> From: Juri Linkov <juri@linkov.net>
> Date: Sun, 06 Dec 2015 01:12:32 +0200
> Cc: 21315@debbugs.gnu.org
> 
> > ping
> >
> > At least make clear that what is said about REGION is only
> > for calls from Lisp.  REGION is always non-nil when used
> > interactively.
> 
> Maybe REGION should be non-nil only when used on a non-contiguous
> (rectangular) region?

How do you see that?





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
       [not found]       ` <<83si3feepi.fsf@gnu.org>
@ 2015-12-06 16:54         ` Drew Adams
  2015-12-07 16:23           ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2015-12-06 16:54 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 21315, juri

> say this:
>   The optional argument REGION non-nil means to ignore BEG and END and
>   copy the region instead.

Yes.

(But I think we usually phrase that as: "Non-nil optional argument
REGION means...".)

> Also, we should tell that this distinction is only relevant to
> invoking these functions from Lisp programs, not interactively.

Yes.

  From Lisp, non-nil optional argument REGION means...

> As for the argument, AFAICT it makes no difference in interactive
> usage.

Yes, it is always non-nil interactively: `prefix-numeric-value'
never returns nil.

> Does documenting the above clarify the issue?

Yes, I think so.  Thx.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-06 16:54         ` bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad Drew Adams
@ 2015-12-07 16:23           ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2015-12-07 16:23 UTC (permalink / raw)
  To: Drew Adams; +Cc: 21315-done, juri

> Date: Sun, 6 Dec 2015 08:54:44 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: juri@linkov.net, 21315@debbugs.gnu.org
> 
> > say this:
> >   The optional argument REGION non-nil means to ignore BEG and END and
> >   copy the region instead.
> 
> Yes.
> 
> (But I think we usually phrase that as: "Non-nil optional argument
> REGION means...".)
> 
> > Also, we should tell that this distinction is only relevant to
> > invoking these functions from Lisp programs, not interactively.
> 
> Yes.
> 
>   From Lisp, non-nil optional argument REGION means...
> 
> > As for the argument, AFAICT it makes no difference in interactive
> > usage.
> 
> Yes, it is always non-nil interactively: `prefix-numeric-value'
> never returns nil.
> 
> > Does documenting the above clarify the issue?
> 
> Yes, I think so.  Thx.

Thanks, I made all the changes.  I also added a reference to
filter-buffer-substring in these doc strings, something that should
have been done almost 11 years ago.  The ELisp manual is also updated.






^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
  2015-12-06 16:15     ` Eli Zaretskii
@ 2015-12-08  0:49       ` Juri Linkov
  0 siblings, 0 replies; 9+ messages in thread
From: Juri Linkov @ 2015-12-08  0:49 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 21315

>> > At least make clear that what is said about REGION is only
>> > for calls from Lisp.  REGION is always non-nil when used
>> > interactively.
>>
>> Maybe REGION should be non-nil only when used on a non-contiguous
>> (rectangular) region?
>
> How do you see that?

I thought this arg should have the same meaning as in other rectangular
commands, but let's discuss this on the corresponding subject in emacs-devel.





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2015-12-08  0:49 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <<fc2203ff-88da-4b92-a049-1606ef40d38c@default>
     [not found] ` <<0fc80688-9028-4715-b2d9-a4bce4439a3b@default>
     [not found]   ` <<87y4d8cwwv.fsf@mail.linkov.net>
     [not found]     ` <<c9793b16-b42f-4094-8292-70682c50a22b@default>
     [not found]       ` <<83si3feepi.fsf@gnu.org>
2015-12-06 16:54         ` bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad Drew Adams
2015-12-07 16:23           ` Eli Zaretskii
2015-08-21 17:17 Drew Adams
2015-12-04 18:06 ` Drew Adams
2015-12-05 23:12   ` Juri Linkov
2015-12-06  2:13     ` Drew Adams
2015-12-06 16:15       ` Eli Zaretskii
2015-12-06 16:15     ` Eli Zaretskii
2015-12-08  0:49       ` Juri Linkov

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).