PPTools/Ppgen/Tutorial/Footnotes

Overview

The original ppgen support for footnotes remains available, but it has disadvantages when compared with the new "landing zone" support described in this article.

The original support works as follows:

1. When you start working on the file, footnote references in the text look like [1], [2], etc. or [A], [B], etc. or a mixture. Some numbers or letters may be repeated. To handle the footnotes you will generally need to renumber/rename each of them so each footnote is uniquely named. For numeric footnotes you can use a # for the number of each and ppgen will renumber them uniquely for you. (This remains true with the new support, too.)
2. Footnotes themselves appear at the bottom of the page that references them. You will probably move them so they are located at the end of the chapter where they occur, or you may move them all to the end of the book. Optionally you may put a .fm command before the relocated footnotes to provide a short horizontal line that will clearly separate the regular text from the footnote text.

That approach has at least two problems:

1. Once you have moved the actual footnote text to a new location, it is harder for you to find that text. In its original location you know the image number of the page in the book, and if you need to refer to the book you can do so easily. Once they are moved you no longer know what page they originally occurred on, and if you need to refer back to the book it's harder to find the right page.
2. You may decide, especially if you have a lot of footnotes, that you want them located differently in the text output file(s) than in the HTML output file. In the HTML it is easy for the user to click on a footnote reference and see the footnote text, and (in most cases) to then return to the footnote reference to keep reading. That is much harder in the text version(s). So, while it may be appropriate to put all the footnotes at the end of the book for the HTML version, you may want to place them elsewhere in the text version(s), perhaps immediately after the paragraph that referenced them, or at the end of the chapter. Unfortunately, to have them in one location in the text version(s) and another in the HTML you need to duplicate the text and physically put them in two locations, selected using ".if t" or ".if h". That is more complex to setup, and once you have duplicated the text you also need to make any subsequent corrections in two places. That makes continued development of the project harder, and may lead to errors where you make a correction to one version of a footnote but miss the other version, or change it in a different way.

Footnote Landing Zones

Starting with an earlier experimental version (but now in ppgen 3.48c or later) ppgen provides optional support to solve both of the problems mentioned above, through enhancements to the ".fm" and ".fn" commandees and to the handling of footnotes themselves (the ".fn" command). This new support allows you to either:

• leave the footnotes in their original source locations, but have them generated in different places in the text output file(s) and the HTML output file; or
• move the footnotes physically to a different location in the text (e.g., to the paragraph that references them) so they will appear there in the text output file(s), but still have them generated elsewhere in the HTML (e.g., at the end of a chapter or at the end of the book).

You request this new handling using options on the enhanced .fm (footnote mark) command. You may also exempt individual footnotes from this new processing using new operands (tlz/hlz/lz) on the .fn command.

Note: If you use footnote landing zones the purpose of the .fm commands changes. They are no longer optional, and any .fm commands must appear after the footnotes to which they apply.

Options on the .fm command

Ppgen now supports the following options on .fm:

 rend= 
   If you specify this optional parameter, you may use one of these values:
     no or norend, which will suppress the horizontal line completely
     t which will generate the horizontal line when producing a text output file but not when producing HTML
     h which will generate the horizontal line when producing the HTML output file but not when producing text
     th which will generate the horizontal line for all output files. This is the same as omitting rend= from the command.

 rendafter= 
   This operand is meaningful only when landing zone processing is enabled. If you specify this optional parameter
   you may use one of these values:
     no (default), which omits any horizontal line after the generated footnotes.
     yes, which causes generation of a horizontal line after any generated footnotes if one was generated before them.

 lz=
   The lz= option tells ppgen to establish a landing zone for footnotes: a place to which ppgen will move the footnotes that 
   preceded the .fm command and which have not been produced in the output yet.
   
   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

Ppgen now supports the following options on .fn, specified after the footnote number or #:

 lz=here or
 tlz=here or
 hlz=here or
 
   These options are meaningful only if landing zone processing is in effect. The form with "lz" applies to all output formats,
   while the form with "tlz" applies only to text output formats and the form with "hlz" applies only to the HTML output format.
 
   When one of these options is specified, then for the relevant output format ppgen will ignore landing zone processing for that
   specific footnote, and generate it in the output file where it was encountered rather than buffering it for later. This enables you
   to use landing zones for most footnotes in the file, but leave some where they occurred. For example, this might be useful if you
   have a table with a footnote and you want to keep that footnote with the table, but move the rest to the end of a chapter or to the
   end of the book.

