Export footnotes on same html page as main text

[brookter (David Bertenshaw)]

Say I’m writing a web blog. I want to be able to use footnotes in the text, that get rendered as in page footnotes in the html, like so:

I can do this using Markdown (the screenshot is generated from my Tinderbox journal), but I can’t for the life of me work out how to do this using standard non-Markdown notes and export.

I’ve tried using the Tinderbox ‘Footnote’ feature, but I can’t work out how to translate that into the export code which will churn out the equivalent html for Markdown’s

This text has a footnote.[^1]

[^1]: Like this.

I suspect I’m missing something obvious, as it feels like this is basic stuff, but I’ve searched atbref and this forum and come up with nothing that I can translate into usable code.

So, I’d be very grateful for any pointers for how to generate in-page footnotes without using Markdown. In particular:

• What should be happening in the Tinderbox note? Do I used the footnote feature, or something else?

• What export code do I need to use to produce the correct html?

Many thanks for any help!

[eastgate]

The Tinderbox “footnote” feature isn’t meant for this: it fulfills the function of footnotes, but it’s not about formatting.

I’m away from the office, taking a break to drive from my home near US Route 1 outside Boston down to the end of Route 1 in Key West. So I’m just going to sketch a solution here; if it’s obscure or confusing, speak up and I (or someone else on the forum) will unscramble.

1. Do you really want footnotes? One alternative, popular with digital gardeners, is sidenotes, aka margin notes. That can be easier, and it also keeps the note close to its text.

2. Think about how you’d like the HTML to look. For footnotes, this typically includes two elements: the footnote anchor, and the footnote text.

3. You’ll likely want a macro, or perhaps two macros: footnote(symbol, text) or footnote(symbol) for the anchor, and footnoteText(anchor, symbol) for the footnote body.

4. As I said, sidenotes are easier. If footnotes are what you want, you’ll want to accumulate the HTML for all the footnote bodies (if one day might have several footnotes) in a string attribute. Then, in your template, you might say:

^text
<div class="footnotes">
^value($Footnotes)
</div>

What’s nice here is that you’re in control. Want to collect all the footnotes for a week in one place? No problem. Want a directory of footnotes for the year? Easy enough. Want your footnote bodies to be set in 8/11pt Gill Sans Light? CSS is your friend.

[brookter (David Bertenshaw)]

Hi Mark,

Thanks for the comprehensive answer! It will take me some time to work through it, as I’m not really familiar with macros (for example).

I use footnotes a lot in any text I write, so I would prefer to keep using them. I would want anything I use to be easily transferable to export to markdown/word docs etc.

I think I know how to get the text of the footnotes into $Footnotes by collecting them. What I really don’t understand is how to reproduce the symbols/link in the main body of the text – and number them automatically.

I’ve never used macros – I’ll study the help pages to learn about them. But I can’t envisage what the main body of the text will look like. How will it look to replicate this Markdown version?

This is footnote[^1]

[^1]: like this.

Of course, I can replace the [^1] with a link to the footnote note, but how does that translate to the automatic numbering you’d expect on the web page, for example?

I suspect I’m missing something fundamental about the feature – sorry…

Thanks!

[Update] I’ve just found the link to the May 12 Vimeo https://vimeo.com/947001551 where it looks like this topic was discussed… I’m watching it now, and hopefully I’ll be less confused afterwards

[PaulWalters]

@eastgate

sidenotes are easier

I don’t recall seeing example templates to create sidenotes. I know they can be created with CSS, but I don’t see any past postings here showing an “easy” technique – or any technique using Tinderbox. I agree that sidenotes are very nice. Would like to see some best practices for sidenotes in Tinderbox. After you get off US 1, of course.

[mwra (Mark Anderson)]

Well, this is fun! I’ll put my cards on the table: I like footnotes. But in the march from paper to screen some of the arcane parts of typesetting got overlooked. My last ACM paper (for HT’24) completely broke the ACM publishing system and the tech bros running it were lost as to the cause. Why? I’d simply used a footnote that itself had a footnote. But it’s perfectly valid, works in LaTeX (used for the article) and—the article being about hypertext—intentional. The bug was that the ACM’s ingest for authors’ drafts assumes^† a footnote can only be involved in body text (wrong!). No foul, per se, but it shows how lazy assumptions go sideways fast when presented with real data. TL;DR, footnote use is likely more complex than imagined.

