3.1 Init File Namespace ¶

Initialization file are loaded from the main program in the Texinfo::Config namespace. This means that the namespace of the main program and the namespace of initialization files are distinct, which minimizes the chance of a name clash.

It is possible to start init files with:

package Texinfo::Config;

It is not required, but it may help some debugging tools determine in which namespace the code is run.

In the Texinfo::Config namespace, the functions names beginning with ‘texinfo_’, ‘GNUT_’ and ‘_GNUT_’ are reserved. User defined functions in init files should never begin with those prefixes.

The HTML converter is not available directly in the init files namespace, instead it is passed to functions defined in init files that are registered as functions to be called from the converter. See User Defined Functions.

3.2 Getting Build Constants ¶

Some constants are set independently of the output format for a Texinfo build. They are available through Texinfo::Common::get_build_constant:

Function: $value = Texinfo::Common::get_build_constant ($name) ¶

Retrieve build constant $name value.

Defined build constants:

PACKAGE ¶

PACKAGE_CONFIG ¶

PACKAGE_AND_VERSION ¶

PACKAGE_AND_VERSION_CONFIG ¶

PACKAGE_NAME ¶

PACKAGE_NAME_CONFIG ¶

PACKAGE_VERSION ¶

PACKAGE_VERSION_CONFIG ¶

PACKAGE_URL ¶

PACKAGE_URL_CONFIG ¶

Texinfo package name and versions. Values of build constants without ‘_CONFIG’ appended are set by configure. Similar customization variables exist with the same value set in the default case from the main program, with values that can be modified.

The values of the build constants with ‘_CONFIG’ appended are duplicate of the values of the build constants without ‘_CONFIG’².

3.3 Managing Customization Variables ¶

The basic operations on customization variables are to set and retrieve their values.

The customization variables also valid in the main program out of the HTML converter are handled differently if their associated values are strings or arrays. Conversely, customization variables only relevant for the conversion phase set in the main program are always set by associating a string, an array reference or a hash references to customization variables in the same way.

This section describes customization variables set in the main program. These variables are in general passed to converters. It is also possible to set customization variables in the converters only, not in the main program. This is explained later on (see Setting and Getting Conversion Customization Variables).

• Setting Main Program String Variables
• Modifying Main Program Array Variables
• Setting Converter Variables in Main Program
• Getting Main Program Variables Values

texinfo_set_from_init_file('documentlanguage', 'fr');

texinfo_set_from_init_file('SPLIT', 'chapter');

texinfo_set_from_init_file('NO_CSS', 1);

my @SECTION_BUTTONS =
  (
   \&singular_banner,
   'Back', 'Forward',   'FastBack', 'FastForward',
   'Up', 'Top', 'Contents', 'Index', 'About'
  );

texinfo_set_from_init_file ('SECTION_BUTTONS', \@SECTION_BUTTONS);

if (texinfo_get_conf('footnotestyle') eq 'separate') { ... }

3.4 Init File Loading Error Reporting ¶

If an error or a warning should be emitted when loading an init file, before the conversion, use texinfo_register_init_loading_error for an error and texinfo_register_init_loading_warning for a warning.

Function: texinfo_register_init_loading_error ($message) ¶

Function: texinfo_register_init_loading_warning ($message) ¶

Cause an error message or a warning message based on $message to be output, taking into account options related to error reporting such as --force or --no-warn.

Errors or warning emitted from user defined functions should use the converter (see Error Reporting in User Defined Functions).

4.1 Init File Expansion Contexts: Normal, Preformatted, Code, String, Math ¶

Output formatting simple customization needs to be specified especially for different formatting contexts. There are five expansion contexts of interest:

normal context ¶

Paragraphs, index entries, tables, ...

preformatted context ¶

When spaces between words are kept. For example, within the @display (see @display in Texinfo) and @example environments (see @example in Texinfo), and in menu comments. The preformatted regions are usually rendered using <pre> elements in HTML.

code context

When quotes and minus are kept. In particular ---, `` and other similar constructs are not converted to dash and quote special characters. For example, in @code or @option commands (see Useful Highlighting in Texinfo).

math context ¶

Math (see @math in Texinfo). Code or preformatted specifications are often used for math too. In those cases, there is no way to separately specify the formatting in math context.

string context ¶

When rendering strings without formatting elements, for example in titles. The string context allows for limited formatting, typically without any element when producing HTML or XML, so the value can be used in an attribute. XML entities can be used in strings.

It is worth mentioning that in some cases, in particular for file names, plain text can also be used in conversion. There is no associated context in the converter, so the conversion to plain text is usually performed by converting a Texinfo elements tree outside of the main conversion flow.

4.2 Simple Customization for Commands Without Arguments ¶

These commands include those whose names are a single nonletter character, such as @@, and those with a normal alphabetic name but whose braces should be empty, such as @TeX{} and @AA{}.

To change the formatting of a command, the functions is texinfo_register_no_arg_command_formatting:

Function: texinfo_register_no_arg_command_formatting ($command_name, $context, $text, $html_element, $translated_string_converted, $translated_string_to_convert) ¶

$command_name is the @-command name, without the leading @. $context is ‘normal’, ‘preformatted’ or ‘string’. There is no separate math context, ‘preformatted’ should be used for math context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math. If $context is undef, the ‘normal’ context is assumed.

The remaining arguments determine the formatting. If $text is set, the corresponding text is output when the @-command is formatted. $text can contain HTML elements if needed. If $html_element is set, the text is enclosed between the $html_element element opening and the element closing. If $translated_string_converted is set, the corresponding text is translated when the document language changes and used as text. $translated_string_converted should already be HTML. If $translated_string_to_convert is set, the corresponding text is translated when the document language changes and converted from Texinfo code to HTML. Since the conversion is done in the appropriate context, $translated_string_to_convert should only be set for the ‘normal’ context. See (texi2any_internals)Texinfo::Translations METHODS.

It is not required to set values for all the contexts. If preformatted context output is not set, normal context output is used. If string context output is not set, preformatted context output is used.

For example, if you want ­ to be output for @- in normal, preformatted (and math) and string context, call

texinfo_register_no_arg_command_formatting('-', undef, '­');

If you want “<small>...</small>” to be output for @enddots in normal context and ... to be output in other contexts, call

texinfo_register_no_arg_command_formatting('enddots',
                                           'normal', '...', 'small');
texinfo_register_no_arg_command_formatting('enddots',
                                           'preformatted', '...');

If you want “error-->” to be used for @error in every context, with a translation when the document language changes, call

texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
                                           'error-->');

If you want “is the same as” to be used for @equiv, translated when the document language changes, and converted from Texinfo to HTML in the context of the translation, call

texinfo_register_no_arg_command_formatting('equiv', undef, undef, undef,
                                 undef, 'is the @strong{same} as');

See Translated Strings Customization for customization of translated strings.

4.3 Simple Customization for Simple Commands with Braces ¶

• Customization of Commands Converting to Uppercase
• Simple Output Customization for Simple Commands with Braces

texinfo_register_upper_case_command('sc', 0);
texinfo_register_upper_case_command('var', 1);

texinfo_register_style_command_formatting('sansserif', 'code', 0,
                                          'normal');
texinfo_register_style_command_formatting('sansserif', 'code', 1,
                                          'preformatted');

foreach my $context ('normal', 'preformatted') {
  texinfo_register_style_command_formatting ('t', undef,
                                             undef, $context);
}

4.4 Simple Customization of Accent Commands ¶

You can modify the formatting of accent commands such as @', @ringaccent or @dotless by selecting HTML general features, to output numeric entities or characters (see HTML Features Customization in Texinfo).

You can also change how accented commands are converted to named entities. The accent named entities are obtained by combining a letter to be accented, such as ‘e’ and a postfix based on the accent command name, for example ‘acute’ for the acute accent @'. For example, ‘@'e’ is converted to the ‘é’ named entity in the default case.

The association of accent @-command and named entity postfix and the list of letters that can be prepended can be changed with texinfo_register_accent_command_formatting:

Function: texinfo_register_accent_command_formatting ($accent_command_name, $entity_postfix, $letters) ¶

$accent_command_name is a Texinfo accent formatting @-command name, $entity_postfix is a string corresponding to the accent command that is postpended to the letter accent argument. $letters is a string listing the letters that can be combined with the $entity_postfix. If $entity_postfix or $letters is an empty string, numeric entities are used instead of named entities.

For example, with the following code, @dotless{i} should be converted to ı, and @dotless{j} to &jnodot;. Other letters than ‘i’ and ‘j’ in argument of @dotless should not be combined into a named entity with that example.

texinfo_register_accent_command_formatting('dotless', 'nodot', 'ij');

4.5 Simple Customization of Containers ¶

Texinfo tree elements that are not text container nor directly associated with an @-command can have information set on their formatting. The first piece of information is whether their contents should be considered in code context (see Init File Expansion Contexts: Normal, Preformatted, Code, String, Math). The other piece of information is the type of preformatted environment they are, analogous with the @-command names of @example or @display³.

The function used is texinfo_register_type_format_info:

Function: texinfo_register_type_format_info ($type, $code_type, $pre_class_type) ¶

$type is the type of the container. If $code_type is set, the container contents are assumed to be in code context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math. If $pre_class_type is set, the HTML <pre> elements class attribute are based on $pre_class_type, if there are such HTML elements output for preformatted content of $type containers.

For example, to set content appearing in-between node links in @menu, which is in the menu_comment container type to be formatted in a code context, with preformatted type ‘menu-between’, use:

texinfo_register_type_format_info('menu_comment', 1, 'menu-between');

