The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

Footnotes

Two POD elements are added to support footnotes:

  • N<> interior sequenceF was already taken.Nested footnotes don't work correctly. I don't think they should be supported.

  • =footnote directive1

This method requires you to keep track of unique footnote IDs. It allows multiple paragraphs,0

  verbatim                                              paragraphs,

and format specific paragraphs.

I suppose this is neither here nor there, but I'm not a fan of multi-sentence (much less multi-paragraph) footnotes. If the information is important, why not work it into the main text or put it in the Appendix? If it isn't important, why include it at all?

But some people seem to love them. They put stories, jokes, code examples, detailed arguments, disclaimers, etc. in footnotes. As a matter of principle, I wish they were disallowed in POD. Unfortunately, it would then be impossible for Larry to write the next Camel in standard POD!You can embed footnotes in the multi-paragraph style, but I don't think it should be supported.

The most common use of the footnote is for short parenthetical statements:

  =head1 Why I love Perl.N<www.perl.com>

  [Insert reasons here]

which gets formatted:

  Why I love Perl.[1]

  [Insert reasons here]

  ___
  1
      www.perl.com

For the vast majority of footnotes, this is all you need to know. The pod2X translators take care of the details for putting footnotes in X. pod2latex uses \footnote, pod2html uses <a> tags, pod2text puts notes at the bottom of the document, etc.

There is a limitation to the interior sequence version of footnotes---they can't contain pod paragraphs.* A general solution for the problem would be to add a macro language to pod. I thought that it would be overkill.** Instead I added a footnote directive that associates footnote text with a specific footnote mark. For instance if you wanted to make the HTML footnote different from the text version you could do something like:

  =head1 Why I love Perl.N<12>

  [Insert reasons here]

  =footnote 12

  =for text

  www.perl.com

  =for html

  <a href="http://www.perl.com">The Perl web-site.</a>

  =footnote

First place a mark with the N interior sequence. Pod translators use the contents of the mark as a footnote ID which must match /^[\d*]+$/. Sometime after the mark is placed, use the footnote directive to start the footnote section for that footnote ID. Footnote sections are ended with another footnote directive. Note that the footnote ID is only used to tie a specific footnote mark to its text---the formatter is free to renumber (or re-mark) your footnotes.

Not to mention beyond my abilities to do right. :)

LaTeX doesn't allow \verb within footnotes, at least not without an optional package. (See http://www.tex.ac.uk/cgi-bin/texfaq2html?keyword=footnote&question=143)

This is an orphaned footnote. It's just sort of stuck in here with a footnote mark that doesn't go anywhere in the text. Does anyone know where, if anywhere, it makes sense to put these?

11 POD Errors

The following errors were encountered while parsing the POD:

Around line 20:

Deleting unknown formatting code N<>

Deleting unknown formatting code N<>

Around line 26:

Deleting unknown formatting code N<>

Around line 32:

Unknown directive: =footnote

Around line 34:

Deleting unknown formatting code N<>

Around line 51:

Unknown directive: =footnote

Around line 58:

Deleting unknown formatting code N<>

Around line 65:

Unknown directive: =footnote

Around line 89:

Deleting unknown formatting code N<>

Deleting unknown formatting code N<>

Around line 122:

Unknown directive: =footnote

Around line 126:

Unknown directive: =footnote

Around line 132:

Unknown directive: =footnote