bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Drew Adams]

The doc string says this:

  This is an internal function; Lisp code should call `tooltip-show'.

Why?  While it is true that you can get, using `tooltip-show', the
behavior of arg PARMS by binding `tooltip-frame-parameters', the behavior
of args DX and DY by binding `tooltip-x-offset' and `tooltip-y-offset',
and the behavior of arg TIMEOUT by binding `tooltip-hide-delay' (which is
not documented, BTW), you cannot the behavior of arg FRAME.  And binding
user options is not really a great way to control the function behavior,
in general.

So `tooltip-show' is not really a user-level substitute for "internal"
`x-tooltip-show'.

What's more, the doc of `tooltip-show' explicitly refers to how variable
`x-max-tooltip-size' affects the behavior.  Why refer to that "internal"
variable?  And if it is not "internal" then why does it have the prefix
`x-'?  Why isn't there a `tooltip-max-size' option, corresponding to the
other `tooltip-*' options?

It looks like this design/implementation is incomplete.  It is great to
have `tooltip-mode' and `tooltip-show'.  But we should not be telling
users to use only `tooltip-show' and not `x-show-tip'.  I see no reason
for that.  The two functions are different; that's all.  Neither should
be considered more "internal" than the other.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The doc string says this:
>
>   This is an internal function; Lisp code should call `tooltip-show'.
>
> Why?  While it is true that you can get, using `tooltip-show', the
> behavior of arg PARMS by binding `tooltip-frame-parameters', the behavior
> of args DX and DY by binding `tooltip-x-offset' and `tooltip-y-offset',
> and the behavior of arg TIMEOUT by binding `tooltip-hide-delay' (which is
> not documented, BTW), you cannot the behavior of arg FRAME.  And binding
> user options is not really a great way to control the function behavior,
> in general.

I agree that the calling conventions for `x-show-tip' seems to be much
nicer than `tooltip-show'.  

> So `tooltip-show' is not really a user-level substitute for "internal"
> `x-tooltip-show'.
>
> What's more, the doc of `tooltip-show' explicitly refers to how variable
> `x-max-tooltip-size' affects the behavior.  Why refer to that "internal"
> variable?  And if it is not "internal" then why does it have the prefix
> `x-'?  Why isn't there a `tooltip-max-size' option, corresponding to the
> other `tooltip-*' options?

The commit that added the line about it being internal just says "doc
fix", so I can only guess what the reason behind it was: Perhaps we're
trying to get away from all `x-' functions and replace them with generic
functions?  But, as you say, then it's odd that we still have
`x-max-tooltip-size'.

So perhaps the way forward here is to make `x-max-tooltip-size' an
obsolete alias for a new variable `tooltip-max-size'?  And add a way to
specify the FRAME parameter somehow...  but the calling convention for
that function is kinda meh.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Fri, 02 Aug 2019 14:28:45 +0200
> Cc: 20164@debbugs.gnu.org
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
> > The doc string says this:
> >
> >   This is an internal function; Lisp code should call `tooltip-show'.
> >
> > Why?  While it is true that you can get, using `tooltip-show', the
> > behavior of arg PARMS by binding `tooltip-frame-parameters', the behavior
> > of args DX and DY by binding `tooltip-x-offset' and `tooltip-y-offset',
> > and the behavior of arg TIMEOUT by binding `tooltip-hide-delay' (which is
> > not documented, BTW), you cannot the behavior of arg FRAME.  And binding
> > user options is not really a great way to control the function behavior,
> > in general.

I wonder when we will stop wasting time and energy on hair-splitting
reports such as this one.  Probably never.  Sigh.

> I agree that the calling conventions for `x-show-tip' seems to be much
> nicer than `tooltip-show'.  

If you do, please explain it to me, because the above arguments don't
convince me, certainly not that x-show-tip's API is "nicer".  Maybe
I'm missing something.

Tooltips are about showing short hints about various elements of the
UI, they are not general-purpose tools for showing arbitrary text in
arbitrary places.  And tooltip-show looks entirely reasonable and
adequate for the job as defined above.

It could be that someone tried to use tooltips as poor-man's child
frames, but we now have those as first-class objects, so any such
(ab)use would be unnecessary.

> > So `tooltip-show' is not really a user-level substitute for "internal"
> > `x-tooltip-show'.
> >
> > What's more, the doc of `tooltip-show' explicitly refers to how variable
> > `x-max-tooltip-size' affects the behavior.  Why refer to that "internal"
> > variable?  And if it is not "internal" then why does it have the prefix
> > `x-'?  Why isn't there a `tooltip-max-size' option, corresponding to the
> > other `tooltip-*' options?