See (texi2any_internals)Texinfo::Parser Types of container elements, for a description of container types.

5.1 Output Units ¶

We will call the main unit of output documents a document output unit. An output unit’s association with output files is determined by the split options (see Splitting Output in Texinfo). This section describes precisely how these output units work, with details for customization.

The output units are:

Normal output units ¶

These are composed of normal sections and nodes. Usually a node is associated with a following sectioning command, while a sectioning command is associated with a previous node; they both together make up the output unit. Either the node or the sectioning command is considered to be the main element component, depending on the values of the customization variables USE_NODES (see HTML Output Structure Customization in Texinfo).

For example, when generating Info, the nodes are the main elements; when generating HTML, either case may happen (see Two Paths in Texinfo).

Top output unit ¶

The top output unit is the highest output unit in the document structure. If the document has an @top section (see @top Command in Texinfo), it is the output unit associated with that section; otherwise, it is the output unit associated with the document’s @node Top (see The Top Node in Texinfo). If there is no @node Top, the first output unit in the document is the top output unit. The Top output unit is also a normal output unit.

Miscellaneous output units ¶

The remaining output units are associated with different files if the document is split, and also if MONOLITHIC is not set (see ‘texinfo’ in Texinfo). There are four such miscellaneous output units, also called special output units:

1. Table of contents
2. Short table of contents, also called Overview
3. Footnotes page
4. About page

More details:

