Feedback on FootNotePlugin

This plugin is a rename of EndNotePlugin. See previous discussion at EndNotePluginDev.

-- IanBygrave - 05 Dec 2006

Ideas from EndNotePluginDev that I plan to address, in no particular order:

• CSS (MichaelDaum)
• Allowing line breaks within notes. (JamesParker)
• Configurable delimiter instead of curly brackets. (IanDSouza)
• %FOOTNOTE{ "footnote text" label="f1"}% and %FOOTNOTE{ ref="f1" }% (DiabJerius)

-- IanBygrave - 05 Dec 2006

Line breaks within notes (with the current %FOOTNOTE% syntax) needs TWiki::Func::extractParameters to be able to return parameters with line breaks in them. As far as I know, it can't do that.

I may change the syntax to:

%STARTFOOTNOTE{ params ... }%Footnote text.
With line breaks in it.%ENDFOOTNOTE%

I think I can do this without changing the curly bracket usage.

-- IanBygrave - 05 Dec 2006

Why not simply use the line continuation syntax with a trailing backslash? That should work out of the box. Example:

%FOOTNOTE{ "footnote line 1\
footnote line 2\
footnote line 3" }%

-- PeterThoeny - 05 Dec 2006

My footnotes disappear after saving one topic several times (the footnote text will not appear anymore). Is there a known bug?

-- StefanieWrobel - 30 Dec 2006

PS my syntax: |*Phase*|*Beispiele* {{ verkürzt nach EbGH05, S. 273 }} |

The footnote appeared after the first saving. Then i created a topic for EbGH05, returned to the topic containing the footnote. The footnote text was gone. The anchor did still exist, leading to nowhere.

-- StefanieWrobel - 30 Dec 2006

Thanks for spotting that bug. I'll upload a fix soon. It seems to be worse if you are using modperl.

-- IanBygrave - 05 Jan 2007

Hi Ian. That would be great because it is a nice plugin. We are using speedy_cgi.

-- StefanieWrobel - 07 Jan 2007

The FootNotePlugin.zip uploaded on 05 Jan 2007 - 17:58 is fixed.

-- IanBygrave - 08 Jan 2007

Ian, I have seen that you are updating the zip package, thanks! Could you update also the text on the FootNotePlugin topic so that we can see what is new without downloading the package?

-- PeterThoeny - 11 Jan 2007

Thanks for updating the plugin topic. Small feedback: In the plugin info table, escape the EndNotePlugin with leading <nop> to avoid a broken link at sites where the plugin is installed.

-- PeterThoeny - 12 Jan 2007

Great plugin! One thing I'm hoping for , is more flexibility in formatting the footnote tag. I would like to insert topic references with this plugin, so it would be necessary to use formats like [_Author_, 2004] and [3]. Otherwise it suits perfectly to this task.

-- MikkoLaakso - 29 Jan 2007

Hi. If I use FootNotePlugin on a page which has more than one section (using the MultiEditPlugin), then the footnote appears at the end of the section, not at the end of the page. What text is FootNotePlugin looking for to identify the end of the page ? It looks like this is not necessarily the real end of the page. Any help appreciated - it's a great plugin.

-- SteveJonesST - 16 May 2007

I assume you are using the 30 Apr 2007 version. This puts footnotes at the end the text passed to postRenderingHandler

-- IanBygrave - 24 May 2007

Hi Ian. Yes, I am using the latest versions of FootNotePlugin, MultiEditPlugin and Edit contrib, on TWiki 4.0.5. I am willing to help you debug.

-- SteveJonesST - 25 May 2007

I've noticed that on TWiki 4.1.2, and FootNotePlugin 29 April version, that footnotes don't display rendered in page order. My pages use a lot of includes, often generated from searches, and the footnotes show up from the included pages first, and then from the "including" page. Is there any way to change this order to get them in final rendered page order?

Would there be a downside from doing the footnote processing as part of the postRenderingHandler instead of the commonTagsHandler? (Or maybe do all of the markup conversion from commonTagsHandler and postpone the footnote processing until the postRenderingHandler? I've looked at the code a bit and in order to move the processing to postRendering, the Note function would have to return a real html link instead of the wiki markup, maybe by using the TWiki::Func::internalLink?

-- GeorgeClark - 05 Dec 2007

In looking into this a bit further, it seems as though the Plugin hooks need a hook in the same location as the _TOC builtin hook in TWiki.pm. The %TOC% needs to be handled after all other variable expansion, but before the excluded blocks are re-inserted. It seems as though any plugin that deals with the complete page, like the TOC, Footnotes, Index, etc. would have to process just prior to the TOC.

postRenderingHandler is a bit too late. It is after the TOC has been built, so any Footnote header cannot be added to the TOC. And the excluded blocks are restored, so variable handling becomes much more complex.

-- GeorgeClark - 05 Dec 2007

May be a new hook is needed? You can create a Feature Request.

-- PeterThoeny - 06 Dec 2007

Before I go asking for additional hooks, I'm still trying to understand the order of hook processing, particularly expansion of builtin tags like %INCLUDE%. What I'm finding is that at least the commonTagsHandler seems to get called from the deepest INCLUDE upwards. So footnote order is very confusing.

Would the hook execution change if it was using a registered Tag handler, or is there some way to determine that the handler is being called in a pass that is after all INCLUDEs have been expanded?

-- GeorgeClark - 11 Dec 2007

The fix for the footnote order seems really simple. Finally found a note to it buried in one of the modules.

In the common tag handler, include:

    if( $_[3] ) {
            # bail out, handler called from an %INCLUDE{}%
        return;
        }

If the common tag handler is processing an include, bail out until called with the full topic text. I have not done a lot of testing but it seems to work for me.

-- GeorgeClark - 09 Jan 2008

This plugin would appear not to work on TWiki 4.2. Is this correct? configure sees it and allows it to be enabled, but it doesn't work and doesn't show up in TWiki.InstalledPlugins. If it is bwoken in 4.2, is there any chance of an update...?

-- MarcusLeonard - 04 Feb 2008

FootNotePlugin 2.003 includes footnote ordering patch from GeorgeClark and tested on TWiki 4.2

-- IanBygrave - 06 Feb 2008

Working for me. Thanks for the quick fix.

-- MarcusLeonard - 07 Feb 2008

Sometimes the {{ }} delimiters, especially the closing }} pair, are being mistakenly matched with the appearance of }} in the Latex being used with the LatexModePlugin. When this happens, the Latex equation is not generated and rendered and the text ends up with a generated %ENDFOOTNOTE% in the view. The quick fix I've implemented in my installation changes the match from $_[0] =~ s/}}/%ENDFOOTNOTE%/g; to $_[0] =~ s/}}(\s|\.)/%ENDFOOTNOTE%/g; so that we apply the ENDFOOTNOTE delimiter only when the }} is followed by a space or a period, which I think covers most cases. However, we still have to rely on LatexModePlugin users not to have a space after their }}.

