---

8 Init File Calling at Different Stages ¶

Arbitrary user-defined functions may be called during conversion. This could be used, for example, to initialize variables and collect some @-commands text, and doing clean-up after the Texinfo tree conversion.

There are four places for user defined functions:

setup

Called right after completing main program customization information with converter specific customization information, but before anything else is done, including collecting the output files names and registering the customization variables pre-conversion values.

structure

Called after setting and determining information on CSS, output files and directories, document structure and associated directions, file names, labels and links for nodes, sectioning commands, special elements, footnotes and index entries.

init

Called after some gathering of global information on the document, such as titles, copying comment and document description, which require some conversion of Texinfo, right before the main output processing. At that point most of the information available from the converter is set (see Conversion General Information).

finish

Called after output generation is finished.

The function used to register a user defined functions is texinfo_register_handler:

Function: texinfo_register_handler ($stage, \&handler, $priority) ¶

$stage is one of the stages described just above. \&handler is a reference on the user defined function. $priority is an optional priority class.

To determine the order of user defined functions calls, the priority classes are sorted, and within a priority class the order is the order of calling texinfo_register_handler.

The call of the user defined functions is:

Function Reference: $status stage_handler ($converter, \%tree, $stage) ¶

$converter is a converter object. \%tree is the Texinfo tree root element. $stage is the current stage.

If $status is not 0 it means that an error occured. If $status is positive, the user defined functions should have registered an error or warning message, for example with document_error (see Error Reporting in User Defined Functions). If $status is negative, the converter will emit a non specific error message. If the $status is lower than -HANDLER_FATAL_ERROR_LEVEL or higher than HANDLER_FATAL_ERROR_LEVEL, the processing stops immediately. Default value for HANDLER_FATAL_ERROR_LEVEL is 100.