GNU bug report logs - #2738
Content-free doc string: `handle-shift-selection'.

Previous Next

Full log

View this message in rfc822 format

From: Alan Mackenzie <acm <at> muc.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 2738 <at> debbugs.gnu.org
Subject: bug#2738: Content-free doc string: `handle-shift-selection'.
Date: Sun, 22 Mar 2009 22:59:15 +0000

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 <at> 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).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.