• The Table of contents should only be formatted if @contents is present in the document.
• Similarly the Short table of contents should only appear if @shortcontents or @summarycontents is present.
• The customization variables contents and shortcontents may be set to trigger the output of the respective output units.
• If CONTENTS_OUTPUT_LOCATION is set to ‘separate_element’, the Table of contents and Short table of contents output units are separate (see Contents and Short Table of Contents Customization). Otherwise the Table of contents and Short table of contents are directly included within the document, at locations depending on the specific CONTENTS_OUTPUT_LOCATION value (see ‘texinfo’ in Texinfo.
• When generating HTML, the Footnotes page should only be present if the footnotes appear on a separate page (see Footnote Styles in Texinfo). However, a footnote output unit is present if the document is not split.
• The About page shouldn’t be present for documents consisting of only one sectioning element, or for monolithic documents without navigation information, or if DO_ABOUT is not set.

It is common not to have anything but normal output units, especially in case of monolithic output.

A last type of output units exist, “virtual” output units corresponding to directions to external manual nodes. They are not part of the output, but can be used in directions. They are often referred to as external node units or external manual units. These units do not exist in the document output, therefore there are no functions called to format those output units. They can appear in directions formatting (see Navigation Panel Button Formatting).

5.2 Directions ¶

A variety of data items, called output units directions, are associated with output units. They may be used in the formatting functions, and/or associated with a button (see Simple Navigation Panel Customization).

Each output unit direction has a name and a reference to the unit they point to, when such an unit exists. The unit is either a global unit (for example, the Top output unit) or relative to the current output unit (for example, the next output unit). Such relative output units are determined with respect to the document structure defined by the section structuring commands (@chapter, @unnumbered…) or by the nodes if the node pointers are specified on @node lines or in menus (see Two Paths in Texinfo).

Here is the list of global output units directions:

‘ ’

An empty button.

Top

Top output unit.

First

First output unit in reading order.

Last

Last output unit in reading order.

About

About (help) page.

Contents

Table of contents.

Overview

Overview: short table of contents.

Footnotes

Corresponds to the Footnotes output unit (see Output Units).

Index

The first output unit with @printindex.

Here is the list of relative output units directions:

This

The current output unit.

Forward

Next output unit in reading order.

Back

Previous output unit in reading order.

FastForward

Next chapter output unit.

FastBack

Beginning of this chapter, or previous chapter if the output unit corresponds to a chapter.

Next

Next section output unit at the same level.

Prev

Previous section output unit at the same level.

Up

Up section.

NodeNext

Next node output unit.

NodeForward

Next node output unit in node reading order.

NodeBack

Previous node output unit in node reading order.

NodePrev

Previous node output unit.

NodeUp

Up node output unit.

Relative direction are each associated with a variant, with ‘FirstInFile’ prepended, which points to the direction relative to the first output unit in file. For example, FirstInFileNodeNext is the next node output unit relative to the first output unit in file. The ‘FirstInFile’ directions are usually used in footers.

• Output Unit Direction Information Type
• Direction Strings

5.3 Direction Strings Customization ¶

The direction strings are used in the default case in navigation panel formatting, therefore replacing their values is a way to customize headers. They are also used in the About special unit formatting (see About Special Output Unit Customization). The direction strings can be customized with texinfo_register_direction_string_info:

Function: texinfo_register_direction_string_info ($direction, $type, $converted_string, $string_to_convert, $context) ¶

$direction is a direction (see Directions), $type is the type of string (see Direction Strings). The other arguments are optional. $context is ‘normal’ or ‘string’. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math. If $context is undef, the ‘normal’ context is assumed.

$converted_string is the string, already converted to HTML that is used for the specified context. If the ‘normal’ context $converted_string only is specified, the same string will be used for the ‘string’ context.

Alternatively, $string_to_convert can be specified to set the string to the corresponding Texinfo code after translation and conversion to HTML. In that case, the context is ignored, as it will be set at the time of the conversion.

$string_to_convert is ignored for special strings that do not need to be translated and cannot contain Texinfo @-commands (‘accesskey’, ‘rel’ and ‘example’). $string_to_convert is also ignored if $converted_string is set for any context.

For example, to set the ‘Up’ ‘button’ to be translated as ‘Higher’, use:

texinfo_register_direction_string_info('Up', 'button', undef, 'Higher');

5.4 Simple Navigation Panel Customization ¶

The navigation panel is the line of links (and labels) that typically appears at the top of each node, so that users can easily get to the next node, the table of contents, and so on. It can be customized extensively.

You can set the ICONS customization variable to use icons for the navigation panel. Setting ICONS is necessary but not sufficient to get icons for direction buttons since no button image is specified in the default case. The ACTIVE_ICONS and PASSIVE_ICONS customization variables need to be set in addition:

ACTIVE_ICONS ¶

PASSIVE_ICONS ¶

Hash references with output unit directions as key (see Directions) and button image icons as values. ACTIVE_ICONS is used for directions actually linking to an output unit, and PASSIVE_ICONS are used if there is no output unit to link to. The button images are interpreted as URLs.

Several arrays and hashes enable even more precise control over the navigation panel buttons and their display. They can be set as customization variables with texinfo_set_from_init_file. See Setting Main Program String Variables.

The following customization variables arrays determine the buttons present in the various navigation panels:

SECTION_BUTTONS ¶

Specifies the navigation panel buttons present at the beginning of sectioning elements in the case of section navigation being enabled or if split at nodes. Specifies the navigation panel buttons present at the page header if split at section and there is no section navigation.

SECTION_FOOTER_BUTTONS ¶

CHAPTER_FOOTER_BUTTONS ¶

NODE_FOOTER_BUTTONS ¶

These arrays specify the navigation panel buttons present in the page footer when the output is split at sections, chapters or nodes, respectively.

CHAPTER_BUTTONS ¶

Specifies the buttons appearing at the page header if split at chapters and there is no section navigation.

MISC_BUTTONS ¶

Specifies the buttons appearing at the beginning of special output units and, if the output is split, at the end of such units.

LINKS_BUTTONS ¶

Used for <link> elements if they are output in the HTML <head>.

TOP_BUTTONS ¶

TOP_FOOTER_BUTTONS ¶

Specifies the buttons used in the top output unit (see Output Units). TOP_BUTTONS buttons are used for the header and TOP_FOOTER_BUTTONS are used for the footer.

Each array specifies which buttons are included, and how they are displayed. Each array item is associated with a button of the navigation panel from left to right. The meaning of the array item values is the following:

string with an output unit direction

If icons are not used, the button is a link to the corresponding output unit whose text is the text direction string (see Direction Strings), surrounded by ‘[’ and ‘]’. If the direction is ‘ ’, the ‘[’ and ‘]’ are omitted.

If icons are used, the button is an image whose file is determined by the value associated with the output unit direction in the ACTIVE_ICONS variable hash if the link leads to an output unit, or in the PASSIVE_ICONS variable hash if there is no output unit to link to. If there is a link to the output unit, the icon links to that output unit. The button name and button description are given as HTML attributes to have a textual description of the icon. The corresponding strings correspond to the button direction string for the button name and the description for a more detailed description (see Direction Strings).

function reference

The functions is called with one arguments, the converter object. The function should return two scalars, the button text and a boolean set if a delimiter is desired before the button.

scalar reference

The scalar value is printed.

array reference of length 2

Here, the first array item should be a an output unit direction. The text of the link depends on the second array item.

reference to a text string

A link to the output unit associated with the output unit direction is generated with the corresponding text used for the text link.

reference to a function

The functions is called with three arguments, the converter object, the output unit direction and the source Texinfo tree element (possibly undef). The function should return two scalars, the button text and a boolean set if a delimiter is desired before the button.

No delimiter is printed before the first button. Leading space buttons mixed with directions not found may be omitted of the navigation panel output.

If the customization variable USE_ACCESSKEY is set, the accesskey attribute is used in navigation. The accesskey direction string is then used for the accesskey attributes (see Direction Strings).

Similarly, if the USE_REL_REV customization variable is set, the rel attribute is used in navigation. In that case the rel direction string is used for the rel attribute (see Direction Strings).

6.1 User Defined Functions are Registered ¶

User defined functions are always passed as a code reference to a registering function, together with a string describing what the function formats. In the following made up example, my_formatting_function is passed as a function reference \&my_formatting_function to the fictitious registering function texinfo_register_some_formatting, with the string specifying the formatting done by the function being ‘format_thing’:

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

texinfo_register_some_formatting ('format_thing', \&my_formatting_function);

As such functions are defined by a reference name associated with a string we will always use the string in function prototypes. For the function arguments we will use \@array to indicate a reference to an array (a.k.a. list, in Perl terminology), \%hash for a reference to a hash and \&function for a reference on a function.

To illustrate these conventions, here is the prototype for the function associated with ‘format_thing’:

Function Reference: $text format_thing ($arg1, \@arg2)

A function reference associated with ‘format_thing’ has a first argument $arg1, a second argument a reference to an array \@arg2, and returns the formatted text $text.

6.2 Converter Object and Conversion Functions ¶

The first argument of most, if not all user defined function is a converter object. This object gives access to methods to get information on the conversion context and to methods useful for the conversion, both as an HTML converter and as a generic Texinfo::Convert::Converter (see (texi2any_internals)Texinfo::Convert::Converter Helper methods). The converter can be used for error reporting by using Texinfo::Convert::Converter methods. See Error Reporting in User Defined Functions on error reporting. The converter can also be used for in-document strings translation. See Translations in Output and Customization on translated strings in output.

7.1 Error Reporting in User Defined Functions ¶

To report an error or a warning in a user defined function, use the methods of Texinfo::Convert::Converter through a converter object (see Converter Object and Conversion Functions).

To report a warning or an error not specific of an element conversion, use converter_document_warn or converter_document_error:

Function: $converter->converter_document_error ($text, $continuation) ¶

Function: $converter->converter_document_warn ($text, $continuation) ¶

Register a document-wide error or warning. $text is the error or warning message.

The optional $continuation argument, if set, conveys that the message is a continuation of the previous registered message.

To report a warning or an error in element conversion, use converter_line_warn or converter_line_error

Function: $converter->converter_line_error ($text, \%location_info, $continuation) ¶

Function: $converter->converter_line_warn ($text, \%location_info, $continuation) ¶

Register a warning or an error. $text is the text of the error or warning. The \%location_info holds the information on the error or warning location. The \%location_info reference on hash may be obtained from Texinfo elements source_info keys.

The optional $continuation argument, if set, conveys that the message is a continuation of the previous registered message.

Note that registering an error does not stop the processing of the Texinfo tree.

See (texi2any_internals)Texinfo::Convert::Converter Registering error and warning messages for the converter module documentation on errors and warning messages registration.

7.2 Setting and Getting Conversion Customization Variables ¶

The customization variables values set during the conversion process may be different from the main program customization variables. The general rule is that variables set in the main program, in particular from init files, are passed to the converter. Some variables, however, only appear in the converter. Some variables are also set in the converter based on the main program customization variables. Finally, some variables should be set or reset during conversion, in particular when converting the tree representing the Texinfo document, when expanding the tree element corresponding to @-commands associated with customization variables (see Customization Variables for @-Commands in Texinfo).

The functions described here should be used in user defined functions, but should not be used out of functions. Conversely, the similar functions used to set customization variables from init files without a converter should not be used in functions, but should be used out of functions in init files (see Managing Customization Variables).

To get the value of a variable in a converter $converter, the function is get_conf:

Function: $result = $converter->get_conf ($variable_name) ¶

$variable_name is the name of the variable; its value in the converter $converter (possibly undef) is returned.

For example:

my $footnotestyle = $converter->get_conf('footnotestyle');

To set a variable in a converter $converter, the function is set_conf:

Function: $converter->set_conf ($variable_name, $variable_value) ¶

$variable_name is the name of the variable; its value in the converter $converter is set to $variable_value. The $variable_name value will not be overidden if it was set from the command line or from an init file.

For example:

$converter->set_conf('footnotestyle', 'separate');

Some customization variables, in particular those associated with @-commands, can be reset to the value they had before starting the conversion. For example, they are reset in order to obtain their value before the conversion. Thet are also reset to the value they had before starting the conversion when their value at the end of the preambule or at the end of the document is needed, but there are no @-commands at those locations in the Texinfo manual. If a value set by set_conf is intended to be found when the customization variable value is reset, set_conf should be called early. For example, when called from a user-defined function called at different stage, it should be called in the ‘setup’ stage (see Init File Calling at Different Stages).

The values set in converter with set_conf will not override command-line set customization variables, nor variables set early in init files. This is the expected behaviour, in particular when the values are set from the document. In the rare cases when overriding the customization would be needed, the force_conf function can be used:

Function: $converter->force_conf ($variable_name, $variable_value) ¶

$variable_name is the name of the variable; its value in the converter $converter is set to $variable_value, overriding any previous value.

7.3 Encoding and Decoding File Path Strings ¶

• Encoding File Path Strings
• Decoding File Path Strings

use Encode qw(encode);

....

my ($encoded_file_path, $encoding)
  = $converter->encoded_output_file_name($file_name);

my $fh = open($encoded_file_path);

.....

my $call_start = "command --set '$action' ";
my $encoding = $converter->get_conf('MESSAGE_ENCODING');
if (defined($encoding)) {
  $encoded_call_start = encode($encoding, $call_start);
} else {
  $encoded_call_start = $call_start;
}
my $encoded_call = $encoded_call_start . $encoded_file_path;
my $call = $call_start . $file_name;
if (system($encoded_call)) {
 $converter->document_error($converter,
     sprintf(__("command did not succeed: %s"),
            $call));
}

my $macro_expand_fname = $converter->get_conf('MACRO_EXPAND');
my $encoding = $converter->get_conf('COMMAND_LINE_ENCODING');
if (defined($encoding)) {
  $macro_expand_fname = Encode::decode($encoding, $macro_expand_fname);
}

7.4 Protection of URLs ¶

URLs need to be “percent-encoded” to protect non-ASCII characters, spaces and other ASCII characters. Percent-encoding also allows to have characters be interpreted as part of a path and not as characters with a special role in URLs. For example, ‘?’ has a special role in URLs as it starts a query string. To have it considered as part of a file path, instead of a marker of the beginning of a query, it needs to be percent encoded.

Convenience functions are provided for URL protection. To protect a whole URL, in which characters with a special role in URL are left as is, use url_protect_url_text. To protect file path in URL, including characters with a special role in URLs, use url_protect_file_text.

Function: $protected_url = $converter->url_protect_url_text($input_string) ¶

Percent-encode $input_string, leaving as is all the characters with a special role in URLs, such as ‘:’, ‘/’, ‘?’, ‘&’, ‘#’ or ‘%’ (and a few other). HTML reserved characters and form feeds protected are also protected as entities (see format_protect_text). This is typically used on complete URLs pointing to diverse internet resources, such as the @url URL argument.

for example

return $converter->html_attribute_class('a', ['myurl'])
 .' href="'.$converter->url_protect_url_text($url)."\">$text</a>";

Function: $protected_path = $converter->url_protect_file_text($input_string) ¶

Percent-encode $input_string leaving as is character appearing in file paths only, such as ‘/’, ‘.’, ‘-’ or ‘_’. All the other characters that can be percent-protected are protected, including characters with a special role in URLs. For example, ‘?’, ‘&’ and ‘%’ are percent-protected. HTML reserved characters and form feeds protected are also protected as entities (see format_protect_text). This is typically used on file names corresponding to actual files, used in the path portion of an URL, such as the image file path in @image.

For example

$converter->html_attribute_class('img', [$cmdname])
   . ' src="'.$converter->url_protect_file_text($image_file)."\");

8.1 Customizing Output File Names ¶

You can specify the output file or directory, intermediate directories and file extension with customization variables (see File Names and Links Customization for HTML in Texinfo).

Two function references registered with texinfo_register_file_id_setting_function enable further customization. The first, node_file_name is used to customize the nodes files names.

Function Reference: $node_file node_file_name ($converter, \%node_element, $file_name) ¶

$converter is a converter object. \%node_element is the Texinfo tree element corresponding to the @node. $file_name is the node file name that has been already set. The function should return the node file name ($node_file).

The other function reference, unit_file_name, is used to customize the file names associated with each normal output unit (see Output Units).

Function Reference: ($file, $path) unit_file_name ($converter, \%output_unit, $file_name, $file_path) ¶

$converter is a converter object. \%output_unit is the output unit. $file_name is the file name that has been already set. $file_path is the file path that has been already set. $file_path is ‘undef’ if the file is relative to the output directory, which is the case if the output is split. The function should return the file name for the output unit, $file, and the file path for the output unit, $path, which should be ‘undef’ if the file path is to be constructed by putting $file in the destination directory.

In the user defined functions, the information that an output unit is associated with @top or @node Top may be determined with:

$converter->unit_is_top_output_unit(\%output_unit);

The information on tree elements may be interesting for those functions (see Texinfo Tree Elements in User Defined Functions). The extra key associated_section of a node element and associated_node of a sectioning command element may also be useful.

The file name associated with a sectioning command is set together with the target, and is described in the next section.

8.2 Customizing Output Target Names ¶

Similar to file names, so-called target and id names may be set. The id is placed where the item is located, while the target is used to construct references to that item. The id and target are the same. A function used to set both target and file name is also described here.

The following function reference is for target items (nodes, anchors, floats), including for external manuals:

Function Reference: $target label_target_name ($converter, $normalized, \%element, $default_target) ¶

$converter is a converter object. $normalized is the normalized node name, \%element is a reference on a Texinfo tree command label element whose contents correspond to the node name. $default_target is the target that has been already set. The function should return the target ($target).

The element corresponding to the label can be found with label_command if the label corresponds to an internal reference (see Target Tree Element Link):

my $element;
$element = $converter->label_command($normalized)
  if (defined($normalized));

For sectioning commands, in addition to the sectioning command target, targets for the sectioning command in table of contents and in short table of contents are needed. The following function reference is for sectioning command related target and file name:

Function Reference: ($target, $target_contents, $target_shortcontents, $file) sectioning_command_target_name ($converter, \%section_element, $default_target, $default_target_contents, $default_target_shortcontents, $file_name) ¶

$converter is a converter object. \%section_element is the Texinfo element corresponding to the sectioning command.

$default_target, $default_target_contents and $default_target_shortcontents are the targets that have been already set for the sectioning element and the sectioning element in table of contents and in short table of contents. $file_name is the file name that has been already set.

The function should return the $target, $target_contents and $target_shortcontents sectioning element target and sectioning element in table of contents and in short table of contents targets, and the file name for the sectioning element ($file).

8.3 Customizing External Node Output Names ¶

In the default case references to external nodes are set as described in the Texinfo manual (see HTML Xref in Texinfo). You can specify external node manuals URLs in cross-references customization files (see HTML Xref Configuration in Texinfo). You can also set a base directory, the Top node file target, the extension and other overall references to external nodes formatting with customization variables (see File Names and Links Customization for HTML in Texinfo).

If the external reference is not already ignored because of IGNORE_REF_TO_TOP_NODE_UP, two function references give full control over the external node target output names, with external_target_split_name if the external target is considered to be split, and external_target_non_split_name if the external target is non split.

Function Reference: ($target, $host_directory, $file_name) external_target_split_name($converter, $normalized, \%element, $default_target, $default_host_directory, $default_file_name) ¶

$converter is a converter object. $normalized is the normalized node name, \%element is a reference on an element containing information on the external node.

$default_target, $default_host_directory and $default_file_name are the target, host and directory URL part and file name URL part that have been already set.

The function should return the $target, $host_directory and $file_name URL parts.

Function Reference: ($target, $host_directory_file) external_target_non_split_name($converter, $normalized, \%element, $default_target, $default_host_directory_file) ¶

$converter is a converter object. $normalized is the normalized node name, \%element is a reference on an element containing information on the external node.

$default_target is the target and $default_host_directory_file is the host and file name part of the URL that have been already set.

The function should return the $target and $host_directory_file URL parts.

8.4 Customizing Special Elements Output Names ¶

For special output units file and target (see Output Units), the function reference is:

Function Reference: ($target, $file) special_unit_target_file_name ($converter, \%output_unit, $default_target, $file_name) ¶

$converter is a converter object. \%output_unit is the special output unit hash. $default_target is the target that has been already set, and $file_name is the file name that has been already set. The function should return the $target and $file.

To determine the variety of the special output unit processed, the output unit special_unit_variety hash key can be used. See Table 16.1.

10.1 Specific HTML Constructs Formatting Functions ¶

A few specific HTML constructs should be formatted using particular functions: elements with classes, “void elements” without end tag and non breaking spaces.

• Formatting HTML Element with Classes
• Closing Lone HTML Element
• Substituting Non Breaking Space

my $open = $converter->html_attribute_class('span', ['math-arg']);
my $arg_result = $open.'>'.$arg.'</span>'
  if ($open ne '');

my $result = $converter->html_attribute_class('em', [$cmdname, 'jax_p'])
   . '>' . $arg_result . '</em>';

$description = $converter->close_html_lone_element(
    "<meta name=\"description\" content=\"$description\"");

my $non_breaking_space = $converter->get_info('non_breaking_space');
my $result = '<tr><td>' .$non_breaking_space. '</tr></td>';

10.2 Converter General Information ¶

Some general information is available from the converter. This information should not change during conversion.

To determine if an output format such as ‘html’ or ‘tex’ is expanded (see Conditional Commands in Texinfo), use is_format_expanded:

Function: $is_format_expanded = $converter->is_format_expanded ($format) ¶

Return true if format $format is expanded, according to command-line and init file information.

The main method to get information from the converter is get_info:

Function: $info = $converter->get_info ($item) ¶

Return information on $item.

The available information is about:

copying_comment

Text appearing in @copying with all the Texinfo commands put into comments (see @copying in Texinfo).

destination_directory

Destination directory for the output files. It is common to use that string in directory or file paths with functions requiring binary strings. In that case the character string needs to be encoded. See Encoding File Path Strings.

document

The Texinfo::Document parsed Texinfo document being converted. Some information relevant for conversion is available from the document using function accessors:

floats_information

Information on floats. See Texinfo::Document::floats_information.

global_commands_information

Global commands information. See Texinfo::Document::global_commands_information.

global_information

Diverse information. See Texinfo::Document::global_information.

indices_information

Information about defined indices, merged indices and index entries. See Texinfo::Document::indices_information.

sections_list

List of the sectioning commands in the document.

See (texi2any_internals)Texinfo::Document Getting document information on information available from the document.

document_name

Base name of the document. It is common to use that string in in directory or file paths with functions requiring binary strings. In that case the character string needs to be encoded. See Encoding File Path Strings.

documentdescription_string

@documentdescription argument converted in a string context (see @documentdescription in Texinfo). See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

expanded_formats

Information on output formats such as ‘html’ or ‘tex’ expansion (see Conditional Commands in Texinfo). An hash reference with format names as key and a true value as value if the format is expanded, according to command-line and init file information.

expanded_formats information should be consistent with is_format_expanded call result (see is_format_expanded).

jslicenses

An hash reference with categories of javascript used in the document as keys. The corresponding values are also hashes with file names as keys and with array references as values. The array references contain information on each of the file licences, with content

1. licence name
2. license URL
3. file name or source of file

line_break_element

HTML line break element, based on ‘<br>’, also taking into account USE_XML_SYNTAX customization variable value.

non_breaking_space

Non breaking space, can be ‘&nbsp;’, but also a non breaking space character or the corresponding numeric entity based on OUTPUT_CHARACTERS and USE_NUMERIC_ENTITY customization variables values. See Substituting Non Breaking Space.

paragraph_symbol

Paragraph symbol, can be ‘&para;’, but also the corresponding numeric entity or encoded character based on OUTPUT_CHARACTERS and USE_NUMERIC_ENTITY customization variables values. See HTML Features Customization in Texinfo.

title_string

title_tree

simpletitle_tree

simpletitle_command_name

Some information is deduced from the title commands: simpletitle reflects @settitle vs. @shorttitlepage, and title is constructed by trying all the title-related commands, including @top and @titlefont, in the top element.

title_tree is a Texinfo tree corresponding to the title, title_string is the result of the conversion in a string context (see Init File Expansion Contexts: Normal, Preformatted, Code, String, Math). simpletitle_tree is a Texinfo tree corresponding to the simpletitle, and simpletitle_command_name is the @-command name used for the simpletitle, without the leading @.

title_titlepage

The formatted title, possibly based on @titlepage, or on simpletitle_tree and similar information, depending on SHOW_TITLE and USE_TITLEPAGE_FOR_TITLE customization variables in the default case (see HTML Output Structure Customization in Texinfo).

See Customization of CSS Rules, Imports and Selectors for an explanation on getting information on CSS.

10.3 Getting Conversion Context ¶

Some dynamically generated information should be used from the converter, in particular the expansion context (see Init File Expansion Contexts: Normal, Preformatted, Code, String, Math).

• Conversion in String Context
• Conversion in Preformatted Context
• Other Dynamic Information

if ($converter->in_string()) {
  return "$mail_string ($text)";
} else {
  return $converter->html_attribute_class('a', [$cmdname])
                      ." href=\"mailto:$mail_string\">$text</a>";
}

my $pre_classes = $converter->preformatted_classes_stack();
foreach my $pre_class (@$pre_classes) {
  if ($Texinfo::Commands::preformatted_code_commands{$pre_class}) {
    $result = '<var>' .$result. '</var>';
    last;
  }
}

10.4 Converting Texinfo Trees ¶

In some cases, it may be needed to convert a Texinfo tree rooted at any element. There is no reason to do that often, as the converter already goes through the tree calling functions to convert the elements, but it can be interesting in some cases.

This is, for example, often needed if a translated Texinfo tree is setup (see Internationalization of Strings Function). For example, here a Texinfo tree is returned by the cdt call, based on the translation of the ‘No value for @strong{{item}}’ string, and converted to HTML with convert_tree:

my $tree = $converter->cdt('No value for @strong{{item}}',
                           {'item' => $text_element});
my $no_value_converted_output = $converter->convert_tree($tree);

• Texinfo Tree Conversion Functions
• Setting the Context for Conversion
• Conversion to Plain Text
• Texinfo Tree Elements in User Defined Functions
• Output Units in User Defined Functions

my @contents = @{$element->{'contents'}};
push @contents, {'text' => ' <code>HTML</code> text ',
                   'type' => '_converted'};
my $result = $converter->convert_tree({'type' => '_code',
                                  'contents' => \@contents });

my $plain_text = Texinfo::Convert::Text::convert_to_text($element,
                                  $converter->{'convert_text_options'});

Texinfo::Convert::Text::set_options_code(
               $converter->{'convert_text_options'});
my $code_string = Texinfo::Convert::Text::convert_to_text($element,
                            $converter->{'convert_text_options'});
Texinfo::Convert::Text::reset_options_code(
               $converter->{'convert_text_options'});

Texinfo::Convert::Text::set_options_code(
               $converter->{'convert_text_options'});
Texinfo::Convert::Text::set_options_encoding_if_not_ascii($converter,
                             $converter->{'convert_text_options'});
my $file_name = Texinfo::Convert::Text::convert_to_text($element,
                            $converter->{'convert_text_options'});
Texinfo::Convert::Text::reset_options_code(
               $converter->{'convert_text_options'});
Texinfo::Convert::Text::reset_options_encoding(
               $converter->{'convert_text_options'});

my @contents = @{$element->{'contents'}};
push @contents, {'text' => ' my added text'};
my $result = $converter->convert_tree({'cmdname' => 'strong',
                                  'contents' => \@contents });

push @{$element->{'contents'}}, {'text' => ' my added text'};

11.1 Registering Specific Formating Functions ¶

User defined formatting functions are registered with texinfo_register_formatting_function:

Function: texinfo_register_formatting_function ($formatted, \&handler) ¶

$formatted is a string describing the formatting function. \&handler is the user defined function reference.

To call a formatting function from user defined code, the function reference should first be retrieved using formatting_function:

Function: \&formatting_function = $converter->formatting_function ($formatted) ¶

$formatted is a string describing the formatting function. Returns the associated formatting function reference.

It is possible to have access to the default formatting function reference. The function used is:

Function: \&default_formatting_function = $converter->default_formatting_function ($formatted) ¶

$formatted is a string describing the formatting function. Returns the default formatting function reference.

The string that should be used to register or call each of the formatting functions and the call of the formatting functions are documented in the following sections of the manual, depending on where they are relevant.

11.2 Basic Formatting Customization ¶

The following formatting functions references handle basic formatting and are called from diverse formatting and conversion functions. See Registering Specific Formating Functions for information on how to register and get the functions references.

All the functions take a converter object as their first argument.

format_comment

Function Reference: $text format_comment ($converter, $input_text) ¶

Return $input_text in a comment.

See Texinfo::Convert::Converter::xml_comment.

format_heading_text

Function Reference: $text format_heading_text ($converter, $command_name, \@classes, $input_text, $level, $id, \%element, $target) ¶

Returns a heading formatted using $input_text as heading text, $level as heading level, \@classes for a class attribute. $command_name gives an information on the @-command the heading is associated with and can be undef, for instance for special output units headings.

$id is an optional identifier, and \%element is an optional Texinfo tree element associated with the heading. $target is the id of the element this heading is referring to.

In the default case, if the $target or $id are specified, a copiable anchor will be generated and injected into the heading. In the case both are specified, $id is preferred over $target, as it is closer to the element the user sees the anchor on.

This function reference can be called for @node and sectioning commands, heading commands, special output units and title @-commands.

A formatted headings is, in the default case, like <h2>$input_text</h2> for a $level 2 heading.

format_program_string

Function Reference: $text format_program_string ($converter) ¶

This function reference should return the formatted program string.

format_protect_text

Function Reference: $text format_protect_text ($converter, $input_text) ¶

Return $input_text with HTML reserved characters and form feeds protected.

For performance reasons, this function reference may not be called everywhere text is protected. For those cases, the calling function should also be redefined to call &{$converter->formatting_function('format_protect_text')}(...) instead of another function⁴.

See Texinfo::Convert::Converter::xml_protect_text.

format_separate_anchor

This function reference is called if there is not another HTML element to add an identifier attribute to.

Function Reference: $text format_separate_anchor ($converter, $id, $class) ¶

id is the identifier. $class is an optional class to be used in an HTML class attribute.

Return an anchor with identifier $id.

For example, a separate anchor with an id built from a counter could be obtained with:

$counter++;
my $anchor_id = 'anchor_id_' . $counter;
my $anchor_with_counter
  = &{$converter->formatting_function('format_separate_anchor')}(
                             $converter, $anchor_id, 'myanchor_class');

The default function used for separate anchors can be replaced by a user-defined anchor formatting function using a <p> element with:

sub my_format_separate_anchor($$;$)
{
  my $converter = shift;
  my $id = shift;
  my $class = shift;

  return $converter->html_attribute_class('p', [$class])." id=\"$id\"></p>";
}

texinfo_register_formatting_function('format_separate_anchor',
                                     \&my_format_separate_anchor);

12.1 Command Tree Element Conversion ¶

All the command elements can have a conversion function and an opening function that can be registered to be called by the converter. Some commands also require more specific information and functions for their formatting.

• Command Tree Element Conversion Functions
• Command Tree Element Opening Functions
• Heading Commands Formatting
• Target Tree Element Link
• Specific Formatting for Indices
• Image Formatting

&{$converter->command_conversion('tab')}($converter, $cmdname,
                                     $command, $args, $content);

my $level = $opening_section->{'extra'}->{'section_level'};
my $closed_strings
   = $converter->close_registered_sections_level(
                    $converter->current_filename(), $level);
$result .= join('', @{$closed_strings});

# ....

$converter->register_opened_section_level(
                 $converter->current_filename(), $level, "</div>\n");

my $node_element = $converter->label_command('Some-node_003f');

my $arg_node = $xref_tree_element->{'args'}->[0];
if ($arg_node and $arg_node->{'extra'}
    and defined($arg_node->{'extra'}->{'normalized'})) {
  my $target_node
    = $converter->label_command($arg_node->{'extra'}->{'normalized'});
}

my $target_text = $converter->command_text($target_element);
my $target_href = $converter->command_href($target_element);
my $hyperlink = "<a href=\"$target_href\">$target_text</a>";

my $entry_root_link = '';
my $associated_command
 =  $converter->command_root_element_command($target_element);
if ($associated_command) {

  my $associated_command_href
    = $converter->command_href($associated_command);
  my $associated_command_text
    = $converter->command_text($associated_command);

  if (defined($associated_command_href)) {
    $entry_root_link
      = "<a href=\"$associated_command_href\">"
          ."$associated_command_text</a>";

} elsif (defined($associated_command_text)) {
  $entry_root_link = $associated_command_text;
}

my $formatted_entry = "<td><tr>$hyperlink</tr>"
                  ."<tr>$entry_root_link</tr></td>\n";

my ($output_unit, $root_command)
 = $converter->get_element_root_command_element($printindex_element);
my $index_element_id = $converter->command_id($root_command);

12.2 Type Tree Element Conversion ¶

All the containers and text Texinfo tree elements not handled with command tree elements have a type associated. As for commands tree elements, they can have an opening function and a conversion function registered for a type and used. Some types may need more specific information too.

For tree elements that contain text, a text type is used to select the formatting functions, irrespective of the actual type of such a tree element. The text type does not exist in actual Texinfo tree elements.

• Type Tree Element Conversion Functions
• Type Tree Element Opening Functions
• Text Tree Elements Conversion
• Inline Text Containers Paragraph and Preformatted Formatting

sub my_tree_element_convert_paragraph_type($$$$)
{
  my $converter = shift;
  my $type = shift;
  my $element = shift;
  my $content = shift;

  $content = '' if (!defined($content));

  if ($converter->in_string()) {
    return $content;
  }

  my @contents = {$element->{'contents'}};
  push @contents, {'text' => ' <code>HTML</code> text ',
                   'type' => '_converted'};
  my $result = $converter->convert_tree({'type' => '_code',
                                   'contents' => \@contents });
  return "<p>".$result."</p>";
}

texinfo_register_type_formatting('paragraph',
                        \&my_tree_element_convert_paragraph_type);

sub my_convert_text($$$)
{
  my $converter = shift;
  my $type = shift;
  my $element = shift;
  my $text = shift;

  # ...

  $text = uc($text) if ($converter->in_upper_case());

  # ...
}

texinfo_register_type_formatting ('text', \&my_convert_text);

my $quotation_arg_to_prepend
  = $converter->convert_text($quotation_arg_element);
$converter->register_pending_formatted_inline_content('quotation',
                                 $formatted_quotation_arg_to_prepend);

sub _open_inline_container_type($$$)
{
  my $self = shift;
  my $type = shift;
  my $element = shift;

  my $pending_formatted = $self->get_pending_formatted_inline_content();

  if (defined($pending_formatted)) {
    $self->associate_pending_formatted_inline_content($element,
                                                    $pending_formatted);
  }
  return '';
}

sub my_final_convert_paragraph_type($$$$)
{
  my $converter = shift;
  my $type = shift;
  my $element = shift;
  my $content = shift;

  $content = '' if (!defined($content));

  my $prepended
    = $converter->get_associated_formatted_inline_content($element);
  if ($converter->in_string()) {
    return $prepended.$content;
  }

  my @contents = {$element->{'contents'}};
  push @contents, {'text' => ' <code>HTML</code> text ',
                   'type' => '_converted'};
  my $result = $converter->convert_tree({'type' => '_code',
                                   'contents' => \@contents });
  return "<p>".$prepended.$result."</p>";
}

texinfo_register_type_formatting('paragraph',
                             \&my_final_convert_paragraph_type);

14.1 Define, Get and Set Shared Conversion State ¶

Four types for selectors and value are currently considered:

string

A string.

integer

An integer

element

A Texinfo tree element.

index_entry.

An index entry reference as appearing in index data structures. See (texi2any_internals)Texinfo::Document index_entries.

New shared infomation is defined with define_shared_conversion_state:

Function: $converter->define_shared_conversion_state ($cmdname, $name, \@specification) ¶

$cmdname is an @-command name, without leading @. name is the name associated with the data. The top command name is conventionally used if there is no natural association with another @-command. \@specification array reference specifies the types of the selectors and the type of the value as strings. The last string of the array specifies the type of the value. The preceding strings specify the number and types of selectors⁵.

For example, ['integer', 'element', 'string'] specifies a ‘string’ type for the value, and two selectors, the first with ‘integer’ type, and the second with ‘element’ type. ['integer'] specifies an integer for the value and no selector.

For example, the following defines a ‘color’ shared conversion state formally associated with @quotation, with an integer value and a string selector.

$converter->define_shared_conversion_state ('quotation', 'color',
                                            ['string', 'integer']);

The association with an @-command is provided for a semantic classification of shared conversion information, but has no practical effect. In particular, nothing prevents using shared conversion state information associated with an @-command in the formatting of another @-command.

The function get_shared_conversion_state is used to get information:

Function: $value = $converter->get_shared_conversion_state ($cmdname, $name, [$selector …]) ¶

Return the reference $value associated with $cmdname and $name. The number of selectors given in argument should match the number of selectors in the definition (possibly none).

For example, continuing with the ‘color’ shared information data defined above, with one selector variable:

my $color_number
   = $converter->get_shared_conversion_state('quotation',
                                               'color', 'purple1');

The function set_shared_conversion_state is used to set shared information:

Function: $converter->define_shared_conversion_state ($cmdname, $name, [$selector …], $value) ¶

Sets $value associated with $cmdname and $name. The number of selectors given in argument should match the number of selectors in the definition (possible none).

For example:

$converter->set_shared_conversion_state('quotation', 'color',
                                        'special_black', 42);

The converter is used to hold the information, but does not use nor write.

14.2 Shared Conversion State in Default Formatting ¶

The following shared conversion state information is defined in the default formatting functions:

These shared information data correspond to:

explained_commands ¶

Associate the explanation given in a previous @abbr or @acronym second argument to first @abbr or @acronym arguments.

footnote_number ¶

The current number of footnotes formatted in document.

footnote_id_numbers ¶

Associate a footnote identifier, typically used in hyperlink reference, to the number of time the corresponding footnote was formatted. More than one corresponds to very rare cases, for instance a footnote in @copying and multiple @insertcopying.

formatted_listoffloats ¶

Associate a list of float type to the number of time it was formatted.

html_menu_entry_index ¶

Current number of menu entries in a menu. Reset to 0 at @menu beginning.

formatted_index_entries ¶

Associate an index entry to the number of time it was formatted.

in_skipped_node_top ¶

Set to 1 in a Top node being skipped, in case NO_TOP_NODE_OUTPUT is set.

formatted_nodedescriptions ¶

Associate a @nodedescription tree element to the number of time it was formatted.

15.1 Internationalization of Strings Function ¶

The subroutines cdt, cdt_string or pcdt, are used for translated strings:

Function: $translated_tree = $converter->cdt ($string, \%variables_hash, $translation_context) ¶

Function: $translated_string = $converter->cdt_string ($string, \%variables_hash, $translation_context) ¶

Function: $translated_tree = $converter->pcdt ($translation_context, $string, \%variables_hash) ¶

$string is the string to be translated, \%variables_hash is a hash reference holding the variable parts of the translated string. $translation_context is an optional translation context that limits the search of the translated string to that context (see Contexts in GNU gettext tools).

The result returned is a Perl Texinfo tree for cdt and pcdt and a string for cdt_string. With cdt_string the substitutions may only be strings.

If called as pcdt, $translation_context is not optional and is the first argument.

With cdt and pcdt, when the string is expanded as Texinfo, and converted to a Texinfo tree in Perl, the arguments are substituted; for example, ‘{arg_name}’ is replaced by the corresponding actual argument, which should be a Texinfo tree element. With cdt_string, the string should already be converted, the arguments are substituted as strings; for example ‘{arg_name}’ is replaced by the corresponding actual argument, which should be a string.

In the following example, ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are the arguments of the string. Since they are used in @uref, their order in the formatted output depends on the formatting and is not predictable. ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are substituted after the expansion, which means that they should already be Texinfo tree elements.

  $converter->cdt('Generated @emph{@today{}} using '
   .'@uref{{homepage}, @emph{{program}}}.',
      { 'homepage' => { 'text' => $converter->get_conf('PACKAGE_URL') },
        'program' => { 'text' => $converter->get_conf('PROGRAM') }});

An example of combining conversion with translation:

$converter->convert_tree($converter->cdt(
       '{explained_string} ({explanation})',
       {'explained_string' => {'type' => '_converted',
                               'text' => $result},
        'explanation' => {'type' => '_converted',
                          'text' => $explanation_result}}),
                         "convert explained $cmdname");

In the default case, the functions from the Texinfo::Translations module are used for translated strings through converter functions. It is possible to use user-defined functions instead as seen next. See (texi2any_internals)Texinfo::Translations for more on Texinfo::Translations.

In texi2any code, cdt and cdt_string are also used to mark translated strings for tools extracting translatable strings to produce template files. pcdt is used to mark translated string with a translation context associated.

15.2 Translated Strings Customization ¶

To customize strings translations, register the format_translate_message function reference:

Function Reference: $translated_string format_translate_message ($converter, $string, $lang, $translation_context) ¶

$string is the string to be translated, $lang is the language. $translation_context is an optional translation context.

The result returned should be the translated string. The result returned may also be ‘undef’, in which case the translation is done as if the function reference had not been defined.

See Internationalization of Strings Function for more information on strings translations function arguments.

This function reference is not set in the default case, in the default case translate_string from the Texinfo::Translations module is called (see Internationalization of Strings Function). See Registering Specific Formating Functions for information on how to register and get the function reference.

Here is an example with new translated strings added and definition of format_translate_message to translate the strings:

texinfo_register_no_arg_command_formatting('error', undef, undef,
                                                undef, 'error-->');
my %translations = (
 'fr' => {
           'error-->' => {'' => 'erreur-->',},
           # ...
         },
 'de' => {
           'error-->' => {'' => 'Fehler-->',},
           # ...
         }
 # ...
);

sub my_format_translate_message($$$;$)
{
  my ($self, $string, $lang, $translation_context) = @_;
  $translation_context = '' if (!defined($translation_context));
  if (exists($translations{$lang})
      and exists($translations{$lang}->{$string})
      and exists($translations{$lang}->{$string}
                                  ->{$translation_context})) {
    my $translation = $translations{$lang}->{$string}
                                      ->{$translation_context};
    return $translation;
  }
  return undef;
}

texinfo_register_formatting_function('format_translate_message',
                                  \&my_format_translate_message);

15.3 Translation Contexts ¶

Translation contexts may be set to avoid ambiguities for translated strings, in particular when the strings are short (see Contexts in GNU gettext utilities). Translation contexts are set for translated direction strings (see Direction Strings) and for special output units headings (see Special Units Information Customization).

For direction strings, the translation context is based on the direction name (see Directions), with ‘direction’ prepended and another string prepended, depending on the type of string:

button

‘button label’ is prepended

description

‘description’ is prepended

text

‘string’ is prepended

For example, the Top direction button direction string translation context is ‘Top direction button label’.

As an exception, the This direction has ‘(current section)’ prepended to have a more explicit translation context. The This direction text direction string translation context is thus ‘This (current section) direction string’.

For special output unit headings, the translation context is obtained by prepending ‘section heading’ to the special output unit variety (see Table 16.1). For example, the footnotes special output unit variety heading translation context is ‘footnotes section heading’.

Here is an example, which could be used with a similar function registered as in the example above (see New translated strings example):

texinfo_register_direction_string_info('Forward', 'text', undef,
                                       'Forward');
texinfo_register_special_unit_info('heading', 'contents',
                              'The @emph{Table of Contents}');

my %translations = (
  'fr' => {
         'The @emph{Table of Contents}' => {'contents section heading'
                       => '@result{} La @emph{Table des mati@`eres}',},
         'Forward' => {'Forward direction string'
                       => 'Vers l\'avant @result{}',},
          }
   ...
);

Other translated strings may also be associated with translation contexts. The translation template file po_document/texinfo_document.pot in the source directory of Texinfo contains the translated strings appearing in all the output formats.

16.1 Special Units Information Customization ¶

To customize special output units formatting, a simple possibility is to change the information associated with the special output units.

The following items common to all the special units may be customized:

class

String for special element HTML class attributes.

direction

Direction corresponding to the special element. See Directions.

heading

Special element heading Texinfo code.

heading_tree

Special element heading Texinfo tree.

order

Index determining the sorting order of special elements.

file_string

File string portion prepended to the special element file names, such as ‘_toc’.

target

A string representing the target of the special element, typically used as id attribute and in href attribute.

The heading string is set with heading, and should be a Texinfo code string. heading_tree cannot be set directly, but can be retrieved. It is determined from heading after translation and conversion to a Texinfo tree.

To set the information, use texinfo_register_special_unit_info in an init file:

Function: texinfo_register_special_unit_info ($item_type, $special_unit_variety, $value) ¶

Set $item_type information for the special unit variety $special_unit_variety to $value. $value may be ‘undef’, or an empty string, but only heading and target should be set to that value as a non-empty value is needed for the other items for formatting.

To get the list of varieties, use get_special_unit_info_varieties:

Function: $list = $converter->get_special_unit_info_varieties ($item_type) ¶

$item_type is the type of information to be retrieved as described above. The list of the special units varieties with information for the $item_type is returned.

To retrieve the information for formatting, use special_unit_info:

Function: $list_or_value = $converter->special_unit_info ($item_type, $special_unit_variety) ¶

$item_type is the type of information to be retrieved as described above. $special_unit_variety is a special unit variety, the corresponding value is returned.

The value returned is translated and converted to a Texinfo tree for ‘heading_tree’.

16.2 Customizing Footnotes ¶

In the default case footnotes are numbered. If NUMBER_FOOTNOTES is set to 0, a ‘*’ is used instead, or the NO_NUMBER_FOOTNOTE_SYMBOL customization variable value, if set.

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 number of the footnote in the document. $footnote_location_filename is the filename of the output unit 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 Other Dynamic 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 Tree Element Link).

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

Returns in \@pending_footnotes_information the information gathered in register_footnote. Each of the array reference 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 Registering 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 to link to the location in the document where the footnote appeared, and the format_single_footnote formatting function to format a single footnote.

The formatting of one footnote is done by the format_single_footnote formatting reference:

Function Reference: $footnote format_single_footnote ($converter, \%element, $footnote_id, $number_in_doc, $footnote_location_href, $footnote_mark) ¶

Formats and returns a single footnote. \%element is the footnote Texinfo tree element. $footnote_id is the identifier for the location where the footnote arguments are expanded. $number_in_doc is the number of the footnote in the document. $footnote_location_href is the href that links to the footnote location in the main document. $footnote_mark is the footnote number or mark.

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

If the footnotes are not in a separate output unit, or there is no separate unit because there is only one output unit or no output unit, 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 Units Information Customization).

