Theme

Apple Annie’s Weblog

Improvements to citations with footnotes and endnotes.

I wrote about adding microformats citations to weblog last November during NaBloPoMo. Then last week, I saw some discussion about footnotes again, replied with a link to my post, and began investigating some of the other solutions I saw mention of. One of them led me down the path of a couple EPUB related role attributes and I decided to go ahead and add them. Let's take a look at what I did through the updates I made to my recent CSS Color Modules and Changes, Part I post.

Existing citations

Implementation of microformats citations will go unhindered, but here's a light refresher of where I started. The h-cite property resides on a list item and contains one or more of the following properties:

  • dt-published
  • p-author and h-card
  • p-publication
  • u-url and p-name

Here is an example from the referenced CSS Color Modules post above, minus the updates (added below):

<li class="h-cite"><small>
  <a id="cite-note--4" href="#cite-ref--4">[4]</a> 
  <time class="dt-published">2023-02-02</time>, 
  <span class="p-author h-card">Adam Argyle</span>, 
  <span class="p-publication">Chrome for Developers</span>, 
  <cite><a class="u-url p-name" href="https://developer.chrome.com/docs/css-ui/migrate-hd-color" rel="external"><i>Migrate to HD CSS color</i></a></cite>
</small></li>

You should also note that the u-url and p-name reside on an <a> inside of a <cite> element. This citation matches the cite attribute on the citation reference on either a <q> or <blockquote>:

<blockquote cite="https://developer.chrome.com/docs/css-ui/migrate-hd-color">
<ol>
  <li><p><b>Graceful degradation:</b> Use the new color spaces and let the browser and operating system figure out which color to show based on display capabilities.</p></li>
  <li><p><b>Progressive enhancement:</b> Use <code>@supports</code> and <code>@media</code> to assess the capabilities of the user's browser, and if conditions are met, provide wide gamut colors.<sup id="cite-ref--4"><a href="#cite-note--4">[4]</a></sup></p></li>
</ol>
</blockquote>

Footnotes

From what I understand, the EPUB epub:type attribute usage is being replaced with ARIA roles for accessibility: This document provides guidance for publishers looking to move from the use of the EPUB 3 epub:type attribute to ARIA roles for accessibility.[1]

That quote is from the abstract of this document, and goes on to explain:

The biggest of these differences is in their primary applications. The epub:type attribute has evolved to aid publisher workflows. It has limited use enabling reading system behaviors outside of some core functionality of EPUB (identifying navigation elements and enhancing media overlay documents). Although it was hoped the attribute would also expose information to assistive technologies, in practice it does not.

The primary purpose of the role attribute, on the other hand, is to expose information to assistive technologies. It is not to facilitate user agent behaviors.[2]

The two roles I am concerned with for citations are complementary to the two parts of what I've already implemented: the citation reference and the citation note; these are: role="doc-noteref" and role="doc-footnote". The recommendations for each have some stipulations as follows.

doc-noteref

A reference to a footnote or endnote, typically appearing as a superscripted number or symbol in the main body of text.[3]

  • HTML usage: <a>

doc-footnote

Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text. The doc-footnote role is only for representing individual notes that occur within the body of a work. For collections of notes that occur at the end of a section, see doc-endnotes.[4]

  • HTML usage: aside element when identifying a single footnote, or on descendants of sectioning content when identifying individual footnotes in a group (refer to footnotes and endnotes)[5]

From this information, I am a bit torn on the requirements, as they seem to slightly contradict each other. You'll see how I've decided to implement this (for now) under Template updates, but I am open to clarity and improvements if this method proves incorrect or incomplete.

Endnotes

In addition to proper citations relating to references, I also regularly include additional resources and links at the end of most blog posts. This is where I may eventually end up, after adding the requirements for role="doc-footnote" usage, as I believe the better method is to stick with role="doc-endnotes" as the containing section and role="doc-endnote" for each item.

doc-endnotes

A collection of notes at the end of a work or a section within it.[6]

Important context: Note that the doc-endnotes role is never applied directly to the list of endnotes. See the doc-endnote role for more information.[7]

This context is important because giving roles to elements can override their inherent nature, such that adding a role to a list element itself will override its role as a list. This will then cause issues with child elements' roles as listitem. Along these same lines, it is no longer necessary to add the role doc-endnote to a list item in a containing doc-endnotes section: [t]hese roles are now implied on list items within sections that have a...doc-endnotes role.[8] However, as I cover in the next section, I have added both roles.

doc-endnote

One of a collection of notes that occur at the end of a work, or a section within it, that provides additional context to a referenced passage of text.[9]

Important context: Authors MUST ensure that elements with role doc-endnote are contained in, or owned, by an element with the role list.[10]

