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