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