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

[Eli Zaretskii]

> Date: Sat, 15 Jun 2019 14:21:50 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> No clue what is meant by "string-type text property".
> 
> Which text properties are string-type text properties?

It's a string that comes from a text property or from an overlay.

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

Because nil stands for a buffer, not just for the lack of a string.

> 2. What text properties are string-type properties?

Asked and answered.

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

It can talk about any Lisp object, or I don't understand the question.

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

See above.

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

See above.  "OBJECT in POSITION" refers to the object recorded in (or
described by) POSITION.

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

Every object on display, be it a character glyph, a display string, an
image, or anything else, has 2 dimensions, which means it has 4
corners.

> And "if the POSITION is on buffer text" (huh? a position on text?)

POSITION describes a click, remember?

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

I hope the modified text is more clear.

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

"In the format".  ("Either of the formats" doesn't necessarily mean
there are two of them.)

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

No.

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

I improved the wording (in the emacs-26 branch), you are invited to
take a look.