sphinx-doc
abbr role has confusing delay and unexpected behavior on mouse click
Describe the bug
The abbr role has a slight, about a half-second delay when you hover over an abbreviation. This means that it's extremely intuitive for a user to click on the abbreviation to see if that shows something. What clicking on it does is the opposite of what you would expect: it ensures that the definition does not show up. The only way to get it to show up is to hover, then wait for about half a second. These two behaviors together means that it's common for people to think that this feature does not work at all.
Ideally, the abbreviation would show its definition immediately upon mouseover instead of having a delay, and clicking on it would also show the definition (or at least not prevent it).
How to Reproduce
- Go to: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-abbr
- Hover your mouse over the abbreviation example there for LIFO, then immediately click on it. You'll see that nothing at all happens, no matter how long you wait or how much you click.
- Move your mouse away from it then hover over it again. This time, don't click. You'll see that it takes about a half second before the abbreviation definition shows.
Environment Information
This bug is front-end behavior irrespective of environment.
Sphinx extensions
Additional context
No response
I'm not a sphinx dev, I just came across this issue.
I don't think this is really a Sphinx issue: it just uses the <abbr> HTML element. That, in turn, just uses normal Windows tooltips (at least on Firefox on Windows), which I imagine haven't changed much since they were introduced in Windows 95.
It's worth noting those tags don't do anything useful on mobile, since there's no notion of "hovering your mouse cursor" on touchscreens. Even when they do work, they're a distraction: I normally can't help hovering on one even if I know the abbreviation already, just in case there's unexpected information.
Overall, you're better off just defining the acronym directly in the running text, e.g., "Network ACLs: (access control lists) define rules..."
Maybe the real bug report here is that Sphinx documentation shouldn't mention the abbr directive at all.
+1 on this not beeing a Sphinx issue (but the standard way browsers handle tool tips)
-1 on not mentioning the abbr directive role in the Sphinx documentation. It can be used without the tooltip for semantic markup like
A network :abbr:`ACL` (access control list) defines rules...
There is one problem, though, with using the :abbr: or :ac: role for semantic markup: When writing the expansion in the main text (in parentheses) like in
A network :abbr:`ACL` (access control list) defines rules...
instead of using the tooltip/title argument, the HTML output still underlines the "ACL" and the cursor turns into a question mark when hovering over the abbreviation.