Clarify docs for HoverTool

[timsnyder]

I recently read http://bokeh.pydata.org/en/0.12.4/docs/user_guide/tools.html#hovertool looking for the hline or vline behavior. I was thrown off by the first sentence:

The hover tool pops up a tooltip div whenever the cursor is over a glyph.

Reading down the page further to http://bokeh.pydata.org/en/0.12.4/docs/user_guide/tools.html#hover-tool my confusion was reinforced by:

The hover tool displays informational tooltips whenever the cursor is directly over a glyph.

The words "cursor is directly over" led me to believe that I wasn't remembering things correctly. So, I bugged Brian in the gitter:

A little tweaking of the HoverTool user-guide text would have kept me reading and eventually gotten me into the refguide where I would have seen hline and vline.

The limitations of hline and vline should be documented in the refguide as well.

Items:

• make link into refguide more prominently featured. This may be as simple as having 'Reference' included in the link text. When I saw the 'HoverTool' link, I didn't bother to click it because I thought it might just be a self reference to the user-guide.
• allude to the possibility of hline and vline in user-guide without being a full repeat of all the detial in the refguide
• clarify limitations of hline and vline in the refguide
• document the use of '~' in TOOLTIPS as in hover_span.py example. It seems needed for spanning hover modes.
• update the 'Warning' block in HoverTool Reference to accurately reflect the glifs that are supported.

[timsnyder]

I'm planning to submit a PR for this before the 0.12.5 release. Feel free to assign this to me.

[bryevdv]

@timsnyder @mattpap What does "$~x" do? I can't find anything in the BokehJS code that would explain it or what it does. Is it specific to bokeh.charts somehow? FYI I am going to update the docs along with #6183 and close this issue along with it.

[matthieucan]

@bryevdv $~x, in the context of a line and with mode=hline, will return the value of x "on the line", that is where the tooltip appears, instead of the value of x in the plot (under the mouse). I don't know what it does in other contexts.

[bryevdv]

@matthieucan Interesting, tho ultimately whatever $~x does in any context, it's entirely unintentional/accidental. It's not anything we intend to support, so not relevant in terms of documentation

[matthieucan]

@bryevdv Oh? Well, that's an accidental feature then, as having the value as projected on the line instead of under the mouse is exactly what I was looking for. I hope this hack stays in place! :)