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.