[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad
From: |
Drew Adams |
Subject: |
bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad |
Date: |
Fri, 21 Aug 2015 10:17:56 -0700 (PDT) |
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'
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- bug#21315: 25.0.50; doc of `kill-ring-save', `copy-region-as-kill' - bad,
Drew Adams <=