If you understand the context in the previous section, the above context should also make sense: doc-endnote must be a child of an element with the role list, either by default through being an HTML list such as <ul> or <ol>, or by having an explicit role of list assigned. My usage of both doc-endnotes on the sectioning element and doc-endnote on the list items may be redundant or unnecessary and I may end up cleaning this up. For now let's see how all this looks together in the template updates I made for weblog.

Template updates

The updates needed on weblog pretty much exclusively apply to the default post template in config. Since I am using Drafts for weblog authoring, I have both a recipe and post template, the post template mimicking the default post config in weblog, so I'll need to update all three templates.

I've added a sectioning element with role="doc-endnotes" and role="doc-endnote" to the list items. The ... denotes omitted content in the default post that is not relevant.

Default post: <<[---
...

--- 

<section role="doc-endnotes">

<h2><i aria-hidden="true" class="fa-solid fa-circle-info"></i>Post info</h2>

<p class="u-font-ur--medium u-spacing--bottom"><small>Links in this post:</small></p>

<ul>
<li role="doc-endnote"><small><a href="" rel="external"></a></small></li>
<li role="doc-endnote"><small><a href="" rel="me"></a></small></li>
</ul>

<p class="u-font-ur--medium u-spacing--bottom"><small>POSSE copies:</small></p>

<ul>
<li role="doc-endnote"><small><a class="u-syndication" href="" rel="syndication">Shared on social.lol</a></small></li>
<li role="doc-endnote"><small><a class="u-syndication" href="" rel="syndication">Shared on Apple Annie's Microblog</a></small></li>
</ul>

</section>

--- ]>>

For reference notes and citations, here is an updated example from the CSS Color Modules post above:

<li role="doc-endnote" class="h-cite"><aside role="doc-footnote"><small>
  <a id="cite-note--4" href="#cite-ref--4">[4]</a> 
  <time class="dt-published">2023-02-02</time>, 
  <span class="p-author h-card">Adam Argyle</span>, 
  <span class="p-publication">Chrome for Developers</span>, 
  <cite><a class="u-url p-name" href="https://developer.chrome.com/docs/css-ui/migrate-hd-color" rel="external"><i>Migrate to HD CSS color</i></a></cite>
</small></aside></li>

Additions to this citation note: a role="doc-endnote" on the list item and a nested <aside role="doc-footnote">.

<blockquote cite="https://developer.chrome.com/docs/css-ui/migrate-hd-color">
<ol>
  <li><p><b>Graceful degradation:</b> Use the new color spaces and let the browser and operating system figure out which color to show based on display capabilities.</p></li>
  <li><p><b>Progressive enhancement:</b> Use <code>@supports</code> and <code>@media</code> to assess the capabilities of the user's browser, and if conditions are met, provide wide gamut colors.<sup id="cite-ref--4"><a href="#cite-note--4" role="doc-noteref">[4]</a></sup></p></li>
</ol>
</blockquote>

This reference includes the addition of a role="doc-noteref" on the citation reference link.

As you can see, my updates include some redundancy and possibly incorrect markup: addition of the <aside role="doc-footnote"> even though part of the recommendation says to only use this on a single footnote within the "body of a work." I chose to include it because of the conflicting recommendation to use on descendants of sectioning content when identifying individual footnotes in a group.[11] Additionally, I included role="doc-endnote" even though that role is implicit on a list item within a sectioning element with the role doc-endnotes. These can all be updated and refined when I find clarity on this information.

Update: Isn't it just like publishing a post and a few hours later coming across something to change your mind? Well, I've found the thing I needed to make me definitively remove role="doc-endnote from the list items. In the W3C Candidate Recommendation, published February 27, 2024, doc-endnote is listed as deprecated with the following note:

The doc-endnote role was designed for use as a list item, but due to clarifications in the WAI-ARIA specification, it is not valid as a child of the list role. As the doc-endnotes role already identifies a section of endnotes, authors are instead advised to use the list and listitem roles when native HTML elements cannot be used to structure the entries.[12]

Secondly, within the same document, the recommendation is now unequivocally to not use doc-footnote within the endnotes as it is redundant. I also appreciate the addition of mentioning that multiple and separate lists of endnotes can be contained within the doc-endnotes sectioning parent.

The element carrying the doc-endnotes role MUST contain at least one descendant list containing the endnotes (if the notes are subdivided, for example by chapter, the element would contain more than one list).

Authors MUST NOT declare elements with the role doc-footnote within the endnotes as it is redundant with the implied role.[13]

After leaving this post feeling quite unsettled with how I left things, conflicted by what I had found (and documented above), this feels like a 180° turnaround just a few hours later!

Post info

Citations in this post:

Links in this post:

POSSE copies:

Share this post on social media.

Discuss on Mastodon
Back to top

Featured post

Recent posts

Search posts

Buy me a coffee

Works in Progress