To get the id of a footnote in the main document, use footnote_location_target:

Function: $target = $converter->footnote_location_target (\%footnote_element) ¶

Return the id for the location of the footnote \%footnote_element in the main document (where the footnote number or symbol appears).

To get an href to link to a footnote location in the main document, use footnote_location_href:

Function: $href = $converter->footnote_location_href (\%footnote_element, $source_filename, $specified_target, $target_filename) ¶

Return string for linking to \%footnote_element location in the main document with <a href>. $source_filename is the file the link comes from. If not set, the current file name is used. $specified_target is an optional identifier that overrides the target identifier if set. $target_filename is an optional file name that overrides the file name href part if set.

See Target Tree Element Link to get link information for the location where footnote text is output.

16.3 Contents and Short Table of Contents Customization ¶

You can set the customization variable CONTENTS_OUTPUT_LOCATION to determine where the table of contents and short table of content are output in the document (see HTML Output Structure Customization in Texinfo):

‘after_top’

The tables of contents are output at the end of the @top section, to have the main location for navigation in the whole document early on. This is in line with FORMAT_MENU set to ‘sectiontoc’ with sectioning command being used in HTML for navigation rather than menus. This is the default.

‘inline’

The tables of content are output where the corresponding @-command, for example @contents, is set. This behavior is consistent with texi2dvi.

