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

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

[Drew Adams]

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

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.

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

[Drew Adams]

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.

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

[Eli Zaretskii]

> Date: Sun, 16 Jun 2019 09:43:23 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 36232-done@debbugs.gnu.org
> 
> > > 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".

When the text or overlay properties specify a string to display, that
string is displayed instead of, or in addition to, buffer text.  And
then you definitely CAN click on some character from such a string on
display.

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

No.

> And in any case, there is no such thing (is
> there?) as a "string-type text property".

There is such a thing, but since you were confused, I replaced that
text with something more specific.

> If there is, then which text properties are
> "string-type" properties?

What I said above.

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

The new text does.

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

No, it means buffer text.

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

I'm sorry it didn't help you, but I want at least to make sure it
doesn't get in your way.  I can certainly envision readers who would
be helped by that (I'm one of them, btw).

> > > 2. What text properties are string-type properties?
> > 
> > Asked and answered.
> 
> Where?  I don't see an answer to that, at all.

In my message, see above.

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

Among others, yes.  One example is the 'display' property whose value
is a string, a.k.a. "display string".  Another example is the
'before-string' overlay property.

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

Because those are the types that we currently put there.  Having a
Lisp object there will allow us to put other objects in the future, if
needed.

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

Once again, I explained what OBJECT can be.

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

No, it means an object that caused something to be displayed.  That
something then has corners.

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

See the new text, you might even like it.

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

That's why the new text says something more clearly and less vaguely.

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

See here:

  http://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-26&id=4701e0663ee53f1c4b1e1e4c5fee9e597671800b

(Is it possible to agree with you that you look in the repository
before following up to your reports?)

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

Not to me, but that's a moot point, because that text is now gone.

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

I invite you to look.

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

In the repository, as usual; see above.  I suggest to bookmark the
cgit URL, because these questions pop up all the time, and the answer
is always the same.

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

[Drew Adams]

> > > > 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".
> 
> When the text or overlay properties specify a string to display, that
> string is displayed instead of, or in addition to, buffer text.  And
> then you definitely CAN click on some character from such a string on
> display.

Is that really what this is all about?  I guess you're
talking about a "replacement" `display' property value
that's a string.

(You're still not clicking a string.  You're clicking
the displayed text of the string.  This is not to be
pedantic; it's to say that the text quoted is unclear
to confusing.)

> > And in any case, there is no such thing (is
> > there?) as a "string-type text property".
> 
> There is such a thing, but since you were confused, I replaced that
> text with something more specific.

Thanks.  I'd still like to know what you are
calling a "string-type property".  From above,
are you talking about property `display'?

> > If there is, then which text properties are
> > "string-type" properties?
> 
> What I said above.

It isn't very clear/explicit.  Are you just
talking about property `display'?  If not, what?

> > > > 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.
> 
> The new text does.

Good; thanks.

> > 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?
> 
> No, it means buffer text.

Not if it means clicking what property `display'
shows.  That's not buffer text (chars in the buffer).

> > 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.
> 
> I'm sorry it didn't help you, but I want at least to make sure it
> doesn't get in your way.  I can certainly envision readers who would
> be helped by that (I'm one of them, btw).

It might really help, including me, but only,
I think, if it says what it means by "object".

> > 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?
> 
> Among others, yes.  One example is the 'display' property whose value
> is a string, a.k.a. "display string".  Another example is the
> 'before-string' overlay property.

OK, now it's becoming more clear.  I don't think
you should assume that that will be understood by
just referring to "string-type" properties.

Overlay properties are not text properties.  The
same property can sometimes be used for either,
but here we're talking about what is the "OBJECT".
If it can be (or contain) an overlay property, OR
a text property, whose value is a string, then I'd
suggest that be said, and not suppose that will be
understood by "string-type text property".

> > > > `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"?
> 
> No, it means an object that caused something to be displayed.  That
> something then has corners.

Then the object itself (e.g. string, nil, cons) does
not have corners.  The text should talk about the
displayed thing that the Lisp object caused to be
displayed.

Too many shortcuts, too many assumptions that a
reader will figure out what invisible jumps you're
intending.

> > > > 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?
> 
> See the new text, you might even like it.

As I said, I'm sure it will be an improvement.
Your taking a closer look at the existing text
and trying to make it clearer is all I can or
would ask for.

> > POSITION is a Lisp value.  It's not "on buffer
> > text", IIUC.
> 
> That's why the new text says something more clearly and less vaguely.

Got it; thanks.

> > > > 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?
> 
> See here:
> 
>   http://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-26&id=4701e0663ee53f1c4b1e1e4c5fee9e597671800b

That's a zillion times clearer.  Good.

> (Is it possible to agree with you that you look in the repository
> before following up to your reports?)

I wouldn't know where to look.  And I didn't know
that you had already made the corrections.  And
it's not very easy to reconstruct the text from
the diff, mentally.

Trying to make you aware of what I found unclear
or confusing is the purpose of the bug report.

If/when you can understand my description of what
I find unclear then that's really enough, generally.
I have confidence that you will DTRT.  Of course,
sometimes there can be disagreement, but generally
not when it comes to doc clarity and purpose.

> > "Either of the formats" does mean that (two).
> 
> Not to me, but that's a moot point, because that text is now gone.

OK.  Just FYI:

https://www.dictionary.com/browse/either

https://www.google.com/search?q=either+definition

> In the repository, as usual; see above.  I suggest to bookmark the
> cgit URL, because these questions pop up all the time, and the answer
> is always the same.

See above.  I don't use GIT so I can only see the
individual changes, which are out of context.

Anyway, thanks; I've bookmarked this now:.

http://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-26

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

[Eli Zaretskii]

> Date: Sun, 16 Jun 2019 11:32:24 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 36232@debbugs.gnu.org
> 
> > When the text or overlay properties specify a string to display, that
> > string is displayed instead of, or in addition to, buffer text.  And
> > then you definitely CAN click on some character from such a string on
> > display.
> 
> Is that really what this is all about?  I guess you're
> talking about a "replacement" `display' property value
> that's a string.

Not necessarily "replacing".  For example, the 'before-string' overlay
property doesn't replace any text.

> (You're still not clicking a string.  You're clicking
> the displayed text of the string.  This is not to be
> pedantic; it's to say that the text quoted is unclear
> to confusing.)

You are splitting hair.  "Clicking a string" is as natural as
"clicking buffer text".  (Let's please not make this into another
bikeshedding galore.)

> > There is such a thing, but since you were confused, I replaced that
> > text with something more specific.
> 
> Thanks.  I'd still like to know what you are
> calling a "string-type property".  From above,
> are you talking about property `display'?

It's just one example, as I wrote before.

> > > 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?
> > 
> > No, it means buffer text.
> 
> Not if it means clicking what property `display'
> shows.  That's not buffer text (chars in the buffer).

In that case, you get a string as OBJECT, not nil.

> > Among others, yes.  One example is the 'display' property whose value
> > is a string, a.k.a. "display string".  Another example is the
> > 'before-string' overlay property.
> 
> OK, now it's becoming more clear.  I don't think
> you should assume that that will be understood by
> just referring to "string-type" properties.

Which is why I replaced that text with a more concrete one.

> Overlay properties are not text properties.

I never said they were.

> > > > > `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"?
> > 
> > No, it means an object that caused something to be displayed.  That
> > something then has corners.
> 
> Then the object itself (e.g. string, nil, cons) does
> not have corners.

See above: I said "object on display".

> Too many shortcuts, too many assumptions that a
> reader will figure out what invisible jumps you're
> intending.

There should be fewer of them now.