I don't remember why I added a reference to that variable when I
extended the doc string of tooltip-show in 2001(!), but I hope no one
will argue that it's important to know the displayed text might be
truncated.

> The commit that added the line about it being internal just says "doc
> fix",

Guilty as charged ;-)

> so I can only guess what the reason behind it was

No need for guessing; see the short discussion starting at

  https://lists.gnu.org/archive/html/emacs-pretest-bug/2007-03/msg00261.html

The conclusion to take out of that discussion is that whoever uses
x-show-tip should know very well what they are doing, which is another
way of saying "kids, don't try that at home", a.k.a. "an internal
function".

> So perhaps the way forward here is to make `x-max-tooltip-size' an
> obsolete alias for a new variable `tooltip-max-size'?  And add a way to
> specify the FRAME parameter somehow...  but the calling convention for
> that function is kinda meh.

Before we do something like that, I'd like someone to explain why
would they need to call x-show-tip for showing a tooltip.

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> I agree that the calling conventions for `x-show-tip' seems to be much
>> nicer than `tooltip-show'.  
>
> If you do, please explain it to me, because the above arguments don't
> convince me, certainly not that x-show-tip's API is "nicer".  Maybe
> I'm missing something.

I think explicit parameters to a function is almost always to be
preferred to binding variables and then calling a function that takes no
parameters.  In this case, you're supposed bind `tooltip-{x,y}-offset'
according to the doc string.

> No need for guessing; see the short discussion starting at
>
>   https://lists.gnu.org/archive/html/emacs-pretest-bug/2007-03/msg00261.html
>
> The conclusion to take out of that discussion is that whoever uses
> x-show-tip should know very well what they are doing, which is another
> way of saying "kids, don't try that at home", a.k.a. "an internal
> function".

Makes sense to me, and I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: drew.adams@oracle.com,  20164@debbugs.gnu.org
> Date: Fri, 02 Aug 2019 20:03:54 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> I agree that the calling conventions for `x-show-tip' seems to be much
> >> nicer than `tooltip-show'.  
> >
> > If you do, please explain it to me, because the above arguments don't
> > convince me, certainly not that x-show-tip's API is "nicer".  Maybe
> > I'm missing something.
> 
> I think explicit parameters to a function is almost always to be
> preferred to binding variables and then calling a function that takes no
> parameters.  In this case, you're supposed bind `tooltip-{x,y}-offset'
> according to the doc string.

Only if you for some reason don't like the defaults.  Which should
happen rarely, if ever.

> >   https://lists.gnu.org/archive/html/emacs-pretest-bug/2007-03/msg00261.html
> >
> > The conclusion to take out of that discussion is that whoever uses
> > x-show-tip should know very well what they are doing, which is another
> > way of saying "kids, don't try that at home", a.k.a. "an internal
> > function".
> 
> Makes sense to me, and I'm closing this bug report.

Thanks.

bug#20164: 25.0.50; Do not tell users that `x-show-tip' is internal

[Drew Adams]

> So perhaps the way forward here is to make `x-max-tooltip-size' an
> obsolete alias for a new variable `tooltip-max-size'?  And add a way to
> specify the FRAME parameter somehow...  but the calling convention for
> that function is kinda meh.

I guess you're asking others.  If you're also
asking me then my answer is in the bug report.
To be specific:

1. Yes, rename `x-max-tooltip-size' as you suggest.
2. Don't make `x-show-tip' internal or tell users
   it's internal.
3. Don't point users of `x-show-tip' to
   `tooltip-show'.  That's not at all the same
   thing.  Just rehabilitate `x-show-tip'.
4. If you want to rename all of the `x-*' stuff
   to remove that prefix, fine by me (assuming
   `x-*' aliases for backward compatibility).