Edgewall Software
Modify

Opened 11 years ago

Last modified 22 months ago

#9037 new enhancement

Incorporate footnotes into Trac (for use in documentation)

Reported by: Ryan J Ollos Owned by:
Priority: high Milestone: next-major-releases
Component: wiki system Version: 0.12dev
Severity: normal Keywords: footnote
Cc: Branch:
Release Notes:
API Changes:
Internal Changes:

Description

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.

Attachments (0)

Change History (9)

comment:1 by Christian Boos, 11 years ago

Keywords: footnote added
Milestone: next-major-0.1X

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:

in reply to:  1 comment:2 by Christian Boos, 11 years ago

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

comment:3 by Christian Boos, 11 years ago

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.

comment:4 by Ryan Ollos <ryano@…>, 11 years ago

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.

comment:5 by Christian Boos, 10 years ago

Owner: set to Christian Boos
Priority: normalhigh

in reply to:  4 comment:6 by ryano@…, 10 years ago

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?

comment:7 by Christian Boos, 8 years ago

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.

comment:8 by Ryan J Ollos, 6 years ago

Reporter: changed from Ryan Ollos <ryano@…> to Ryan J Ollos

comment:9 by Ryan J Ollos, 5 years ago

Owner: Christian Boos removed

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The ticket will remain with no owner.
The ticket will be disowned.
as The resolution will be set. Next status will be 'closed'.
The owner will be changed from (none) to anonymous. Next status will be 'assigned'.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.