15.2 Customizing Footnotes

NUMBER_FOOTNOTES and NO_NUMBER_FOOTNOTE_SYMBOL customization variables can be used to change the footnotes formatting. Redefinition of @footnote conversion reference and footnote formatting references is needed for further customization.

@footnote @-commands appearing in the Texinfo elements tree are converted like any other elements associated with @-commands (see Command Tree Element Conversion Functions). It is therefore possible to redefine their formatting by registering a user defined function.

To pass information on footnotes between the conversion function processing the @footnote command at the location they appear in the document and the functions formatting their argument elsewhere, two functions are available: register_footnote to be called where they appear in the document, and get_pending_footnotes to be called where they are formatted.

Function: $converter->register_footnote (\%element, $footnote_id, $foot_in_doc_id, $number_in_doc, $footnote_location_filename, $multi_expanded_region)

\%element is the footnote texinfo tree element. $footnote_id is the identifier for the location where the footnote arguments are expanded. $foot_in_doc_id is the identifier for the location where the footnote appears in the document. $number_in_doc is the symbol used to format the footnote in the document. $footnote_location_filename is the filename of the tree unit element of the footnote in the document. If the footnote appears in a region that is expanded multiple times, the information on the expansion is $multi_expanded_region (see Dynamic Converter Formatting Information).

register_footnote is normally called in the @footnote @-command conversion function reference. The default conversion function also call command_href to link to the location where the footnote text will be expanded (see Target Commands Links, Texts and Associated Commands).

Function: @pending_footnotes_information = $converter->get_pending_footnotes ()

Returns in @pending_footnotes_information the information gathered in register_footnote. Each of the array element in @pending_footnotes_information is an array reference containing the arguments of register_footnote in the same order.

The formatting of footnotes content is done by the format_footnotes_sequence formatting reference (see Specific formating Functions):

Function Reference: $footnotes_sequence format_footnotes_sequence ($converter)

Formats and returns the footnotes that need to be formatted. This function normally calls get_pending_footnotes. The default function also calls footnote_location_href (see Other Links, Headings and Associated Information for Special Elements) to link to the location in the document where the footnote appeared.

If footnotes are in a separate element unit (see Output Element Units), the default footnote special element body formatting function calls format_footnotes_sequence (see Special Element Body Formatting Functions).

If the footnotes are not in a separate element unit, or there is no separate element because there is only one tree unit element or no tree unit element, the format_footnotes_segment formatting reference is called when pending footnotes need to be formatted. This function reference can be replaced by a user defined function.

Function Reference: $footnotes_segment format_footnotes_segment ($converter)

Returns the footnotes formatted. In the default case, the function reference calls format_footnotes_sequence and also sets up a header with format_heading_text (see Basic Formatting Customization), using the customization variables FOOTNOTE_END_HEADER_LEVEL and the special footnotes element heading information (see Special Elements Information Customization).