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

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

Thanks for taking a look at this.

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

"At the click position" there is no string (AFAIK).
There is only buffer text with text properties or
an overlay with text properties.

And there is no "string which was clicked on".
Unless I'm really missing something big - this is
not about clicking some string syntax (e.g. "This
is a doc string.") in code text, is it?

And in any case, there is no such thing (is
there?) as a "string-type text property".
If there is, then which text properties are
"string-type" 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?
> 
> Because nil stands for a buffer, not just for the lack of a string.

So what?  If it stands for a buffer then say so.
Still, doesn't nil just mean that something besides
buffer text (e.g. an image?) - and certainly not a
string (IIUC) was what was clicked?

Do you really think that introducing (and without
explaining/describing) "OBJECT" here helps?  I
don't see how it does.  It didn't help me, in any
case, as one user trying to understand - quite the
contrary: it left me scratching my head, rereading,
scratching, and filing this enhancement request.

> > 2. What text properties are string-type properties?
> 
> Asked and answered.

Where?  I don't see an answer to that, at all.
Which text properties (and apparently overlay
properties as well) are "string-type" - and as
opposed to what other property "types"?  Do you
mean text properties whose _values_ are strings?

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

I don't understand the answer.  OBJECT can be any
Lisp object?  Then why does the doc say it's nil,
a "string-type text property", or a cons?

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

I see nothing above about this.

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

So OBJECT means an "object on display"?  Not any
Lisp object?  Not nil or a cons or a string-type
text property?  That doesn't seem to jibe with
your other description.  Or are these two
different uses of "object"?

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

Yes, I know.  The wording is weird.  Why not say
"if POSITION comes from clicking buffer text" or
similar?

POSITION is a Lisp value.  It's not "on buffer
text", IIUC.

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

Oh, did you modify the text?  Thank you for doing
that.  What is the new text?

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

"Either of the formats" does mean that (two).  As
a determiner or pronoun, "either" means one or the
other of two people or things.  Maybe you meant to
say "in one of the formats" or "in any of the
formats".  (As a conjunction it is occasionally
used with more than two things.)

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

OK. I hope your new text makes clear what each of
these "objects" is.

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

Without looking, I'm sure you improved it.  In case
I want to look, where can I find that (URL)?  Thx.