bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Drew Adams]

> > 3. ... the defcustom for `tooltip-frame-parameters' has no :type...
> 
> I cannot reproduce this one: my tooltip.el has this:

Sorry, my bad.

(Perhaps it was the gratuitous extra blank line after the first
doc-string line that threw me off and made me think the doc string
and definition ended there.  Dunno why such lines are added sometimes.
Those are (minor) bugs, AFAICT.  I don't mean this as an excuse for
my not reading the defcustom more carefully, but it might be the
reason that I was mistaken.)

And I see now that the doc string says that "font and color parameters
are ignored, and the attributes of the `tooltip' face are used instead."
It would be good to add info that to the doc in the manual, IMO.

So yes, there is a :type.  But the :type value should, I think, be
something more like this, not just `sexp':

:type '(alist :key-type   (symbol :tag "Parameter")
              :value-type (sexp :tag "Value"))

The :tag's are not required, but at least the type should be
:alist, I think.  Unless I'm missing something - can it ever be
something besides an alist?

Especially if only some frame parameters are allowed as keys (the
others are ignored, so why allow them for customization?), maybe a
more restrictive type than `symbol' should be used - e.g.
`restricted-sexp' with matching for the allowed symbols.

(You will perhaps argue that we didn't exclude including ignored
parameters before, so this would be an incompatible change.  I can't
really argue against that, except to say that it still might not be
bad to start now, raising an error when you try to add an "ignored"
parameter.)

> > 4. `help-echo': No doc saying whether the string can be
> > propertized, and if so, which properties have any effect.
> > Although `x-show-tip' seems to let you change the char size, color,
> > background color, etc., and you can use property `display' with
> > `help-echo', apparently you cannot change the face attributes of
> > the `help-echo' string so that the appearance
> > changes.  This is quite a limitation, AFAICT.
> 
> See above: the doc string of tooltip-frame-parameters says font and
> color parameters are ignored.

#4 is about `help-echo'.  Search the Elisp manual for `help-echo'.
See node `Special Properties', for instance.  Nowhere does it specify
such limitations, AFAICT.

And font and color parameters are not the only ones ignored.

And see the rest of the bug report, including the part about
`x-show-tip' - which face attributes and which frame parameters
have no effect?  And why is `help-echo' more limited wrt specifying
tooltip appearance than is `x-show-tip'?

There are several things said in the doc or doc strings here and
there about tooltips, but (a) the doc is incomplete and (b) it's not
clear what the relations between the various things are: `help-echo'
string properties, `x-show-tip' frame, `tooltip-frame-parameters'.

Apparently (from experimentation) `x-show-tip' does not bother with
`tooltip-frame-parameters'.

But you seem to be suggesting that a `help-echo' tooltip does, and
that `help-echo' string properties are overridden by
`tooltip-frame-parameters' frame-parameter limitations, and that
all of this should be obvious.  At least that's my guess, based on
your repeating, for #4 (`help-echo'), the info about the doc string
of `tooltip-frame-parameters'.