‘separate_element’

The tables of contents are output in separate output units, either at the end of the document if the output is unsplit or in separate files if not. This makes sense when menus are used for navigation with FORMAT_MENU set to ‘menu’.

‘after_title’

The tables of contents are merged into the title material, which in turn is not output by default; see HTML Title Page Customization.

You can set other customization variables to modify table of contents links formatting (see File Names and Links Customization for HTML in Texinfo) and change the HTML code inserted before and after the tables of contents (see Customization of HTML Code Inserted in Texinfo).

Finally, the following function reference provides even more control over the table of contents and short table of contents formatting reference:

Function Reference: $toc_result format_contents ($converter, $command_name, \%element, $filename) ¶

$command_name is the @-command name without leading @, should be ‘contents’, ‘shortcontents’ or ‘summarycontents’. \%element is optional. It corresponds to the $command_name Texinfo tree element, but it is only set if format_contents is called from a Texinfo tree element conversion, and not as a special element body formatting. $filename is optional and should correspond to the filename where the formatting happens, for links.

In the default function, structuring information is used to format the table of contents (see Converter General Information), and command_contents_href and command_href (see Target Tree Element Link) are used for links. If $filename is unset, the current file name is used, using $converter->current_filename().

Return formatted table of contents or short table of contents.

If contents are in a separate output unit (see Output Units), the default contents and shortcontents special element body formatting function calls format_contents (see Special Unit Body Formatting Functions). Otherwise, format_contents is called in the conversion of heading @-command, in title page formatting, and in @contents conversion function, depending on the CONTENTS_OUTPUT_LOCATION value.