Landing Zone processing

When it begins to produce an output file (text, or HTML) ppgen looks through the entire source file to see if there are any .fm (footnote mark) commands with a relevant lz= specification. Thus, when ppgen starts to produce a Latin-1 or UTF-8 text output file, it looks for .fm commands that specify lz=t or lz=th. If it does not find any such commands, then for that output file ppgen will use the original form of footnote handling, and skip using the landing zone support. This means that you might have, for example, the original form of footnote handling for the text but use the landing zone support for the HTML, or vice versa.

If the landing zone support is not active, then whenever ppgen encounters a footnote (.fn command) it will produce the footnote in the output file immediately, at that location.

However, once the landing zone support is activated for a particular output file, the processing changes. When ppgen finds a .fn command it will examine the command to see if that .fn specifies a relevant "lz=here", "tlz=here", or "hlz=here" operand (lz applies to all output formats, tlz to text output formats, hlz to the HTML output format). If the footnote has a relevant lz operand ppgen will produce it at that location as it would do in the absence of lz support. However, if the footnote does not have a relevant lz operand then ppgen will not produce it in the output immediately. Instead, it will save it in a temporary buffer area. As ppgen encounters additional footnotes without a relevant lz operand it will add them to the end of the buffer.

Eventually, ppgen will encounter a footnote mark (.fm) that contains a relevant lz= parameter (t for text output, h for HTML output, or th for both). Ppgen will ignore any .fm commands without lz= or with the wrong lz= value. When it encounters a footnote mark with the right lz= value ppgen will:

1. Generate the horizontal line, but only if rend= is not specified, or if rend= specifies the proper value (t for text, h for HTML). The line is always omitted if rend=no or rend=norend is specified on that .fm command. The line is also omitted if lz= is specified but there are no footnotes saved.
2. Generate all the saved footnotes at that spot in the output file
3. If the .fm contains the operand rendafter=y then ppgen will also generate a horizontal line after the generated footnotes if it generated one before them.
4. Clear the buffer of saved footnotes, so it is ready for the next footnotes that ppgen encounters.

At the end of processing for that output file, if ppgen still has saved footnotes, because footnotes occurred after the last .fm command that had a relevant lz= value, then ppgen will issue a warning message. It will not generate those footnotes, as it has no way to determine where you would want them.

Ppgen will then begin processing the next output file version, restarting its processing from the beginning as describd at the beginning of this section. It may get a different answer about whether landing zone support should be active or not, and will operate accordingly.

Scenarios

1. Suppose you would like all the footnotes to come out at the end of the file for both text and HTML, but you want to leave them in their original positions in the source for ease of editing and reference while preparing the project. You might:

1. Leave each footnote where you found it when you started the project (though you will probably still need to adjust the numbering).
2. Add one .fm command at the end of the file where you would like all the footnotes generated. Specify lz=th on this .fm command. Both text and HTML output will use the landing zone support.

2. Suppose you would like the footnotes to come out at the end of chapters in the text output, but at the end of the book in the HTML output. You might:

1. Leave each footnote where you found it when you started the project (though, again, you will need to adjust the numbering).
2. At the end of each chapter, add a .fm command with the lz=t operand. The text output will use landing zones, and will have one per chapter. Each chapter's landing zone will contain the footnotes for that chapter.
3. At the end of the book, add a .fm command with the lz=h operand. The HTML output will also use landing zones, but will have only the one which will contain all of the footnotes for the entire book.

3. Suppose you decide to place footnotes in the text output at the end of the paragraph that references them, but to put all the footnotes at the end of the book in the HTML. In that case, you could use this approach:

1. Physicaly move each footnote to just after the proper paragraph, optionally with a .fm without operands before the first one for each paragraph. The text output will be using the original footnote support. (You will still need to adjust footnote numbers.)
2. Add one .fm command specifying lz=h at the end of the source file where you would like all the footnotes generated for the HTML version. The HTML output will use the landing zone support.