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

[Alan Mackenzie]

Hi, Emacs!

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.

In detail:

    Check for shift translation,

"Check for"??  This means possibly, "According to whether or not shift
translation is enabled".  Maybe

What is "shift translation"?  Is this something which might be
getting done somewhere in the raw processing of key strokes?  Or does it
mean "Check to see if the shift key is currently depressed"?  OK, I,
personally, have a vague idea it's to do with moving point whilst holding
down the shift key, but that's far from obvious from the doc string.

    and operate on the mark accordingly.

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.

    This is called whenever a command with a `^' character in its
    `interactive' spec is invoked while `shift-select-mode' is
    non-nil.

Great.  So I know one of the occasions on which `handle-shift-selection'
is called, but not what it does.  Does this mean that somebody can foul
up my mark (explicitly a USER feature), by programming a "^" in her doc
string?

    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?

    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?

What is the semantic significance of "without" here?  What business has
some random command got setting my mark without my permission, or
"deactivating" it?

    With optional arg DEACTIVATE, only perform region deactivation.

Er, excuse me, but I'm an Emacs power user, I have a region from the very
moment I first set the mark in a buffer.  What does this all mean?

OK, I, personally, do have a some idea of what's meant, but why on earth
is this sort of functionality being inserted into the interactive string?
When getting arguments from the user, what does "^" at the beginning of
the string instruct the command loop to do?

-- 
Alan Mackenzie (Nuremberg, Germany).