Markdown starts from a completely different place: single plain text document. Recall, it was created for trying to blog from press conferences, on an early smart phone. The web and Markdown have moved on a bit. But pertinently, Markdown export starts from a different design intent from Tinderbox’s^‡ original export design.

But can Tinderbox do this magic? Yes, but (q.v. logic errors above) with some explicit assumptions:

• footnote texts are in discrete, linked-to, notes
• footnotes do not use the built-in Tinderbox footnote method
• footnotes are only called once in the parent document^§
• footnotes do not reference other footnotes (so my usage as at start above is not possible!)

I don’t like the last two restrictions, but resolving that makes the process more complex and we’re trying to get a solution for people who don’t want to dabble in the arcana of action/export code.

My solution is here: footnote-poc5.tbx (614.4 KB).

I think I may have posted an earlier version in the forum (indeed if a same-named older doc exists, ignore it), but this fixes a few edge cases/assumptions I’d missed in past versions.

There are two test notes in the ‘Home’ folder. Export these or view in Preview mode to get an idea of the outcome. The detail of the process is in the ‘NOTES’ container. For ease of reading, you can view ‘NOTES’ in preview mode and read all the implementation notes as a single piece.

Clearly, we could to more (q.v. assumptions above) but I think this covers the basic case. If people want this without inline code in their $Text, then I think the path is to make a feature request for the magic to happen behind the curtain. However, as I suspect those of use who like footnotes are in the minority, the ROI for the work involved may not be there. Remember too, once the code works and is triggered properly, who care how it then works.

†. Yay, footnote opportunity! Probably the programmer who made the system hadn’t read more widely than tech docs and hadn’t encountered full use of footnotes. Fair enough, but that’s why sensible people use the ‘adult supervision’ of proof-reading both (and separately) for sense and pure software/code logic and so spot such silly process errors: the human sense-check would catch the erroneous error flagged by the code-perspective check.

‡. I have zero personal interest in making Tinderbox more like Markdown-centric apps. That is left as a quest for someone else.

[brookter (David Bertenshaw)]

Thanks very much for the demo, Mark. It does exactly what I was looking for – I’ll have to study it to understand it better, of course!

[mwra (Mark Anderson)]

It looks scary as you have to put macros in the $Text. But in reality there are lots of use-but-don’t-touch things in our tools. Plus if it works, does it matter.

I will note that before action code gained functions, I tried and failed at this a number of times!

[brookter (David Bertenshaw)]

There are a few concepts here that needed pulling together – not just macros (which I’d never used), but the mechanics of how the HTML works and so on. A lot to read around and I’m not sure I would have got there on my own. Now I can see how you did it, it’s opened up a lot of possibilities for me… Thanks!

[mwra (Mark Anderson)]

I meant to add, by way of kudos/thanks, that the genesis reaches back to Tinderbox v5 era and work I did for @tedgoranson. That ended up as stretchtext: even cooler but more complex and not for dabbling in. More recently, I revived the idea working on this issue with @satikusala for export of his (now complete) doctoral thesis. That too went a different way: Markdown-centric use proved a better fit to his target export Word-via-pandoc.

Still both those pushed me into rummaging through the Tinderbox toolbox and lead to the solution above.

I’m not suggesting my solution above is the best or only in-Tinderbox solution and I’m aware it looks complex at first sight. However, ‘all’ it uses in customisation terms is a new link type, a template, a library of two functions, a stamp, and a macro. We regularly do things here that seem simpler but which use far more customisation.

[PaulWalters]

@mwra

stretchtext: even cooler but more complex and not for dabbling in

Actually, can be an interesting weekend diversion to look into stretchtext.

Nate Matias’ Tinderbox stretchtext site.

And other material from the 2009 Tinderbox weekend.

Bernstein Stretchtext Library.zip(1.0 MB)

Surgeon General’s Warning This work proceeds modern web languages, coding techniques, browsers, etc., and is not guaranteed to be useful.

[mwra (Mark Anderson)]

The stretch text we did went a bit further, as seen at Typed Parentheticals

This is a stretchtext prompt:

You get:

Click the ‘x’ top left and back the the original:

Before anyone notes, the JS controlling the expand collapse is slightly broken on that (now archive) site, but it shows the broad strokes.

