Footnotes inside Tables

[tajmone]

• When upcoming Asciidoctor feature for "block-level content" table cells becomes available, replace all a-styled cells with new b style. (See Introduce a new type of AsciiDoc table cell asciidoctor/asciidoctor#2352)

---

When footnotes occur in tables, inside a cell styled as a (AsciiDoc), then the footnote will be created at the end of the cell. This happens because AsciiDoc cells are treated as embedded AsciiDoc documents.

NOTE 1 — Nevertheless, footnotes numbering is preserved inside table cells, without breaking the general numbering order.

Although in some cases this might be acceptable, there are tables which contain multiple notes with the same text, which could be externalized as a single footnote — but this would look ugly because they'd appear as a single note pointing to another cell — unless that cell could be styled as d (default), which is fine if any of these cells doesn't require the AsciiDoc style.

My main concern is having to deal with tables where some notes are placed at the bottom of the cell, while others at the bottom of the section (i.e. in HTML docs). I'd rather have a consistent style throughout the book.

The most significant example of this is Appendix H: CODE PATTERNS, which contains 11 footnotes, all inside table cells, 9 of them being also inside a code-block, and many of the being duplicate.

NOTE 2 — Although Asciidoctor allows to reuse a same note more than once, keep in mind that clicking on the footnote link will jump to the note text, but the back-link of the footnote number will only jump back to the first occurrence of that note — which could be a problem for the reader, who will loose track of where he was.

I need to consider if it's worth sharing the same footnote or if it's better to just create a shared attribute containing the same text, to avoid repetition of contents but preserve the redundant footnote, so each has a correct back-link. (This would still introduce a DRY element in the workflow).

References

• Asciidoctor Manual » §61. Footnotes:
  • §61.1. Externalizing a Footnote

[tajmone]

Footnotes in Tables Behaving Normally

An example of a footnote occurring in table cell but behaving like all other normal notes is note 72 in 26. THE HUGO ENGINE AND HOW IT WORKS.

Since the cell containing the note is styled as d (default), the actual note text is not inside the cell but with the rest of the other footnotes at the end of the HTML doc.

[tajmone]

Upcoming Solution in Asciidoctor

I've come across the following Issue on the Asciidoctor project:

• Introduce a new type of AsciiDoc table cell asciidoctor/asciidoctor#2352

When that will be implemented, the whole problem of footnotes inside table cells will be resolved — the new b style (block) for table cells will be treated as an AsciiDoc block snippet, and not as a nested AsciiDoc document like with the a (AsciiDoc) style.

[tajmone]

Related Issues

See also:

• Footnotes in tables asciidoctor/asciidoctor#2350
• Placement of footnotes in tables asciidoctor/asciidoctor#1705

[tajmone]

Footnotes References

This web page discusses in great detail footnotes and their usage:

• https://libguides.murdoch.edu.au/footnote/text

We ought to extract some correct terminology to be able to describe their use in the Styling Conventions document (i.e. avoid ambiguity when referring to note number that appears in the text body and that which appears next to note contents).

[71GA]

Has this been solved already? It is now a 5 years since this problem was reported.

[tajmone]

Has this been solved already? It is now a 5 years since this problem was reported.

No, and I don't think is going to be fixed any time soon either. It's a problem with the actual AsciiDoc specification, i.e. not specific to the Ruby Asciidoctor incarnation, so the question has to be referred to the AsciiDoc standard committee (which I believe it was). Similar changes, at the spec level and affecting every implementation of AsciiDoc, are likely to be discussed for a long time, and only after prolonged discussions and a final deliberation an actual proposal for change is going to make it to the next AsciiDoc Spec update, especially if it's a backward compatibility breaking change.

And even then, after having being accepted, the waiting time before the new updated AsciiDoc Spec comes into being in an Asciidoctor update is going to take ages, and most likely will only happen during a MAJOR version update too.

Optimistically, it's going to take years. But then, the Hugo project is also decades old (almost half a century), so the waiting times are not beyond the overall time span of the project.

Unfortunately, there's no lightweight markup syntax that supports footnotes in tables or inside footnotes, at least not that I'm aware of. I could give it a try with pandoc, and check if it supports at least footnotes inside table cells, but even if it did (which I doubt), it would mean having to port the entire book to pandoc, which is not easy task since the book leverages many Asciidoctor specific features which are not natively available in pandoc.