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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 20164 in the body.
You can then email your comments to 20164 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; Do not tell users that `x-show-tip' is internal
Date: Sun, 22 Mar 2015 09:40:22 -0700 (PDT)

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 <at> gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

Message #8 received at 20164 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 20164 <at> debbugs.gnu.org
Subject: Re: bug#20164: 25.0.50; Do not tell users that `x-show-tip' is
 internal
Date: Fri, 02 Aug 2019 14:28:45 +0200

Drew Adams <drew.adams <at> 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

Message #11 received at 20164 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 20164 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#20164: 25.0.50;
 Do not tell users that `x-show-tip' is internal
Date: Fri, 02 Aug 2019 17:20:53 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Fri, 02 Aug 2019 14:28:45 +0200
> Cc: 20164 <at> debbugs.gnu.org
> 
> Drew Adams <drew.adams <at> 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.

Message #14 received at 20164 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 20164 <at> debbugs.gnu.org
Subject: RE: bug#20164: 25.0.50; Do not tell users that `x-show-tip' is
 internal
Date: Fri, 2 Aug 2019 08:38:41 -0700 (PDT)

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

Message #17 received at 20164 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 20164 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#20164: 25.0.50; Do not tell users that `x-show-tip' is
 internal
Date: Fri, 02 Aug 2019 20:03:54 +0200

Eli Zaretskii <eliz <at> 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

Message #24 received at 20164 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 20164 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#20164: 25.0.50; Do not tell users that `x-show-tip' is
 internal
Date: Fri, 02 Aug 2019 21:57:39 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: drew.adams <at> oracle.com,  20164 <at> debbugs.gnu.org
> Date: Fri, 02 Aug 2019 20:03:54 +0200
> 
> Eli Zaretskii <eliz <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.