Incorporate footnotes into Trac (for use in documentation)

[Ryan J Ollos]

As I have tried to contribute a little bit to the documentation, it has occurred to me that it would be really nice for the sake of page layout and clarity to have footnotes available for use in the documentation.

I have used the ​th:FootNoteMacro for quite some time and there does not seem to be any issues with it. There are currently not even any open tickets filed against the macro.

Would it be possible to incorporate this macro into the next Trac distribution if we were to refactor the code to fit the style guidelines for Trac, write some unit tests, or whatever else might be necessary?

Or is the preferred way to go about this through a direct incorporation into the wiki markup language, like I see is available with Restructured Text (as shown on WikiProcessors - see Example 2)?

I searched around but did not find any similar suggestions.

[Christian Boos]

I'm glad you raised this topic, it's also something that was on my wishlist ;-)

The FootNote macro on TracHacks seems to be a good starting point, and I think the way it works is fine, compared to what other wikis provide. The few improvements I see are in the way the footnote data is stored: instead of being attached to the formatter, it should be put in the rendering context, because the latter is shared during recursive rendering (i.e. you'd like to gather the footnotes found in divs, quotes and table cells). Another possible improvement is to add some kind of shorthand syntax, maybe a variant of the intra-page link (normal link [#someid], [#(ref)] footnote link?).

Here are a few additional references I collected on the topic:

• ​[Trac] Footnotes mail on Trac-users (25 Jan 2005)
• ​Wikipedia:Help:Footnotes
• ​Creole2Wiki:"Creole 2.0/1.0 additions in 2.0/Footnotes"
• ​footnotes in JspWiki
• and MoinMoin's ​<<FootNote()>> macro

[Christian Boos]

… Another possible improvement is to add some kind of shorthand syntax, maybe a variant of the intra-page link (normal link [#someid], [#(ref)] footnote link?).

Or simply use ((This is a foot note)) as in ​http://www.dokuwiki.org/syntax#footnotes.

[Christian Boos]

Or simply use the very common "e-mail" or README style ... [1], with footnotes specified as:

[1] This is a foot note

Of course this would conflict with revision links, but how often do we refer the the first few revisions? In presence of footnote definitions it would make sense to interpret them preferentially as footnote references. If there are no corresponding footnote, revert to the "changeset" meaning.

[Ryan Ollos <ryano@…>]

I tend to prefer the syntax you noted in comment:2, but I'll do some research over the weekend starting with the references you mentioned.

One of the reasons I prefer that syntax is that it is clean, and a user is unlikely to use the syntax when they don't intend to. My preference for this comes from the experience that wiki syntax is often used accidentally, for example when log messages are inserted as comments. An analogy is that, if the syntax for a changset was [[5]] rather than [5], I think it would be accidentally used much less often. Similarly ##5 rather than #5 for tickets. I'm not suggesting changing the existing wiki syntax, just showing how we might avoid clashes with commonly used text in choosing the syntax for footnotes.

One of the features that the ​th:FootNoteMacro has implemented that we might want to consider is the ability to refer to previous footnotes using the [[FootNote(1)]] syntax. I'm not sure how this could be best implemented, but I think the ​th:FootNoteMacro missed the mark slightly in that using an ordered numeric index is prone to error and difficult to maintain when editing a large article.

[ryano@…]

Replying to Ryan Ollos <ryano@…>:

One of the features that the ​th:FootNoteMacro has implemented that we might want to consider is the ability to refer to previous footnotes using the [[FootNote(1)]] syntax. I'm not sure how this could be best implemented, but I think the ​th:FootNoteMacro missed the mark slightly in that using an ordered numeric index is prone to error and difficult to maintain when editing a large article.

Replying to cboos:

Another possible improvement is to add some kind of shorthand syntax, maybe a variant of the intra-page link (normal link [#someid], [#(ref)] footnote link?).

Now that I read this again, it appears you may have already suggested an answer to the question I was asking. Are you suggesting that a short-hand such as [#(ref)] could be used to refer to a previously generated footnote, as [[FootNote(1)]] currently does?

[Christian Boos]

Relating comment:2 to #10734: we could also have a footnote block:

Some text.
(((
A multiline footnote.

With arbitrary content.
)))
Reprise of the text.

or even:

Some text (((
A multiline footnote.

With arbitrary content.
))). Reprise of the text.

[Artoria2e5]

Came here from the FootNoteMacro place and turns out it's somewhat of a forgotten ticket. Anyways, a few cents:

I'm not sure how this could be best implemented, but I think the ​​th:FootNoteMacro missed the mark slightly in that using an ordered numeric index is prone to error and difficult to maintain when editing a large article.

The MediaWiki approach is to identify footnotes by a customizable string name as well as an auto-incrementing counter. The element ID would still go with the counter, so the program needs to maintain a dict associating the name with the counter.

It's even possible for the current macro to do that (it works with global state / context already), so long as you figure out a syntax. Maybe you can differentiate by argument count?

Or simply use the very common "e-mail" or README style

The non-conflicting alternative is [^1]. It's used by some Markdown dialects — and in emails when people want to disambiguate between links and notes. Theoretically you can also put names into it like [^foobar], but it seems to have the downside of making naming or numbering mandatory — no more throwaway notes.

On the other hand, Ryan's approach could work better. Taking an analogy from processors, we can say that adding a prefix to the (( note )) bit defines its name — like

The `-p` option is used to specify a pass-phrase in scripting environments.
((#name:blah The factory pass-phrase is "Bravo Lima Alfa Hotel".))
(((#name:example
For example, instead of rigging up `expect`, an admin can simply write
{{{#!bash
MAKE UP SOME SCRIPT
}}}
)))

(Yeah, it does work better in multi-line, because you can use a line break…)