-- TonyLiu - 04 Mar 2008

Could you use the {PluginsOrder} configuration setting to make LatexModePlugin render first?

-- IanBygrave - 06 Mar 2008

I'm having a problem: When I add a footnote that contains a hyperlink, the footnote (ie a superscript 1, 2 etc) winds up containing that hyperlink + the superscript number. I'm using the standard WYSIWYG editor with TWiki 4.2. If I add a link in, but make sure the editor will not turn it into an HTML link (by getting rid of the http:// at the beginning), everything is fine. Has anyone else had problems with this?

-- MaxPar - 29 Apr 2008

I see the same problem with hyperlinks in footnotes. It seems to have been caused by the change "25 Apr 2008: Show footnotes in tooltips." for V2.004. You could try the previous version if you can work out how to download old versions of attachments

-- IanBygrave - 29 Apr 2008

FootNotePlugin 2.005 fixes hyperlinks in footnotes, and may also fix corruption of LatexModePlugin markup.

-- IanBygrave - 29 Apr 2008

Your fix for hyperlinks in footnotes is working well for me. Thanks so much!

-- MaxPar - 06 May 2008

I recently installed this plugin (in 4.2.2), and it is working fine. But I had the need to use something other than regular Arabic numerals for the footnotes numbers. Looking around it seemed that using Roman numerals was pretty standard for footnotes. I also found CPAN has a nice Roman module. So I went ahead and patched my copy of the plugin so it can optionally display the footnote numbers as Roman numerals.

Basically, from the user perspective it works like this:

• I can change the default wiki-wide format by setting the FORMAT property on the FootNotePlugin page (i.e. * Set FORMAT = ROMAN for Roman). If not set the default is ARABIC.
• I can change the format for a specific topic by adding a %FOOTNOTEFORMAT{format}% tag to the page (e.g. %FOOTNOTEFORMAT{ROMAN}% for Roman).
• I can change the format for a specific footnote using %STARTFOOTNOTE{FORMAT=format}% note text %ENDFOOTNOTE% (e.g. %STARTFOOTNOTE{ROMAN}% note text %ENDFOOTNOTE% for Roman).

When the format is set to ROMAN, the numbers are formatting as Roman numerals. For example, the second footnote would look like this⁽ⁱⁱ⁾ (instead of this⁽²⁾).

If the Roman perl module is not available then the format reverts to Arabic.

I am not sure if this would be useful to others. If anyone is interested I can post some diffs, or a new copy of the zip. Let me know.

-- GeoffreyLowney - 22 Aug 2008

I had been thinking about custom label formats, extending the footnote markup syntax to:

• {{Text}} Use the next number (in the default format) as the label. The default would be customizable with the FORMAT setting as you suggest.
• {{f:Text}} Use the next number in format f as the label, where f can be:
  • 1 : Arabic numerals
  • a : Lower-case letters
  • A : Upper-case letters
  • i : Lower-case roman numerals
  • I : Upper-case roman numerals
  • + : Symbols
• {{label::Text}} Use label as the label.

Questions:

• Is there one numbering sequence, or one per format?
• What happens if two footnotes on the same page want to use the same label? Make one footnote by concatenating the text?

Anyway, send me your patch.

-- IanBygrave - 23 Aug 2008

That label format syntax is now implemented in V2.007.

The variable for setting the default is %FOOTNOTELABELFORMAT% and can be set sitewide, per-web, or per-page.

Formats NYI:

• + : Symbols
• x , X : Hexadecimal

-- IanBygrave - 24 Aug 2008

I think it should now be easy to implement a feature requested by DiabJerius on 01 Dec 2006 (see EndNotePluginDev).

• {{label::}} to refer to a previously created footnote without repeating the text.

-- IanBygrave - 24 Aug 2008

Ups, one should refresh the page before commenting.

-- FranzJosefGigler - 25 Aug 2008

With the new syntax footnotes like {{http://www.perlmonks.org/}} crash with a message Undefined_Label_Format

-- AndreLichtsteiner - 27 Aug 2008

Yes. Sorry. You could prepend some whitespace, or suggest a character other than ':' for the label format syntax.

-- IanBygrave - 27 Aug 2008

The {{http://www.perlmonks.org/}} problem reported by AndreLichtsteiner is fixed in v2.008.

-- IanBygrave - 31 Aug 2008

I've just noticed that FootNotePlugin interacts very badly with HolidaylistPlugin. The footnotes are rendered inside the holiday table!

-- IanBygrave - 12 Jan 2009