bug#23341: x-show-tip does not respect the value of tooltip-hide-delay, and the default tooltip timeout isn't configurable

[Drew Adams <drew.adams@oracle.com>]

> But there are external packages calling that function utilizing the
> default meanings of its parameters, and it's also an internal function
> used by `read-file-dialog', so the analogy with `x-show-tip' is
> complete.

FWIW, I don't see why `x-show-tip' is being
considered "internal".  And I'm one who uses it in
external libraries.

If `tooltip-show' can use `x-show-tip' then so
can "external" code that does something similar.

The only even partially good excuse for branding
something "internal" is to let users know not to
depend too heavily on its behavior, as it might
change sometime.  (And that's anyway true of
everything in Emacs.)

`tooltip-show' is not sufficiently general to
serve as a replacement for the use cases of
`x-show-tip'.  Branding the latter "off limits"
is misguided, IMO.

This, in the `x-show-tip' doc string, is misguided:

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

(No reason given, BTW.  Nothing that helps users
understand.  Just a big "VERBOTEN !" sign.)
___

On the other hand, there's nothing wrong with
_documenting_, clearly, any caveats that you
think users of `x-show-tip' should be aware of.

And by "documenting" I don't mean hand-waving
about unspoken, unclear "complications".
___

Even the title of this bug should be a clue
that something is wrong about it: the tail is
wagging the dog.  Why should `x-show-tip'
respect the value of `tooltip-hide-delay'?

It's the other way around: `x-show-tip' does
not, and should not, depend on any `tooltip-*'.
It's `tooltip-*' that depends on its use of
`x-show-tip'.
___

What Martin said in this bug thread is sound:

  A function that calls 'x-show-tip' directly
  should generally use 'tooltip-hide-delay' as
         ^^^^^^^^^
  TIMEOUT argument.  If it doesn't, it should
  provide a customizable variable to use as
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  TIMEOUT argument instead.

That's reasonable.  If you can reasonably use
`tooltip-show' then do so.  If you can't, use
`x-show-tip'.

And in the latter case, if it makes sense to
use `tooltip-hide-delay' as the TIMEOUT arg,
then do so.

If not, then if you can reasonably provide a
user option, to let users specify the TIMEOUT
to use, then do so.

Different uses of showing a tooltip can call
for different behaviors, including different
TIMEOUT values.  For some uses the general
option `tooltip-hide-delay' is appropriate.
For others it's not - instead, you want to
let users specify another timeout value.

Martin also suggested:

  Any package that optionally provides its
  own delay for hiding tips should, by default,
  use the value of 'tooltip-hide-delay' for
  that option.

That too makes sense, _in general_.  But
"should" should be avoided in such guidance,
unless "in general" follows.  The devil is
in the details, i.e., in what the use case is.

None of this is complicated.  None of it is
a reason to call `x-show-tip' off limits.
___

And what Martin said about `x-show-tip' arg
TIMEOUT is also sound for args DX and DY:
use options `tooltip-[xy]-offset', or
provide library-specific options.
___

The bug filer even admitted the following,
in response to Martin's clear advice:

  this isn't a documented convention AFAICS,

That calls out for the _proper_ "fix": Just
add what Martin suggested to the doc.  Don't
make a mountain out of this mole hill.
___

This, I think, is the bottom-line expression
of the bug OP's problem:

  I opened this issue based on the experience
  that it took me some non-trivial amount of
  time to figure out that I had to configure
  flycheck-pos-tip-delay, and not tooltip-delay.

  flycheck-pos-tip follows the convention that
  you outlined above, but that convention wasn't
  obvious to me, and doesn't yield a consistent
  or very nice experience (any time I install a
  package that uses tooltips, I need to wonder
  configure its timeout, unless it uses tooltip
  - which I can't easily guess).

IMO, this just points to a case of either or
both (1) something (`flycheck-pos-tip') not
being well-enough documented or (2) a user not
using `C-m' or otherwise checking what a library
provides before using it.

If Flycheck provides an option for the hide
delay it uses, and if it makes that provision
obvious, then I don't see a Flycheck bug (or
any other bug).

Eli said something similar, I think:

  Bottom line, I think the bug is in the
  packages that don't provide customizations
  for this, and you should take this up with
  the respective maintainers.

(I say "I think", because maybe he meant more
than that, about an option.  Maybe he too
meant to suggest that no library should use
`x-show-tip'.)

If in fact it makes better sense for Flycheck
to _not_ provide its own delay option, and
instead to just use `tooltip-hide-delay', then
change it to do that.  (I have no opinion here.)

But there's no requirement that code that uses
`x-show-tip' use anything `tooltip-*'.  That
would be backward: the tail wagging the dog.

3rd-party code, just as much as `tooltip.el',
can reasonably make use of `x-show-tip'.

The OP's complaint is essentially this:

  I don't want to have to configure every
  package that I use independently.  It's
  good to be able to fine-tune independent
  packages, but consistent defaults are nice
  in any case, aren't they?

And this:

  As a user, I would like to have a way to
  globally configure how long tooltips
  produced by Emacs are displayed.  At the
  moment, Emacs does not provide such a
  default. tooltip-hide-delay is close, but
  it does not cover all tooltips.

It can't - and it shouldn't necessarily -
cover all tooltips, because Emacs cannot
know how some particular library (use case)
might make use of tooltips.  OP's
inconvenience is the cost of not being able
to predict and reasonably cover every use
case.

So the answer is yes, consistency is nice
when it makes sense.  But yes, if it makes
sense for a library to provide its own
settings, such a options, as opposed to just
using a generally/globally "consistent"
setting, then it's up to you as a user to
recognize that fact and act accordingly.

If a library gives you an option to get the
behavior you like as a user, then don't
complain that it's a bother to specify that.
If _you_ think that option should default
to the value of a more general option, then
tell it to the library maintainer.  It's
possible that the maintainer has a good
reason to have provided you with a separate
option.

Or not.  IOW, it's either a problem with
that library or a user problem.  It's not a
problem with `x-show-tip'.  One person's
inconvenience for having to customize more
than just one option is another person's
relief in being able to get behavior, in a
particular context, that differs from what
that general option provides.

As Eli put it:

  to me, such a global value makes very
  little sense, because tooltips can be
  used for many different features that
  don't necessary display short helpful
  text.  Having a single value for all the
  possible use cases is IMO not a good
  customization design, as it can never be
  a "one fits all" value anyway.

And he says this, with which I also agree:

  tooltip-hide-delay has no relation
  whatsoever to x-show-tip.  It is a user
  option supported by functions in tooltip.el,
  as its name says.

No relation, although I also agree with
Martin's suggestion that it can make sense
to use that option in a call to `x-show-tip'
when other things are equal (i.e., when
there's no good reason not to).
___

There were good things said in this thread.
This is not one of them, IMO:

  Reading this thread, there were some good
  arguments for why we shouldn't add such a
  variable -- x-show-tip isn't supposed to
  be called directly, and tooltip.el already
  has a way to tweak this.

Drop the "x-show-tip isn't supposed to be
called directly".  That's misguided.  The
rest is fine.
___

Just one opinion, from one 3rd-party provider,
who sometimes uses `x-show-tip' with
`tooltip-hide-delay' and sometimes uses it
with a delay option designed for use with a
specific library that calls `x-show-tip'.