Next: Conversion to Plain Text, Previous: Texinfo Tree Conversion Functions, Up: Converting Texinfo Trees   [Contents][Index]

10.4.2 Setting the Expansion Context for Conversion ¶

The expansion context is not generally customizable, as it is implied by the Texinfo command being converted (see Init File Expansion Contexts: Normal, Preformatted, Code, String, Math). However, it is possible to set the code or the string expansion context explicitly if needed. You often need expansion in string context for HTML elements attributes. The code expansion context is already set for @-commands such as @code or @example. However, it cannot be set automatically in every situation where it is relevant, in those cases you should set it explicitly. For example, node names appearing in headings, most parts of the definition lines (except for the category), and index entries in index defined by @defcodeindex in @printindex formatting should be formatted in code expansion context.

To set code expansion in the main formatting document context, call convert_tree_in_code_context:

Function: $converted_text = $converter->convert_tree_in_code_context (\%element, $explanation) ¶

\%element is a Texinfo tree element. $explanation is optional, it is a string explaining why the function was called, to help in case of debugging. The function sets code expansion context and returns \%element converted by convert_tree.

In the following example, the content of an existing tree element is copied, text is prependended and the resulting new tree element is converted in code expansion context:

my @contents = @{$element->{'contents'}};
push @contents, Texinfo::TreeElement::new({'text' => ' HTML text '});
my $new_element = Texinfo::TreeElement::new({'contents' => \@contents});
my $result = $converter->convert_tree_in_code_context($new_element);
return "<p>".$result."</p>";

Since the main document expansion context should never be in string expansion context it is not possible to set string expansion context in the main formatting document context.

You can set the expansion context with convert_tree_new_formatting_context by setting the expansion context flags argument with flags set for the expansions you want. You can set different flags concurrently, in case you want to set multiple explansion contexts. The flags are:

$Texinfo::Convert::HTML::CTXF_string

Add this flag for an expansion in string context.

$Texinfo::Convert::HTML::CTXF_code

Add this flag for an expansion in code context.

For example:

# conversion in string context
my $result_string = $converter->convert_tree_new_formatting_context(
                     $element, 'in string',
                     $Texinfo::Convert::HTML::CTXF_string);

my $multi_flag = 0;
$multi_flag |= $Texinfo::Convert::HTML::CTXF_string;
$multi_flag |= $Texinfo::Convert::HTML::CTXF_code;
# conversion in code and string context
my $result_code_string
    = $converter->convert_tree_new_formatting_context(
                     $element, 'in code string', $multi_flag);

if ($converter->in_string()) {
  return $result_string;
}
return "<i title=\"$result_string\">$text</i>\n"
        . "<i title=\"$result_code_string\">again $text</i>\n";