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);