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

[Eli Zaretskii]

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

> In detail:
> 
>     Check for shift translation,
> 
> "Check for"??  This means possibly, "According to whether or not shift
> translation is enabled".  Maybe
> [...]
>     and operate on the mark accordingly.

The author tried to come up with something that would fit on a single
line, for `apropos's sake.  Sometimes the result is not entirely
correct for English grammar purists, but there's no need to become so
sarcastic.  (My modified doc string still sacrifices some of the
grammar correctness for brevity.)

> This is vacuous.  "Operate on" says NOTHING; it is equivalent to "do
> something with".  So this command is going to "do something" with my
> mark.  I'd far rather the doc string told me what.

It does, a few lines below.  Again, the first line of the doc string
can never tell the whole story, because it's a kind of executive
summary.

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

>     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?

> 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".