bug#30516: 26.0; `C-h k' for mouse click is now confusing and less useful

[Drew Adams <drew.adams@oracle.com>]

> > A change for the worse seems to have been made to the help displayed
> > by `C-h k' for a mouse click.
> >
> > Instead of clearly showing two separate help sections, one for the up
> > event and one for the down event, what you see now is help for the up
> > event followed immediately - with no separation, by this sentence:
> >
> >   For documentation of the corresponding mouse down
> >   event <down-mouse-1>, click and hold the mouse button
> >   longer than 0.5 second(s).
> 
> If I `C-h k mouse-1', I get the contents below, so I'm unable to
> reproduce this.  Are you still seeing this on the trunk, or do you have
> a different recipe for how to reproduce it?

Still seeing it, `emacs -Q`, Emacs 26.2.

Please reread the bug report carefully.  It describes
perfectly what I (still) see.

---

What you report corresponds instead to what happens
if you do what it says in that somewhat puzzling
final paragraph, quoted in the bug report:

 For documentation of the corresponding mouse down event <down-mouse-1>,
 click and hold the mouse button longer than 0.5 second(s).

An ordinary `mouse-1' _click_ does NOT produce the
output you describe.  To get that, you need to
_press_ `mouse-1', _hold_ it pressed more than half
a second, and then release it.

The help I described is what you get when you click
`mouse-1'.  And it does NOT describe the _click_.
It describes only the last event of the click.

I imagine that someone intentionally implemented
this help "improvement", and that you will thus say
that it is behaving as designed.

The bug report is to say that, whether by design or
accident, the behavior is worse, not better, now.
For users, that is.  IMHO.

If some real problem (e.g. a bug) existed that
provoked this change, are you sure that it was
worse than the new behavior?  What was that
problem, if there was one?  Was it new, or had it
always been with us over the decades?

In any case, this bug report counts one user as
not appreciating the new behavior.  Do with it
what you will.

But it's hard to understand that you could not
repeat the reported behavior.  Just click.
Normally.

> <down-mouse-1> at that spot runs the command mouse-drag-region (found
> in global-map), which is an interactive compiled Lisp function in
> ‘mouse.el’.
> 
> It is bound to <down-mouse-1>.
> 
> (mouse-drag-region START-EVENT)
> 
> Set the region to the text that the mouse is dragged over.
> Highlight the drag area as you move the mouse.
> This must be bound to a button-down mouse event.
> In Transient Mark mode, the highlighting remains as long as the mark
> remains active.  Otherwise, it remains until the next input event.
> 
> When the region already exists and ‘mouse-drag-and-drop-region’
> is non-nil, this moves the entire region of text to where mouse
> is dragged over to.
> 

You skipped this line, which occurs after
that text and before the next text you cite:

  ----------------- up-event ----------------

> <mouse-1> at that spot runs the command mouse-set-point (found in
> global-map), which is an interactive compiled Lisp function in
> ‘mouse.el’.
> 
> It is bound to <mouse-1>.
> 
> (mouse-set-point EVENT &optional PROMOTE-TO-REGION)
> 
>   Probably introduced at or before Emacs version 22.1.

(That last ("Probably...") line is not in the Emacs 26.2
output that I see.  Perhaps it was added afterward.)

> Move point to the position clicked on with the mouse.
> This should be bound to a mouse click event type.
> If PROMOTE-TO-REGION is non-nil and event is a multiple-click, select
> the corresponding element around point, with the resulting position of
> point determined by ‘mouse-select-region-move-to-beginning’.