Obviously if you were trying to simple add text within a sentence you’d need to effect the result in a slightly different way. Indeed you see that nicely in Storyspace in its reader mode, though I should add the latter may look like but isn’t like Tinderbox’s text pane preview.

I get the impression that except in deliberate (art(work) such a literary hypertext, the act of experimenting with getting working stretch text is enough to make those trying it move on to something else!

[ShawnMichaels]

Hello!

The code for the footnotes is interesting and exactly what I was looking for. Thank you for that! However, unfortunately, no footnotes are displayed for me (v. 9.6.1) (see screenshots). I haven’t changed anything in the document. @mwra , do you have any idea what might be the cause? Has something changed? Is my version of Tinderbox too old?

Best regards

[mwra (Mark Anderson)]

Oh dear. Sorry to hear that. I retried the original file (d/l from the link up-thread) and it works here in v10.0.2. It ought to work in v9.6.0. From the post’s date, I would have used v9.7.3 at the time but the idea worked on a file that probably goes back a year …to v9.6.0!

The process uses action code functions and those need v9.1.0 as that was when functions were first added.

The ‘magic’ in the demo happens in template ‘HTML-Page-with-footnotes’ which calls two functions stored in Library note (in /Hints) ‘Footnote functions’. The function fMakeFoonoteListing() is the one that generates the list of footnotes that is missing when you

I’ll admit I’m stumped as to why it is not working for you. If not already tried, I’d download a fresh copy of the TBX, re-start Tinderbox and load the fresh file. Is the result still the same.

[mwra (Mark Anderson)]

Note to self. In addressing the last above, I did see how the whole footnoting could be further modularised into a set of functions allowing a single insertion into the main page export template. Same process, but more cleanly done.

Essentially, in ‘HTML-Page-with-footnotes’ or any calling page template, you’d add—where the footnotes listing was desired)

<!-- insert footnote listing, if any -->
^if($Text.countOccurrencesOf("addFootnote"))^
^action(fCreateFootnoteList($ID))^
^endIf^<!-- end insert footnote listing, if any -->

replacing the existing ^action()^ call at the head of the note, and this in-page template code:

^if(vNotes>0)^
<hr class="footnote-rule">
<div class="footnote-list">
	<p class="footnote-title">Footnotes</p>
	<ol>
^value(vListString)^   </ol>
</div>
^endIf^

The fCreateFootnoteList() function would then wrap the existing functions and generate the enclosing HTML currently hard-coded in to the template (the latter section above). The presence in $Text of the string addFootnote is assumed to only find the name of the in-$Text macro used to mark footnotes. This if not detected, no footnote listing is inserted at all. If found, fCreateFootnoteList() would internally call fGetListOfFootnotes(iText:string) to allow then running fMakeFoonoteListing(iList:list,iCaller:string) whose output would be meshed into the static HTML of the overall listing section and that whole complete string would be inserted complete into the calling templates HTML output.

So, that could be done… (albeit to the same visible output at the original example)

[mwra (Mark Anderson)]

Turned out to be pretty simple. The main export template now only has this code for the footnotes:

// code
^if($Text.countOccurrencesOf("addFootnote")>0)^
^value(fCreateFootnoteList($ID))^
^endIf^
// code

The library ‘Footnote functions’ now has this new function:

function fCreateFootnoteList(iID:number){
	var:string vID = iID; // cast $ID to a string to avoid accidents
	var:list vList = fGetListOfFootnotes($Text(vID));
	var:string vOutput =;

	vOutput += '<hr class="footnote-rule">\n';
	vOutput += '<div class="footnote-list">\n';
	vOutput += '\t<p class="footnote-title">Footnotes</p>\n';
	vOutput += '\t<ol>';
	vOutput += fMakeFoonoteListing(vList,vID);
	vOutput += '\t</ol>\n';
	vOutput += '</div>\n';

	return vOutput;
}

Notice how the template only needs 2 elements. Firstly, the ^if()^ tests if the note needs a footnote list—I added a new text note ‘Test without notes’ to test this. Secondly, the list is generated by a single ^value()^ command calling the new function. The latter then calls the existing function to return a string of the entire footnote list section.

Here is a revised TBX, with the above changes: footnote-poc6.tbx (600.1 KB)

Note that the output/result is the same but some light incremental formalisation/structure has better encapsulated the HTML footnote list generation.

[mwra (Mark Anderson)]

Doh! In moving code out of the export template I overlooked one important fact. If you use the above doc and preview, you will notice that on each preview, the footnotes start at an ever higher number.

