[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#2738: Content-free doc string: `handle-shift-selection'.
From: |
Alan Mackenzie |
Subject: |
bug#2738: Content-free doc string: `handle-shift-selection'. |
Date: |
Sun, 22 Mar 2009 22:59:15 +0000 |
User-agent: |
Mutt/1.5.9i |
Hi, Eli!
On Sat, Mar 21, 2009 at 08:46:54PM +0200, Eli Zaretskii wrote:
> > Date: Sat, 21 Mar 2009 17:23:43 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc:
> > The doc-string for `handle-shift-selection' is of little or no help in
> > informing the reader what the function does. It is, in fact,
> > infuriatingly useless. This should be fixed.
> I changed it to say this:
> "Activate/deactivate mark depending on invocation thru ``shift
> translation.''
> \(See `this-command-keys-shift-translated' for the meaning of
> shift translation.)
> This is called whenever a command with a `^' character in its
> `interactive' spec is invoked while `shift-select-mode' is
> non-nil.
> If the command was invoked through shift translation, set the
> mark and activate the region temporarily, unless it was already
> set in this way. If the command was invoked without shift
> translation, or if the optional argument DEACTIVATE is non-nil,
> deactivate the mark if the region is temporarily active."
> Is this good enough to close the bug? If not, please tell what still
> needs improvement.
I don't think it is. I'm not sure this function can be documented
coherently. I think it's a bad function. Sorry, I'm not being very
constructive here. I just find the whole thing distasteful in the
extreme, the idea that rather than binding commands to key sequences,
with a clean separation between the interactive commander, the key
sequences and the commands, we've now got a hodge podge where the
command loop now actually performs part of a command's function -
sometimes, depending on the key binding.
In fact, how about just saying something like "this function ensures the
mark is set for a movement command making a CUA region", or something
like that?
In addition this, the function is buggy. It spuriously enables
transient-mark-mode in certain circumstances (I'll be submitting a bug
report soon).
[ .... ]
> > If the command was invoked through shift-translation,
> > "THROUGH" shift-translation. Is "shift-translation" some sort of
> > processing step? Is a translation being shifted here, or is a shift
> > being translated?
> I added a direct link to where shift-translation is explained.
> (Before that, it was reachable only from the doc string of
> `shift-select-mode', i.e. by following one more link.)
Thanks!
> > set the mark and activate the region temporarily, unless it was
> > already set in this way. If the command was invoked without
> > shift-translation and a region is temporarily active, deactivate
> > the mark.
> > This reads like a flowchart, and it's uncomfortably close to
> > gibberish. Is it not possible to state the function's FUNCTION,
> > rather than leaving the reader to figure this out from its
> > quasi-flowchart?
> Is the replacement better?
A bit better, yes.
> > When getting arguments from the user, what does "^" at the beginning of
> > the string instruct the command loop to do?
> This is not about getting arguments, this is about the `interactive'
> spec, as the doc string says. See "(elisp)Interactive Codes".
Does this bit not perhaps need a warning that "^" in an interactive spec
is really intended for Emacs's internal use and will throw an error on
anything but Emacs 23 (or later)?
--
Alan Mackenzie (Nuremberg, Germany).