To get id and link href of sectioning commands in table of contents and short table of contents, use command_contents_target and command_contents_href:

Function: $target = $converter->command_contents_target (\%sectioning_element, $contents_or_shortcontents) ¶

Returns the id for the location of \%sectioning_element sectioning element in the table of contents, if $contents_or_shortcontents is ‘contents’, or in the short table of contents, if $contents_or_shortcontents is set to ‘shortcontents’ or ‘summarycontents’.

Function: $href = $converter->command_contents_href (\%sectioning_element, $contents_or_shortcontents, $source_filename) ¶

Return string for linking to the \%sectioning_element sectioning element location in the table of contents, if $contents_or_shortcontents is ‘contents’ or in the short table of contents, if $contents_or_shortcontents is set to ‘shortcontents’ or ‘summarycontents’. $source_filename is the file the link comes from. If not set, the current file name is used. Returns undef if no string is found or the string is empty.

16.4 About Special Output Unit Customization ¶

The default About output unit has an explanation of the buttons used in the document, controlled by SECTION_BUTTONS. The formatting of this is influenced by the text, description and example direction strings (see Direction Strings) and by ACTIVE_ICONS (see Simple Navigation Panel Customization).

PROGRAM_NAME_IN_ABOUT can also be used to change the beginning of the About output unit formatting.

