PPTools/Ppgen/Footnotes

This page explains footnote and endnote handling in ppgen in more detail than the entry in the Ppgen Manual.

This guide assumes you have already identified and, if necessary, renumbered the project's footnotes as described in the Post-Processing FAQ.

Footnotes and Endnote Basics

There are three components to a footnote in a ppgen source file:

• The footnote reference in the text, normally a letter or number enclosed in square brackets: [A] or [1];
• The footnote text, identified with the .fn dot-command; and
• One or more optional landing zones, using the .fm dot-command.

Ppgen's footnote system is designed so that a single footnote in your source file can be displayed differently in the text and html versions.

A Simple Footnote

In its simplest form, a footnote looks like this:

The science or art of describing books has no technical term.[2]

.fn 2
The reader can refer to Notes and Queries, 4 Series IX, p. 8,
for some remarks on the inconvenient length of bibliographical words.
.fn-

The reference is [2]. The note itself begins with the .fn command, followed by the number (or letter) of the note and ends with the .fn- command.

This code as written will generate a note in the text, immediately after the paragraph, in both the text and html versions.

Landing Zones

For the text version, this simple note is probably fine, but in the HTML version, the recommendation is to move to the notes to the end of the chapter or the end of the book. In ppgen, we do this by creating a landing zone.

To create a landing zone, place a .fm ("footnote marker") dot command in your source file where you want the footnotes to appear--for example, at the end of the chapter, or in a separate "Notes" section at the end of the text. The marker looks like this:

.fm lz=h

The lz=h attribute tells ppgen to use this as a landing zone for footnotes in the HTML version. All footnotes in the file up to this .fm command will be placed here.

If you use a landing zone anywhere in the file, you must specify a landing zone for all notes in that output file (html or text). However, the other output file will be unaffected.

In other words, if you specify a landing zone in the html output:

• You must specify a landing zone for every note in the html version, but
• You do not need to specify landing zones for the text version; they will display where they are located in the text.

You can also specify different landing zones for the html and text versions--for example, placing text notes at the end of each chapter (with .fm lz=t) but html notes at the end of the entire book.

Command reference

The commands we use take a number of arguments:

.fn

The basic syntax of a .fn command is:

.fn ref [lz=here] 

where ref is the footnote number, letter, or other reference.

The optional here argument tells ppgen to place the footnote where it appears in the file, instead of waiting for the landing zone. It comes in three forms:

• lz=here applies to all output formats
• tlz=here applies only to text formats
• hlz=here applies only to HTML formats

Use this argument only if you have at least one landing zone for that type of file; otherwise ppgen will generate a run-time error.

.fm

The .fm defines a footnote marker, a separator between the footnotes and the rest of the text. It also defines a landing zone for previously defined footnotes that have not yet been rendered. The basic syntax is:

.fm lz=[value] rend=[value] rendafter=[value] 

All arguments are optional.

Landing Zones

The lz argument tells ppgen to establish a landing zone for footnotes: a place where ppgen will display any footnotes that have already been defined with a .fn command, but not yet displayed.

There are three possible values:

• t establishes a landing zone for the preceding footnotes when producing a text output file.
• h establishes a landing zone for the preceding footnotes when producing an HTML output file.
• th establishes a footnote landing zone for any kind of output file

If you do not include the lz argument, ppgen will not create a landing zone; it will simply draw the desired footnote marker. This is useful if you're not using landing zones at all, and simply want to insert a marker between text and notes.

Markers

The two arguments rend and rendafter control whether horizontal lines are displayed before or after the footnote block.

Rend controls whether a line appears before the note or notes. The possible values of rend are:

• th, which will generate the horizontal line for all output files. This is the default value.
• t or h, which will generate the horizontal line only on the corresponding output file (text or HTML).
• no or norend, which will suppress the horizontal line completely.

Rendafter controls whether a line appears after the notes; it is available only when landing zones are enabled and applies to the same output files as the landing zone. The parameters are:

• yes, which draws a horizontal line after the footnotes, and
• no, the default, which does not.

References

The third element of a footnote or endnote is the inline reference. In most cases, this is straightforward: it's a number, a capital letter, or a Roman numeral inside [square brackets].

However, there are two problems that can arise with references: ppgen can think something is a footnote reference when it's not, or, less commonly, ppgen doesn't recognize a footnote reference and treats it as ordinary text.

That shouldn't be a footnote!

Any time ppgen sees a number inside [square brackets], it's treated as a footnote reference. This can cause problems if your text uses brackets for other purposes. In this example:

44. Dates of the kings of England, in easy triplets, by a lady
Lond. [1874].

the date will be rendered in the HTML text as a superscript, with a link to a nonexistent footnote 1,874.

To avoid this, use a backslash to escape the opening square bracket:

\[1874].

This is only necessary with Arabic numbers; Roman numerals and letters are only flagged as footnotes if ppgen finds a .fn tag with the same label.

That should be a footnote!

In ppgen, footnote labels can contain only letters, numbers, and the following four additional characters:

- _ : -

It cannot contain spaces or other special characters like asterisks (*) or commas.

In most cases, this is all you need; either the notes will already be in this format or you will want to change them to simple Arabic numbers anyway. But in some specialised texts, a postprocessor may want to reproduce the text's references and notes exactly.

In these cases, your best bet is to use a temporary name that ppgen will recognize, then add an .sr command to replace it. For example, if your text uses "tn 1" to indicate a translator's note:

...the year 1540.[tn-1]

.fn tn_1
Old calendar.
.fn-

.sr th *tn_*tn *