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 data[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

[jvns]

Here's an updated version with tooltips that work better, and fixing most of the other issues. You can see it in action here: https://jvns.github.io/git-scm.com/docs/git-checkout/fr

I decided to truncate the glossary entry (similar to how the Wikipedia tooltips work) because I felt like it was getting unwieldy.

Some things that I still need to fix:

1. the links in the tooltips are all broken
2. if you try to move your cursor inside the tooltip, sometimes it disappears before can do that
3. I think there should be a short delay before showing the popup when you hover
4. the "open link" icon is in the wrong place
5. I haven't tested it on mobile at all
6. I think the terms should also be regular elements

[dscho]

Awesome!

[dscho]

@To1ne any objection against merging this in its current state?

[jvns]

I think I've fixed most of the issues except for "I haven't tested it on mobile" and "maybe the term you hover over should be a link". I'm still waiting for CI to run to rebuild the man pages again.

[jvns]

After some missteps, I got the CI to work! You can see it here: https://jvns.github.io/git-scm.com/docs/git-checkout

remaining issues:

• I have now tested it in mobile Safari and it does not work. Haven't figured out how to unbreak it yet. I haven't tested it on other mobile browsers.
• In development, the links inside the tooltips have the wrong destination, because there's a different base URL. I think it will be fine in the production site though.

[To1ne]

• I have now tested it in mobile Safari and it does not work. Haven't figured out how to unbreak it yet. I haven't tested it on other mobile browsers.

@jvns I have no idea what we expect to happen on mobile, hover isn't a thing on touchscreens, is it? So I think that's fine (for now)

• In development, the links inside the tooltips have the wrong destination, because there's a different base URL. I think it will be fine in the production site though.

Didn't test it locally, but doesn't sound like a blocker to me.

A few other comments from my side:

• external-link.svg does not seem to be used no more
• When the text in the tooltip is truncated, can we add a "Read more" at the end? I think this is better for usability (I have no prove, but it's not really obvious otherwise to see the text is cut off)
• Thought/question: I see this change makes the user load a 13kb json. The html for git-checkout is about the same size. I wonder whether it's worth to preload the full glossary all the time.
• I did not review the code, but I scrolled through and "looks good to me"
• Nanopop.js seems to be small, and MIT licensed, so no objections to that.

@dscho Overall there don't seem to be any blockers for me, so I can agree merging this version. Unless @jvns wants to address some of these comments first?

[To1ne]

How does one approve in GitHub??

[To1ne]

And people say GitLab is confusing?

[dscho]

what [do] we expect to happen on mobile, hover isn't a thing on touchscreens, is it?

I intuitively tapped on the term, and it had worked in a previous iteration.

In development, the links inside the tooltips have the wrong destination, because there's a different base URL. I think it will be fine in the production site though.

I faced similar problems with the search, and used the baseURLPrefix() hack to accommodate, maybe something similar might work here, too?

const baseURLPrefix = (() => {
  const thisScriptSrc =
    Array.from(document.getElementsByTagName('script'))
      .pop()
      .getAttribute('src');
  return thisScriptSrc
    .replace(/^(?:[a-z]*:\/\/[^/]*)?(.*\/)(assets|js)\/[^/]+.js(\?.*)?$/, '$1');
})();

 I see this change makes the user load a 13kb json.

Given that it will be cached locally, this seems okay to me. Besides, it is loaded in the background, right?

[jvns]

I removed the unused external-link.svg, but I don't think I'll have time to address the other issues for a little bit. I don't think that the .json files are cached.

[To1ne]

I removed the unused external-link.svg, but I don't think I'll have time to address the other issues for a little bit. I don't think that the .json files are cached.

Good enough for me.