Russ Allbery > podlators > NOTES

Download:
podlators-2.5.3.tar.gz

Annotate this POD

CPAN RT

New  1
Open  2
Stalled  3
View/Report Bugs
Source  

Footnotes ^

Two POD elements are added to support footnotes:

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?

syntax highlighting: