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

[Drew Adams]

> You've omitted the facts you've found, for some reason.  That's a
> bad idea: since no one really knows about these limitations,

Someone who understands the code (C code, IIUC) can discover them.

> if you want to raise the chances that this bug report will be acted
> upon, I urge you to describe everything you tried and found not to
> work, so that whoever takes upon this task will have the "bread-crumbs"
> to go by.  Otherwise, researching this issue from scratch is an
> unpleasant task that is unlikely to find its volunteer.  Thanks.

I'll try.  But I don't have many such "facts".  Someone familiar with
the code would need to specify what is and is not possible for users
to do. I would hope that some of the limitations would be removed,
but any limitations should be documented.

I mention here some superficial tests I tried, in case it helps.

> > 1. If you create a tooltip using, say, `x-show-tip', you can
> > control the font, text color and size, background color, etc.
> > Well, only some frame parameters seem to have any effect, when
> > passed in argument PARMS.  Just which parameters can or cannot be
> > used for PARMS should be documented.

(defun foo (&optional height)
  (interactive (list (and current-prefix-arg
                          (prefix-numeric-value current-prefix-arg))))
  (unless height (setq height  1))
  (x-show-tip (propertize (string (char-after))
                          'face `(:foreground "red"
                                  :height ,(* 200 height)))))

Other face parameters (e.g. :font) do not seem to be reflected.

Likewise frame parameters (arg PARMS).  I also tried binding
`tooltip-frame-parameters' in such a function, but couldn't get that to
change the tooltip frame parameters either.

I also tried customizing face `tooltip', but that seems to have no
effect for `x-show-tip' or for `help-echo' tooltips for `tooltip-mode'.
Perhaps that is normal for MS Windows, but I don't see any doc about it.

> > 2. The word `tooltip' is hardly mentioned in the doc.  Another doc
> > fix would be to document `tooltip-mode' properly in the Elisp manual,
> > saying which frame parameters you can use for `tooltip-frame-parameters',
> > etc.

The only "facts" here are from searching the Emacs and Elisp manuals.
The Emacs manual has node `Tooltips', and there are other places where
"tooltip" is mentioned, but they essentially refer to node `Tooltips'.

The Elisp manual, which is really what I care about in this context,
has a few occurrences of "tooltip", which say that tooltip frames do
not count for this or that operation.  E.g. `Deleting Frames' says
"Unless FRAME is a tooltip...".

Node `Special Properties' mentions the word in passing, and sends you
to the Emacs manual, node `Tooltips'.  IOW, nothing technical about
tooltips here - just mention of what a tooltip is.  Other occurrences
of the term in the Elisp manual do not add anything in this regard.

> > 3. A related bug in `tooltip.el' is that the defcustom for
> > `tooltip-frame-parameters' has no :type.  Impossible for a user to
> > customize the value properly using Customize.  And no help about
> > which parameters can be used effectively (see #2, above).

That fact is expressed clearly enough, no?

> > 4. `help-echo': No doc saying whether the string can be
> > propertized, and if so, which properties have any effect.

That fact is expressed clearly enough, no?

> > 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',

Do you need an example of using `display' with `help-echo'?  I use
a sexp like this for `help-echo' in dired+.el, to show a thumbnail
preview of an image file on mouseover:

(propertize " " 'display (create-image file))

> > apparently you cannot change the face attributes of the `help-echo'
> > string so that the appearance changes.  This is quite a limitation,
> > AFAICT.

(defun foo ()
  (interactive)
  (add-text-properties
   (line-beginning-position) (+ 20 (line-beginning-position))
   `(mouse-face underline help-echo
                ,(propertize (word-at-point)
                             'face '(:foreground "red" :height 200)))))

The tooltip does not reflect what `propertize' should do here.

> > All of this kind of thing should be documented: what you can and
> > cannot do - which parameters have an effect.  You can make
> > `help-echo' show an image instead of text,

See above.

> > but you cannot simply change the text appearance of a `help-echo'
> > string?  How are users supposed to guess what is possible?
> > Should be documented.

HTH.  I don't really know what is allowed and what is not - or why.