r-lib/downlit

store Rd elements as data-attributes for later use in tooltips (progressive enhancement)?

maelle opened this issue · 8 comments

I.e. from usethis::use_git() produce

[`usethis::use_git()`](https://usethis.r-lib.org/reference/use_git.html "Initialise a git repository")

(Hugo recognizes it :-) ) or the equivalent html <a href='https://usethis.r-lib.org/reference/use_git.html' title='Initialise a git repository'>use_git</a>, depending on context.

The title would be the Rd title, or Package Title, or vignette title, depending on the linked thing.

It works in GitHub issues too:

usethis::use_git()

https://www.freecodecamp.org/forum/t/how-display-title-attribute-on-mobile/278918

Since the title attribute doesn't help on mobile / for people using the keyboard, maybe not a good idea.

Or good to use it if there's then something on the client side like littlefoot.js for footnotes (so putting the title might serve such workflows ). E.g. https://getbootstrap.com/docs/4.0/components/tooltips/

Ok so now I think I am proposing

  • storing a few parts from the Rd as data attributes
  • having a tooltip using those in pkgdown & friends that'd give a "preview of the Rd page".

My arguments

  • the Rd stuff is there so why not store it?
  • often the preview of the Rd page would be enough to remember what the function is?

I made an example for fun: https://codepen.io/maellesalmon/pen/eYJzZpW, using tippy.js which is more flexible than Bootstrap tooltip pluggin. My example perfectly mimicks the styling of the man pages 😼

Hmmmm, storing more data from the Rd file in data attributes seems like a good idea to me (assuming that the front end rendering the HTML would then generate the tooltips as desired). But this will require a considerable re-architecting of the internals of downlit because instead of autolink_url() we need autolink_meta() or similar, and that change needs to be fed through a lot of intermediate functions. So it's not something I'm likely to work on in the foreseeable future, but if someone else is interested, I could certainly provide a few hints as to how I'd expectation the implementation to work.

I am interested, without any promise on when I'd get to it, so hints are welcome.

Basically every function starting with href_ needs to be touched. You'd first need to come up with a new prefix (maybe meta_?) and then a rough sketch of what the meta object should look like (probably a named list at least containing href). You'd then need to start at the bottom from the functions that find urls (href_topic_local(), href_topic_remote(), etc), editing them to return this list, and figuring out how to retrieve the additional metadata you want. You'd then bubble that up all the way to highlight() and autolink()/ autolink_url() (probably also providing a new autolink_meta()).