5. Overview of initialization files content and loading

The initialization files are perl files, read as explained in Use initialization files for fine tuning. You don't need to know much of perl to do some simple changes in variable values, however, to be able to really take advantage of all the features of the initialization file, a good knowledge of perl is required.

In initialization file two kind of variables appear. These are normal variables (including arrays and hashes) and references on functions. The later permits the dynamic redefinition of functions used to produce the HTML manual. You should be able to change the value of some normal variables without a deep knowledge of perl, by looking at the existing examples. The possible mistakes in that case could be omitted ‘;’, and bad quoting.

Initialization file are loaded from the main program by the mean of a require, while in the Texi2HTML::Config namespace. This means that the namespace of the main program and the namespace of inititalization files are distinct, which ensures that no name clash should happen. The variables are declared with the our specifier, such that it should be possible to use the use strict pragma in the initialization file code.

To avoid messing with the variables in the main namespace all the global variables which could be of use in the init files are in the Texi2HTML namespace. Notice that the functions of the main program are still in the main namespace.

5.1 Setting the encodings

There are four encodings relevant for texi2html, they are associated with corresponding variables:

1. The encoding appearing in @documentencoding. The associated value overrides the $DOCUMENT_ENCODING variable value.
2. The texinfo files encoding, associated with the variable $IN_ENCODING. This variable is overriden when $DOCUMENT_ENCODING is set, if the encoding is supported by perl.
3. The out files encoding, associated with the variable $OUT_ENCODING. If not defined, the value of $ENCODING_NAME or $IN_ENCODING is used if one of these variables is set.
4. The encoding advertized in out files, associated with the variable $ENCODING_NAME. If unset the value of this variable is based on the other ENCODING variables, and if they are all undefined, the variable $DEFAULT_ENCODING is used.

The values for the encoding related variables are set in the default init_out function reference (see section Preparing the output).

In general the $DOCUMENT_ENCODING and $IN_ENCODING are set to the right values, and to force a given encoding for the output, the $ENCODING_NAME value may be set. The current default output encoding is UTF-8.

5.2 Redefining functions in initialization files

To redefine a function you must replace the corresponding funtion reference with a reference on your function. Thus you should write your function, give it a name you are certain it is unique in the Texi2HTML::Config namespace, and override the value of the function reference with your own function reference. When another function from the main program (or from another functions of an initialization file) calls the reference, your function will be used.

For example the function reference corresponding with the function called when doing an anchor is called $anchor. Thus if you want to override the corresponding function you could write:

# override the function reference
$anchor = \&my_own_function;

# the function reference now refers to
sub my_own_function {
# process arguments and return an html anchor
}

5.3 Conventions used for function prototypes

As the functions are defined by a reference name, we will always use the reference name in function prototypes. For the function arguments we will use \@array for a reference on an array and similarly \%hash for a reference on a hash.

Thus, the prototype for the function associated with the function reference ‘$formatting_function’ will be:

Function Reference: $text formatting_function $arg1 \@arg2

formatting_function takes as first argument $arg2, as second argument a reference on an array \@arg2 and returns the formatted text $text.

To redefined the corresponding function, you should write:

$formatting_function = \&my_formatting_function

sub my_formatting_function($ $)
{
    my $arg1 = shift;
    my $arg2 = shift;
    # prepare $formatted_text
    .....
    return $formatted_text
}

This document was generated by Derek Price on June, 5 2007 using texi2html 1.78.