If the above is not enough and you want to control exactly the formatting of the about unit, the about special output unit body reference function may be overridden (see Special Unit Body Formatting Functions).

16.5 Special Unit Body Formatting Functions ¶

In addition to the formatting possibilities available with the default special output units formatting presented previously, it is also possible to control completely how a separate special output unit is formatted.

To register body formating user defined functions for special output units (see Output Units), the special output units varieties are used, as described in Table 16.1. Special element body formatting user defined functions are registered with texinfo_register_formatting_special_unit_body:

Function: texinfo_register_formatting_special_unit_body ($special_unit_variety, \&handler) ¶

$special_unit_variety is the element variety (see Table 16.1). \&handler is the user defined function reference.

The call of the user defined functions is:

Function Reference: $text special_unit_body ($converter, $special_unit_variety, \%special_unit) ¶

$converter is a converter object. $special_unit_variety is the unit variety. \%special_unit is the special output unit.

The $text returned is the formatted special output unit body.

To call a special output unit body formatting function from user defined code, the function reference should first be retrieved using special_unit_body_formatting:

Function: \&special_unit_body_formatting = $converter->special_unit_body_formatting ($special_unit_variety) ¶

$special_unit_variety is the special output unit variety. Returns the conversion function reference for $variety, or ‘undef’ if there is none, which should not happen for the special output units described in this manual.

For example:

my $footnotes_element_body
 = &{$converter->special_unit_body_formatting('footnotes')}(
                                   $converter, 'footnotes', $element);

It is possible to have access to the default conversion function reference. The function used is:

Function: \&default_special_unit_body_formatting = $converter->defaults_special_unit_body_formatting ($special_unit_variety) ¶

$special_unit_variety is the special output unit variety. Returns the default conversion function reference for $special_unit_variety, or undef if there is none, which should not happen for the special output units described in this manual.

See Customizing Footnotes for more on footnotes formatting. See Contents and Short Table of Contents Customization for more on the contents and shortcontents formatting. See About Special Output Unit Customization for more on the about special output unit body formatting.

17.1 Navigation Panel Button Formatting ¶

The function reference format_button does the formatting of one button, corresponding, in general, to a link to a direction:

Function Reference: $formatted_button format_button ($converter, $button, $source_command) ¶

$button holds the specification of the button (see Buttons Display). $source_command is an optional argument, the @-command the link comes from.

Returns the formatted result in $formatted_button.

The buttons images can be formatted with format_button_icon_img (see below).

Simple navigation panel customization (see Simple Navigation Panel Customization), USE_ACCESSKEY, USE_REL_REV and direction strings customization (see Direction Strings Customization) can be relevant for the formatting of a button.

To get direction strings typically used for formatting of buttons or hyperrefs leading to that direction, use direction_string:

Function: $string = $converter->direction_string ($direction, $string_type, $context) ¶

Retrieve the $direction (see Directions) string of type $string_type (see Direction Strings). $context is ‘normal’ or ‘string’. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math. If $context is undef, the ‘normal’ context is assumed. The string will be translated if needed. May return undef.

To get the Texinfo special output unit associated with a special output unit direction, such as ‘About’ or ‘Contents’, as well as output unit associated with other global directions, such as ‘Top’ or ‘Index’, use use global_direction_unit:

Function: \%output_unit = $converter->global_direction_unit ($direction) ¶

Return the output unit associated with direction $direction, or undef if the direction is not a global output unit direction nor a special output unit direction or the associated special output unit is not output.

To get link information for relative and global directions, use from_element_direction:

Function: $result = $converter->from_element_direction ($direction, $type, $source_element, $source_filename, $source_command) ¶

Return a string for linking to $direction, or the information to be used for a hyperlink to $direction, depending on $type. The possible values for $type are described in Output Unit Direction Information Type.

$source_element is the output unit the link comes from. If not set, the current output unit is used. $source_filename is the file the link comes from. If not set, the current file name is used. $source_command is an optional argument, the @-command the link comes from. It is only used for messages.

format_button_icon_img formatting function can be redefined. In the default case, it is called for an active direction, if ICONS is set, when formatting a navigation panel button.

Function Reference: $text format_button_icon_img ($converter, $button, $icon, $name) ¶

$button is a button name, typically obtained from the button direction string (see Direction Strings). $icon is an image file name to be used as icon. $name is the direction heading, typically formatted in string context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

