---

11 Basic Formatting Customization ¶

The following formatting functions references handle basic formatting and are called from diverse formatting and conversion functions. See 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_button_icon_img

Called for an active direction, if ICONS is set, when formatting the navigation panel (see Simple Navigation Panel Customization).

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.

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 to and can be undef, for instance for special elements 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, tree units, special elements 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 &{$self->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.