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).