Show the glossary definition when a user hovers over some Git jargon

[jvns]

I was thinking about how Git has a lot of jargon (tree-ish, pathspec, refspec, commit-ish, reset, index, etc) which even very experienced Git users often aren't familiar with, and how Git has a glossary where (at least in theory) a lot of the jargon is defined, but that glossary isn't very discoverable. It seems like there's a design intention with the man pages where if there's some text inside angle brackets (like <tree-ish>, then you're supposed to be able to look up that text in the glossary. What if looking it up as simple as just hovering over the term?

So I hacked together a way to show the glossary entry for a piece of jargon when someone hovers over it with their mouse. You can see it in action here: https://jvns.github.io/git-scm.com/docs/git-checkout

If folks thinks this seems like an interesting idea, I can work on resolving some of the issues with the current hacked-together approach, like:

• no localization
• I don't think modifying the DOM on page load is the right approach, it just seemed like the easiest way to get something working
• it only supports jargon terms inside <angle brackets>, like <tree-ish>. It would be nice to be able to mark things outside of angle brackets as jargon, but I'm not sure how to accomplish that yet
• All of the links inside the popup are broken
• it's impossible to scroll the glossary entry popup because it disappears when you move the mouse
• like with the TOC change I'm really working beyond the limits of my design skills, so the design needs work
• Not integrated with CI

Here's a screenshot:

[dscho]

Wow, what a lovely feature!

Just a couple of improvements I would like to suggest:

• When hovering over a term that is scrolled too low on the page, the glossary is not shown, which is partially good because it would be displayed on top of the text. Maybe there could be a visual indicator that the glossary is hidden in such a case? Or it could be displayed on the top of the page?
• Nice touch that it works on mobile devices, too, by tapping on the term! I did notice that tapping on the same term twice keeps the glossary open; It seems to me that the convention is to hide such popups on second tap, though, maybe we should do that here, too?

That's pretty much all I could possibly contribute to make this PR even better. What an impressive feature, I really like it!

[dscho]

You probably wanted to use date[this.currentLang] here?

As to how to handle other languages, this is what I used for the multilingual search (to support searching through, say, the French pages when looking at a French manual page):

git-scm.com/assets/js/application.js

Line 247 in c239214

const language = document.querySelector("html")?.getAttribute("lang");

[To1ne]

Fancy!

[jvns]

Awesome! I'm going to experiment with a few different designs, I did some research on what other projects do and came up with some options. I think I'll fix the "When hovering over a term that is scrolled too low on the page.." issue by changing the design so that the tooltip is closer to the cursor, like in all of these references.

• Kubernetes
• Jetbrains
• sphinx-xref
• Wikipedia