bug#36232: 26.2; (elisp) `Click Events': OBJECT "string-type text property" etc.

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

No clue what is meant by "string-type text property".

Which text properties are string-type text properties?

OBJECT is apparently either nil or (STRING . STRING-POS), where STRING
is the string clicked on and STRING-POS is the position in the string
where clicked.

But:

1. Why call that OBJECT instead of, say, STRING-INFO?  What kind of
   object is it?  If the value is nil doesn't it just mean that a string
   was not clicked on?

2. What text properties are string-type properties?

This doc would likely be clearer if something were said about what kind
of "objects" it tries to talk about, in general (assuming that all of
the occurrences of "object" mean the same kind of thing).  That's just a
guess, as I have no good idea what it is trying to say.

This apparently affects also `posn-object' (e.g. in (elisp `Accessing
Mouse').  There it talks about a string or an image in a POSITION.  Does
"object" just mean string or image?  How can a string be in a position?

And the doc string of `posn-object' talks about "the object of
POSITION."  Again, unclear what that object is.

`posn-object-x-y' is described as coordinates relative to a corner of
"the object in POSITION" - what kind of cornered object is this, and
what/where are its "corners"?  And "if the POSITION is on buffer text"
(huh? a position on text?) then it returns "the relative position of the
... character closest to that position."  Unintelligible to me.  There
must be a clear way of saying what this is trying to say, whatever that
is.

Also there, `posnp' says that its arg (OBJECT) is a position list "in
either of the formats documented in Click Events..."  What are those two
formats?  I don't see two position-list formats identified as such in
that node.  Unclear, to me.

Ostensibly it's about the POSITION (a list) you get from clicking either
an image or some buffer text (but string? what string?).  Why, and what,
objects are introduced to describe the list is unclear to me.

Going to the parent node, `Input Events', OBJECT is an input event or
event type.  Is that the same kind of object the other nodes are talking
about?  How so?  Trying to plug in "input event or event type" to the
various occurrences of "object" doesn't seem to make sense in most
cases.

If this all makes perfect sense to its author, fine.  Consider it the
feedback of this user that the description is not understandable - hope
the feedback helps somehow.



In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''