{"id":3350,"date":"2021-01-24T19:48:57","date_gmt":"2021-01-24T18:48:57","guid":{"rendered":"https:\/\/blog.tomayac.com\/2021\/01\/24\/ruby-html-footnotes\/"},"modified":"2021-01-24T19:48:57","modified_gmt":"2021-01-24T18:48:57","slug":"ruby-html-footnotes","status":"publish","type":"post","link":"https:\/\/tomayac.com\/wordpress\/2021\/01\/24\/ruby-html-footnotes\/","title":{"rendered":"<ruby> HTML footnotes"},"content":{"rendered":"\n\t\t\t

It is sometimes surprising to me to see what kind of use cases HTML has a\ndedicated element for. Something that comes to mind is\n<output><\/code><\/a>,\na container element into which a site or app can inject the results of a\ncalculation or the outcome of a user action. For another use case that is\narguably more common and which is also the topic of this blog post, HTML has\nnothing specific to offer:\nfootnotes<\/strong>Footnotes<\/strong> are notes at the\nfoot of the page while endnotes are collected under a separate heading at the\nend of a chapter, volume, or entire work. Unlike footnotes,\nendnotes<\/strong> have the advantage of not affecting the layout of the\nmain text, but may cause inconvenience to readers who have to move back and\nforth between the main text and the endnotes.<\/rt><\/ruby>.<\/p>\n

Footnotes in HTML, then and now \u2693<\/a><\/h2>\n

Despite several\nproposals<\/a>\nto deal with footnotes at the language level,\nHTML\u00a03.0 Draft<\/a> was the last version of\nHTML that offered the FN<\/code><\/a>\nelement. It was designed for footnotes, and when practical, footnotes were to be\nrendered as pop-up notes. You were supposed to use the element as in the code\nsample below (the inconsistent character casing sic<\/em>).<\/p>\n

<<\/span>DL<\/span>><\/span><\/span>
  <<\/span>DT<\/span>><\/span><\/span>Hamlet:<\/<\/span>DT<\/span>><\/span><\/span>
  <<\/span>DD<\/span>><\/span><\/span>
    You should not have believed me, for virtue cannot so
    <<\/span>a<\/span> href<\/span>=<\/span>\"<\/span>#fn1\"<\/span><\/span>><\/span><\/span>inoculate<\/<\/span>a<\/span>><\/span><\/span> our old stock but we shall
    <<\/span>a<\/span> href<\/span>=<\/span>\"<\/span>#fn2\"<\/span><\/span>><\/span><\/span>relish of it<\/<\/span>a<\/span>><\/span><\/span>. I loved you not.
  <\/<\/span>DD<\/span>><\/span><\/span>

  <<\/span>DT<\/span>><\/span><\/span>Ophelia:<\/<\/span>DT<\/span>><\/span><\/span>
  <<\/span>DD<\/span>><\/span><\/span>I was the more deceived.<\/<\/span>DD<\/span>><\/span><\/span>

  <<\/span>DT<\/span>><\/span><\/span>Hamlet:<\/<\/span>DT<\/span>><\/span><\/span>
  <<\/span>DD<\/span>><\/span><\/span>
    Get thee to a nunnery. Why wouldst thou be a breeder of sinners? I am myself
    <<\/span>a<\/span> href<\/span>=<\/span>\"<\/span>#fn2\"<\/span><\/span>><\/span><\/span>indifferent honest<\/<\/span>a<\/span>><\/span><\/span> ...
  <\/<\/span>DD<\/span>><\/span><\/span>
<\/<\/span>DL<\/span>><\/span><\/span>

<<\/span>fn<\/span> id<\/span>=<\/span>\"<\/span>fn1\"<\/span><\/span>><\/span><\/span><<\/span>i<\/span>><\/span><\/span>inoculate<\/<\/span>i<\/span>><\/span><\/span> - graft<\/<\/span>fn<\/span>><\/span><\/span>
<<\/span>fn<\/span> id<\/span>=<\/span>\"<\/span>fn2\"<\/span><\/span>><\/span><\/span><<\/span>i<\/span>><\/span><\/span>relish of it<\/<\/span>i<\/span>><\/span><\/span> - smack of it (our old sinful nature)<\/<\/span>fn<\/span>><\/span><\/span>
<<\/span>fn<\/span> id<\/span>=<\/span>\"<\/span>fn3\"<\/span><\/span>><\/span><\/span><<\/span>i<\/span>><\/span><\/span>indifferent honest<\/<\/span>i<\/span>><\/span><\/span> - moderately virtuous<\/<\/span>fn<\/span>><\/span><\/span><\/code><\/pre>\n
<<\/span>p<\/span>><\/span><\/span><<\/span>b<\/span>><\/span><\/span>Customer<\/<\/span>b<\/span>><\/span><\/span>: Hello! I wish to register a complaint. Hello. Miss?<\/<\/span>p<\/span>><\/span><\/span>
<<\/span>p<\/span>><\/span><\/span>
  <<\/span>b<\/span>><\/span><\/span>Shopkeeper<\/<\/span>b<\/span>><\/span><\/span>:
  <<\/span>span<\/span> title<\/span>=<\/span>\"<\/span>Colloquial pronunciation of '<\/span>What do you'<\/span>\"<\/span><\/span>><\/span><\/span>Watcha<\/<\/span>span<\/span>><\/span><\/span> mean,
  miss?
<\/<\/span>p<\/span>><\/span><\/span>

<<\/span>p<\/span>><\/span><\/span>
  <<\/span>b<\/span>><\/span><\/span>Customer<\/<\/span>b<\/span>><\/span><\/span>: Uh, I'm sorry, I have a cold. I wish to make a complaint.
<\/<\/span>p<\/span>><\/span><\/span>
<<\/span>p<\/span>><\/span><\/span>
  <<\/span>b<\/span>><\/span><\/span>Shopkeeper<\/<\/span>b<\/span>><\/span><\/span>: Sorry,
  <<\/span>span<\/span> title<\/span>=<\/span>\"<\/span>This is, of course, a lie.\"<\/span><\/span>><\/span><\/span>we're closing for lunch<\/<\/span>span<\/span>><\/span><\/span>.
<\/<\/span>p<\/span>><\/span><\/span><\/code><\/pre>\n
Using title<\/code> comes with an important downside, though, as the spec rightly\nnotes.<\/p>\n
\n
Unfortunately, relying on the title<\/code> attribute is currently discouraged as\nmany user agents do not expose the attribute in an accessible manner as\nrequired by this specification (e.g. requiring a pointing device such as a\nmouse to cause a tooltip to appear, which excludes keyboard-only users and\ntouch-only users, such as anyone with a modern phone or tablet).<\/p>\n<\/blockquote>\n
For longer annotations, the a<\/code> element should be used, pointing to an element\nlater in the document. The convention is that the contents of the link be a\nnumber in square brackets.<\/p>\n
<<\/span>p<\/span>><\/span><\/span>Announcer: Number 16: The <<\/span>i<\/span>><\/span><\/span>hand<\/<\/span>i<\/span>><\/span><\/span>.<\/<\/span>p<\/span>><\/span><\/span>
<<\/span>p<\/span>><\/span><\/span>
  Interviewer: Good evening. I have with me in the studio tonight Mr Norman St
  John Polevaulter, who for the past few years has been contradicting people. Mr
  Polevaulter, why <<\/span>em<\/span>><\/span><\/span>do<\/<\/span>em<\/span>><\/span><\/span> you contradict people?
<\/<\/span>p<\/span>><\/span><\/span>

<<\/span>p<\/span>><\/span><\/span>
  Norman: I don't. <<\/span>sup<\/span>><\/span><\/span><<\/span>a<\/span> href<\/span>=<\/span>\"<\/span>#fn1\"<\/span><\/span> id<\/span>=<\/span>\"<\/span>r1\"<\/span><\/span>><\/span><\/span>[1]<\/<\/span>a<\/span>><\/span><\/span><\/<\/span>sup<\/span>><\/span><\/span>
<\/<\/span>p<\/span>><\/span><\/span>
<<\/span>p<\/span>><\/span><\/span>Interviewer: You told me you did! ...<\/<\/span>p<\/span>><\/span><\/span>

<<\/span>section<\/span>><\/span><\/span>
  <<\/span>p<\/span> id<\/span>=<\/span>\"<\/span>fn1\"<\/span><\/span>><\/span><\/span>
    <<\/span>a<\/span> href<\/span>=<\/span>\"<\/span>#r1\"<\/span><\/span>><\/span><\/span>[1]<\/<\/span>a<\/span>><\/span><\/span> This is, naturally, a lie, but paradoxically if it
    were true he could not say so without contradicting the interviewer and thus
    making it false.
  <\/<\/span>p<\/span>><\/span><\/span>
<\/<\/span>section<\/span>><\/span><\/span><\/code><\/pre>\n
The ruby<\/code> element \u2693<\/a><\/h2>\n
The other day, I came across a\ntweet<\/a> by\nMichael Scharnagl<\/a>, whose website and Twitter handle\nare aptly named Just Markup<\/em> and who runs a Twitter campaign this year called\n#HTMLElementInATweet<\/code><\/a>:<\/p>\n
Day 22: <ruby>

Represents small annotations 

\u2139\ufe0f The term ruby originated as a unit of measurement used by typesetters, representing the smallest size that text can be printed on newsprint while remaining legible. 

developer.mozilla.org\/en-US\/docs\/Web\u2026<\/a> 

#HTMLElementInATweet<\/a><\/p>— Michael Scharnagl (@justmarkup) January 22, 2021<\/a><\/blockquote>\n
I had heard about\nruby<\/code><\/a> in the\npast, but it was one of these elements that I tend to look up and forget\nimmediately. This time, for some reason, I looked closer and even consulted the\nspec<\/a>.<\/p>\n
\n
The ruby<\/code> element allows one or more spans of phrasing content to be marked\nwith ruby annotations. Ruby annotations are short runs of text presented\nalongside base text, primarily used in East Asian typography as a guide for\npronunciation or to include other annotations. In Japanese, this form of\ntypography is also known as furigana<\/em>.<\/p>\n<\/blockquote>\n
\n
The rt<\/code> element marks the ruby text component of a ruby annotation. When it\nis the child of a ruby<\/code> element, it doesn't represent anything itself, but\nthe ruby<\/code> element uses it as part of determining what it<\/em> represents.<\/p>\n<\/blockquote>\n
You are supposed to use it like so.<\/p>\n
<<\/span>ruby<\/span>><\/span><\/span> \u660e\u65e5 <<\/span>rp<\/span>><\/span><\/span>(<\/<\/span>rp<\/span>><\/span><\/span><<\/span>rt<\/span>><\/span><\/span>Ashita<\/<\/span>rt<\/span>><\/span><\/span><<\/span>rp<\/span>><\/span><\/span>)<\/<\/span>rp<\/span>><\/span><\/span> <\/<\/span>ruby<\/span>><\/span><\/span><\/code><\/pre>\n
\n
The HTML <ruby><\/code> element represents small annotations that are rendered\nabove, below, or next to base text, usually used for showing the pronunciation\nof East Asian characters. It can also be used for annotating other kinds of\ntext, but this usage is less common.<\/p>\n<\/blockquote>\n
\n
The term ruby<\/em> originated\nas a unit of measurement used by typesetters<\/a>,\nrepresenting the smallest size that text can be printed on newsprint while\nremaining legible.<\/p>\n<\/blockquote>\n
Hmm \ud83e\udd14, this sounds like it could fit the footnotes use case. So I went and\ntried my luck in creating ruby<\/code> HTML footnotes.<\/p>\n
Using ruby<\/code> for footnotes \u2693<\/a><\/h2>\n
The markup is straightforward, all you need are\nruby<\/code><\/a> for the\nfootnote, and\nrt<\/code><\/a> for the\nfootnote text. I like that the footnote is just part of the flow text, so I do\nnot need to mentally switch context when writing. I also do not have to manually\nnumber my footnotes and come up with and remember the value of id<\/code>s. Another\nsmall advantage is that footnotes are not part of copied text, so when you copy\ncontent from my site, you do not end up with "text\u2009[2] like this". The snippet\nbelow shows the markup of a footnote.<\/p>\n
<<\/span>body<\/span> tabindex<\/span>=<\/span>\"<\/span>0\"<\/span><\/span>><\/span><\/span>
  <<\/span>p<\/span>><\/span><\/span>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec consectetur
    dictum fermentum. Vivamus non fringilla dolor, in scelerisque massa. Quisque
    mattis elit quam, eu hendrerit diam ultricies ut. Nunc sit amet velit
    posuere, malesuada diam in, congue diam. Integer quis venenatis velit. Donec
    quis nunc
    <<\/span>ruby<\/span> tabindex<\/span>=<\/span>\"<\/span>0\"<\/span><\/span>
      ><\/span><\/span>vel purus<<\/span>rt<\/span>
        ><\/span><\/span>Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      <\/<\/span>rt<\/span>><\/span><\/span><\/<\/span>ruby<\/span>
    ><\/span><\/span>
    maximus dictum. Sed nec tempus odio. Vestibulum et lobortis ante. Duis
    blandit pulvinar lectus non sollicitudin. Nulla non imperdiet diam. Fusce
    varius ultricies sapien id pretium. Praesent ut pellentesque massa. Nunc eu
    tellus hendrerit risus maximus porta. Maecenas in molestie erat.
  <\/<\/span>p<\/span>><\/span><\/span>
<\/<\/span>body<\/span>><\/span><\/span><\/code><\/pre>\n
\/* Behavior *\/<\/span>

\/* Set up the footnote counter and display style. *\/<\/span>
body<\/span> {<\/span>
  counter-reset<\/span>:<\/span> footnotes;<\/span>
}<\/span>

\/* Make footnote text appear as `inline-block`. *\/<\/span>
ruby<\/span> {<\/span>
  --footnote-display<\/span>:<\/span> inline-block;<\/span>
}<\/span>

\/* Display the actual footnote [1]. *\/<\/span>
ruby:after<\/span> {<\/span>
  counter-increment<\/span>:<\/span> footnotes;<\/span>
  \/* The footnote is separated with a thin space. \ud83e\udd13 *\/<\/span>
  content<\/span>:<\/span> '\u2009['<\/span> counter<\/span>(<\/span>footnotes)<\/span> ']'<\/span>;<\/span>
}<\/span>

\/* Remove the focus ring. *\/<\/span>
ruby:focus<\/span> {<\/span>
  outline<\/span>:<\/span> none;<\/span>
}<\/span>

\/* Display the footnote text. *\/<\/span>
ruby:focus rt<\/span> {<\/span>
  display<\/span>:<\/span> var<\/span>(<\/span>--footnote-display)<\/span>;<\/span>
}<\/span>

\/* Hide footnote text by default. *\/<\/span>
rt<\/span> {<\/span>
  display<\/span>:<\/span> none;<\/span>
}<\/span>

\/**
 * Make sure the footnote text remains visible,
 * so contained links can be clicked.
 *\/<\/span>
rt:hover<\/span> {<\/span>
  display<\/span>:<\/span> var<\/span>(<\/span>--footnote-display)<\/span>;<\/span>
}<\/span><\/code><\/pre>\n
The following CSS snippet determines the look and feel of the footnotes.<\/p>\n
\/* Look and feel *\/<\/span>

\/* Footnote text styling. *\/<\/span>
rt<\/span> {<\/span>
  background-color<\/span>:<\/span> #eee;<\/span>
  color<\/span>:<\/span> #111;<\/span>
  padding<\/span>:<\/span> 0.2rem;<\/span>
  margin<\/span>:<\/span> 0.2rem;<\/span>
  max-width<\/span>:<\/span> 30ch;<\/span>
}<\/span>

\/* Images in footnote text styling. *\/<\/span>
rt img<\/span> {<\/span>
  width<\/span>:<\/span> 100%;<\/span>
  height<\/span>:<\/span> auto;<\/span>
  display<\/span>:<\/span> block;<\/span>
}<\/span>

\/* Footnote styling *\/<\/span>
ruby:after<\/span> {<\/span>
  color<\/span>:<\/span> red;<\/span>
  cursor<\/span>:<\/span> pointer;<\/span>
  font-size<\/span>:<\/span> 0.75rem;<\/span>
  vertical-align<\/span>:<\/span> top;<\/span>
}<\/span><\/code><\/pre>\n
Demo \u2693<\/a><\/h2>\n
I have enabled ruby<\/code> footnotes right on my blog This is\nthe second footnote, the other is at the top<\/a>.<\/rt><\/ruby>, but you can\nalso play with a standalone demo<\/a> on Glitch\nand remix its\nsource code<\/a>.<\/p>\n
\n  
Something I could not get to work (yet) is to make the rt<\/code>'s CSS position<\/code> to\nbe absolute<\/code>. I got the best results so far by making the rt<\/code> an inline block\nby setting the CSS property --footnote-display: inline-block<\/code>. I am well aware\nof ruby-align<\/code><\/a>\nand\nruby-position<\/code><\/a>.\nThe former does not have great browser support at the moment but seems relevant,\nand the latter seems to have no effect when I change the display<\/code> value of rt<\/code>\nto anything other than the UA stylesheet default, which is block<\/code>. If you\nmanage to get it to work such that footnote texts open inline, floating right\nunder the footnote and not affecting the surrounding paragraph text, your help\nwould be very welcome. I also still need to look into supporting printable\nfootnotes. If you are interested, you can reach me and\ndiscuss this idea on Twitter<\/a>.<\/p>\n
The CSS to make the automatic footnote numbering work is based on a\nCSS counter<\/a>.\nThe rt<\/code> is styled in a way that it is not displayed by default, and only gets\nshown when the ruby<\/code>'s :after<\/code>, which holds the footnote number, is focused.\nFor this to function properly, it is important to make the <ruby><\/code> element\nfocusable by setting\ntabindex="0"<\/code><\/a>.\nOn mobile devices, the body<\/code> needs to be focusable as well, so the footnote can\nbe closed again by clicking\/tapping anywhere in the page. The rt<\/code> element can\ncontain\nphrasing content<\/a>,\nso links and images are all fine. Another thing to remember is to make sure the\nrt<\/code> element remains visible on :hover<\/code>, so links can be clicked even when the\nruby<\/code> element loses focus. I have moved the CSS display<\/code> value of rt<\/code> into a\nCSS custom property, so I could easily play with different values. The CSS below\nis all it takes to make the footnotes work.<\/p>\n
The MDN docs<\/a>\ndescribe the ruby<\/code> element as follows.<\/p>\n
This approach is what most folks use today, for example,\nAlex Russell<\/a>\nor the\nHTML export<\/a>\nof Google Docs documents.<\/p>\n
The current HTML Living Standard (snapshot from January\u00a022, 2021) remarks\nthat HTML does not have a dedicated mechanism for marking up footnotes and\nrecommends<\/a>\nthe following options for footnotes. For short inline annotations, the title<\/code>\nattribute could be used.<\/p>\n