Returns a formatted icon image.

See Directions for the list of directions.

17.2 Navigation Panel and Navigation Header Formatting ¶

The overall display of navigation panels is controlled via this function reference, format_navigation_header:

Function Reference: $navigation_text format_navigation_header ($converter, \@buttons, $command_name, \%element) ¶

\@buttons is an array reference holding the specification of the buttons for the navigation panel (see Simple Navigation Panel Customization). \%element is the element in which the navigation header is formatted. $command_name is the associated command (sectioning command or @node). It may be undef for special output units.

Returns the formatted navigation header and panel. The navigation panel itself can be formatted with a call to format_navigation_panel.

The customization variable VERTICAL_HEAD_NAVIGATION should be relevant (see Customization of Navigation and Headers in Texinfo).

The navigation panel display is controlled via format_navigation_panel:

Function Reference: $navigation_text format_navigation_panel ($converter, \@buttons, $command_name, \%element, $vertical) ¶

\@buttons is an array reference holding the specification of the buttons for that navigation panel. \%element is the element in which the navigation header is formatted. $command_name is the associated command (sectioning command or @node). It may be undef for special elements. $vertical is true if the navigation panel should be vertical.

Returns the formatted navigation panel in $navigation_text. The buttons in the navigation panel can be formatted with a call to format_button (see format_button).

17.3 Element Header and Footer Formatting ¶

By default, the function associated with format_element_header formats the header and navigation panel of an output unit.

Function Reference: $formatted_header format_element_header ($converter, $command_name, \%element, \%output_unit) ¶

\%element is the element in which the navigation header is formatted (sectioning command, @node or special output unit). $command_name is the associated command name. It may be undef for special output units. \%output_unit is the associated output unit (see Texinfo Tree Elements in User Defined Functions).

Returns the formatted navigation header and panel.

In the default code, the function reference select a buttons list (see Simple Navigation Panel Customization). The navigation header can then be formatted with a call to format_navigation_header (see format_navigation_header). It is also possible to format directly the navigation panel, depending on customization variables values and location in file.

Similarly, the function associated with format_element_footer formats the footer and navigation panel of a output unit.

Function Reference: $formatted_footer format_element_footer ($converter, $output_unit_type, \%output_unit, $content, $command) ¶

\%output_unit is the output unit in which the navigation footer is formatted. $output_unit_type is the associated type. $content is the formatted element content. $content can be undef. $command is an optional argument, the @-command associated with the \%output_unit.

Returns the formatted navigation footer and panel.

In the default code, the function reference select a buttons list (see Simple Navigation Panel Customization). The navigation header can then be formatted with a call to format_navigation_header (see format_navigation_header).

Many customization variables have an effect on the footer formatting, such as SPLIT (see HTML Splitting in Texinfo), customization variables used for the customization of headers such as HEADERS or WORDS_IN_PAGE (see Customization of Navigation and Headers in Texinfo) and customization variables setting inserted HTML code such as DEFAULT_RULE (see Customization of HTML Code Inserted in Texinfo).

To select the list of buttons for header and footer formatting, it may be handy to be able to determine if the output unit being formatted is the Top output unit. To determine if a output unit is associated with the top output unit, use unit_is_top_output_unit:

Function: $is_top_output_unit = $converter->unit_is_top_output_unit (\%output_unit) ¶

Returns true if the \%output_unit output unit is the Top output unit (see Output Units) and is either associated with the @top sectioning command or with the Top @node.

17.4 Element Counters in Files ¶

The position of the output unit being formatted in its file or the total number of elements output to a file is interesting for navigation header and footer formatting, for instance to format end of files, decide which type navigation header or footer is needed and whether a rule should be output.

To get information on tree elements unit counter in files, use count_elements_in_filename:

Function: $count = $converter->count_elements_in_filename ($specification, $file_name) ¶

Return output unit counter for $file_name, or undef if the counter does not exist. The counter returned depends on $specification:

current

Return the number of output units associated with $file_name having already been processed.

remaining

Return the number of output units associated with $file_name that remains to be processed.

total

Return the total number of output units associated with the file.

For example, to get the total number of output units associated with the file of a node element:

my $file_name = $converter->command_filename($node_element);
my $number = $converter->count_elements_in_filename('total',
                                                  $file_name);

18.1 Customizing HTML File Beginning ¶

You can set the variable DOCTYPE to replace the default. The DOCTYPE is output at the very beginning of each output file.

You can define the variable EXTRA_HEAD to add text within the <head> HTML element. Similarly, the value of AFTER_BODY_OPEN is added just after <body> is output. These variables are empty by default.

The <body> element attributes may be set by defining the customization variable BODY_ELEMENT_ATTRIBUTES.

By default, the encoding name from OUTPUT_ENCODING_NAME is used. If this variable is not defined, it is automatically determined.

A date is output in the header if DATE_IN_HEADER is set.

The description from @documentdescription (or a value set as a customization variable) is used in the header (see @documentdescription in Texinfo).

<link> elements are used in the header if USE_LINKS is set, in which case LINKS_BUTTONS determines which links are used and the rel direction string (see Direction Strings) determines the link type associated with the rel attribute. See Simple Navigation Panel Customization.

You can set HTML_ROOT_ELEMENT_ATTRIBUTES to add attributes to the <html> element.

If SECTION_NAME_IN_TITLE is set, the sectioning command argument is used in the <title> HTML element instead of the @node argument.

You can also set a JavaScript browsing interface with customization variables (see JavaScript Interface and Licenses in Texinfo). See Customization of Navigation and Headers in Texinfo for more information on customization variables in the main Texinfo manual. See Customization of HTML Code Inserted in Texinfo for more on insertion of HTML code in output.

The following function references give full control over the page header formatting done at the top of each HTML output file.

Function Reference: $file_begin format_begin_file ($converter, $filename, \%output_unit) ¶

$filename is the name of the file output. \%output_unit is the first output unit of the file. This function should print the page header, in HTML, including the <body> element.

18.2 Customizing HTML File End ¶

You can define the variable PRE_BODY_CLOSE to add text just before the HTML </body> element. Nothing is added by default. If PROGRAM_NAME_IN_FOOTER is set, the date and name of the program that generated the output are output in the footer.

By default, the JavaScript license web labels page is formatted and output at the end of file (see JavaScript Interface and Licenses in Texinfo).

The format_end_file function reference give full control over the page footer formatting done at the bottom of each HTML output file.

Function Reference: $file_end format_end_file ($converter, $filename, \%output_unit) ¶

$filename is the name of the file output. \%output_unit is the last output unit of the file. This function should print the page footer, including the </body> element.

18.3 Associating Information to an Output File ¶

To be able to retrieve information associated with the current file, in general for the file begin or end formatting, register_file_information can be used to associate integer information, and get_file_information to retrieve that information.

Function: $converter->register_file_information ($key, $value) ¶

Associate the current output file name file to the key $key, itself associated with the integer value $value.

Function: $value = $converter->get_file_information ($key, $file_name) ¶

Return the value associated with the key $key and file name $file_name.

By default, this interface is used to get ‘mathjax’ file information registered when converting math @-commands to insert references to MathJax scripts in file beginning (see MathJax scripts in Texinfo) and license information in end of files (see JavaScript Interface and Licenses in Texinfo).

19.1 HTML Title Page Customization ¶

If SHOW_TITLE is not set, no title is output. SHOW_TITLE is ‘undef’ in the default case. If ‘undef’, SHOW_TITLE is set if NO_TOP_NODE_OUTPUT is set. The “title page” is used to format the HTML title if USE_TITLEPAGE_FOR_TITLE is set, otherwise the simpletitle is used. USE_TITLEPAGE_FOR_TITLE is set in the default case. See HTML Output Structure Customization in Texinfo.

The following functions references provides full control on the title and “title page” formatting:

Function Reference: $title_titlepage format_title_titlepage ($converter) ¶

Returns the formatted title or “title page” text.

In the default case, return nothing if SHOW_TITLE is not set, return the output of format_titlepage if USE_TITLEPAGE_FOR_TITLE is set, and otherwise output a simple title based on simpletitle.

Function Reference: $title_page format_titlepage ($converter) ¶

Returns the formatted “title page” text.

In the default case, the @titlepage is used if found in global information, otherwise simpletitle is used (see Converter General Information).

19.2 CSS Customization ¶

CSS in HTML output can already be modified with command line options and customization variables (see HTML CSS in Texinfo). More control of the generated CSS is available through functions.

• Customization of CSS Rules, Imports and Selectors
• Customizing the CSS Lines

my @all_included_rules = $converter->css_get_info('rules');
my $all_default_selector_styles = $converter->css_get_info('styles');
my $titlefont_header_style = $converter->css_get_selector_style('h1.titlefont');

$converter->css_set_selector_style('h1.titlefont', 'text-align:center');
$converter->css_add_info('imports', "\@import \"special.css\";\n");

sub my_function_set_some_css {
  my $converter = shift;

  $converter->css_set_selector_style('h1.titlefont',
                                     'text-align:center');
  # ... calls to  $converter->css_add_info();
}

texinfo_register_handler('structure', \&my_function_set_some_css);

19.3 Customizing Node Redirection Pages ¶

Node redirection pages are output if NODE_FILES is set (see Invoking texi2any in Texinfo).

It is possible to change completely how node redirection pages are generated by redefining the following function reference:

Function Reference: $node_redirection_file_content format_node_redirection_page ($converter, \%element) ¶

\%element is a node element needing a redirection page. A redirection page is needed if the node file name is not the file name expected for HTML cross manual references (see HTML Xref in Texinfo).

Returns the content of the node redirection file.