7.19 Bypassing normal formatting

It is possible to bypass completely the normal formatting of @-commands with braces and raw regions (@html, @tex, @xml… regions). In that case the @-commands and the text within are passed to a user defined function early, in a pass when no expansion of output takes place, called the collecting pass. Another user defined function is called during the output expansion phase.

Moreover, arbitrary user defined functions may be called between the different texinfo parsing and outputting passes. This could be used, for example to initialize some things before collecting the @-commands and their text, expanding them between the collecting and expansion phase and doing some cleaning after the expansion pass. These possibilities are used for the interface to LaTeX2HTML (see section Expanding @tex and @math regions using LaTeX2HTML), and the examples are taken from that use.

The @-commands that are keys of the %command_handler hash are collected in the collecting pass and expanded in the expansion pass using user defined functions. The associated value is a reference on a hash used to specify the user defined function references. The key of the hash reference are 'init' for the function reference called during the collecting pass, and 'expand' during the expansion pass. Here is an example for an @-command with braces:

$command_handler{'math'} =
     { 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
       'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
     };

And an example for a raw region @-command:

$command_handler{'tex'} =
     { 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
       'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
     };

The function references are called like:

Function Reference: $status $command_handler{'$command'}->{'init'} $command $text $count

$command is the @-command name, $text is the text appearing within the @-command. $count is a counter counting how many times this @-command appeared. $status is a boolean which should be true if the collecting was succesfull. If false the @-command and the text is discarded.

Function Reference: $result $command_handler{'$command'}->{'expand'} $command $count $state $text

$command is the @-command name, $count is a counter counting how many times this @-command appeared. $state is a reference on a hash containing many informations about the context. $text should be empty. $result is the expanded resulting text.

There are three places for user defined functions, associated with arrays:

@command_handler_init

The function references in that array are called before the collecting pass. At that time the information available is essentially the file names.

@command_handler_process

The function references in that array are called between the collecting pass and the expansion pass. At that time all the special @-commands have been collected as explained above but no output has been produced.

@command_handler_finish

he function references in that array are called after the end of the output generation.

Here is an example of these arrays use:

push @command_handler_init, \&Texi2HTML::LaTeX2HTML::init;
push @command_handler_process, \&Texi2HTML::LaTeX2HTML::latex2html;
push @command_handler_finish, \&Texi2HTML::LaTeX2HTML::finish;

Doku-Base