Why? because each exporting (content) note has a counter stored in $FootnoteCounter. It is only needed by notes with footnotes as it is used during evaluation of the in-$Text ^do(addFootnote)^ macros so the footnotes number sequentially. $FootnoteCounter is initially set at 1. At the end of preview or export of a note with 6 footnotes, the value stands at 6.

In footnote-poc6.tbx I unwittingly removed the code in the template’s ^action()^ section that re-initialised $FootnoteCounter to 1. In this version I use this code:

^action(
$FootnoteCounter($ID) = 1; // reset the note footnote counter
)^

at top and bottom of the template. This way it both re-initialised at start and then re-set at the end of export. thus before, after previewing note ‘Rural Rides’ $FootnoteCounter would hold 6. Now it shows 1 as it is only used during export and then reset.

The only changed notes are the template “HTML-Page-with-footnotes” which not has an ^action()^ section added at both beginning and end, and library “Footnote functions” has added comments at its end. The commenting arose from a conversation with @satikusala’s about the ability to make the ‘code’ portable. Library could add another function code to generate the required user attribute, if necessary, but whilst the template notes can be copy pasted between TBXs, marco code is currently inaccessible for copy/transfer other than by copy/paste directly from the source TBX’s Export Inspector’s Macro tab. Hm, perhaps these could be exposed as notes in /Hints, like stamps. Though originally designed for export use, most ^do()^ macro use I have seen of late uses action code to some degree.

Here is the file, with the fixes: footnote-poc7.tbx (512.4 KB)

[ShawnMichaels]

@mwra , thank you very much for your help and the considerable time you’ve put into this! I’ve been very busy the last few days, which is why I haven’t responded yet, sorry, but I also wanted to get the file running first. I’ve also tried to understand exactly what you’ve programmed, but I’ve only grasped it roughly so far because I’m not yet familiar enough with Tinderbox. Anyway: Unfortunately, I didn’t manage to get it working. Even in the latest version, the footnotes don’t function, and that’s left me somewhat at a loss. It should work as soon as one opens the file, right?

[mwra (Mark Anderson)]

@ShawnMichaels

the footnotes don’t function,

Sorry to hear this. To clarify, don’t function in what way? In the TBX (please use footnote-poc7.tbx)? Or, when the data is copied elsewhere?

For instance, if I open footnote-poc7.tbx, select note ‘rural Rides’, select the text pane ‘Peview’ sub-tab^†. In the preview, click footnote #1 (superscript ‘1’ after the word ‘smoke’), and the preview should scroll to reveal the footnotes.

Or you can export the note and try the HTML page in a Web browser.

What test are you doing? I ask as it might help track down why it isn’t working for you.

[@eastgate @satikusala something perhaps to review, briefly, review in the next meet-up so the process being enacted is on video? The demo doc is already done (footnote-poc7.tbx) so there are no preps needed.]

†. In not visible, use Tinderbox’s Window menu, Show Text Pane Selector.

[mwra (Mark Anderson)]

OK, dialling the previous demo up to 11, this version is modified to allow for a page exported from multiple notes. In the early examples we got one note → one HTML page with a footnote list at the end. Now, previewing/exporting a container that includes all its (exporting) children results in continuous footnote numbering that runs across the entire composite page.

See: footnote-poc-multiple1.tbx (546.4 KB)

This new method works either with composite notes or for individual exports—try previewing some of the child notes of the main text container ‘Endnote Listing Test’.

The genesis of this arose from discussion with @satikusala about how to deploy the above in a more real-world setting where there is a fair likelihood of export pages that use more than one source note.

The logic for the continuous footnote numbering follows the outline below it. However, by using the same “Item-with-footnotes” template used by descendant notes, an `^include()^`` for outside the root container of the page can be used.

The above demo tests both the include() case and allowing for some notes (with footnotes) not exporting.

I hope people find this useful, and do let me know of breakages or unconsidered edge-cases…

---

(Ping: @tedgoranson. This PoC is pertinent to ideas we’ve discussed and should be compatible with your existing stretchtext design).

[mwra (Mark Anderson)]

A revised demo: footnote-poc-multiple2.tbx (570.6 KB)

It includes better commenting in the Library note and adds a note ‘MANIFEST: summary on moving code to a new TBX (preview)’ that explains how to port the code to your own document.