12.1.4 Target Tree Element Link ¶

User-defined code in functions replacing default conversion functions for @xref and similar @-commands output, @menu, @node, sectioning commands, @printindex and @listoffloats formatting requires links, labels and files information, mainly to output hyperlinks to target commands.

Target @-commands are @-commands that are associated with an identifier and can be linked to. They corresponds first to @-commands with unique identifier used as labels, @node, @anchor and @float. Sectioning commands, index entries, footnotes are also associated with targets. The “virtual” elements associated with special output units are also associated with targets leading to each special unit (see Output Units in User Defined Functions).

To get the unique Texinfo tree element corresponding to a label, use label_command:

Function: \%element = $converter->label_command ($label) ¶

Return the element in the tree that $label refers to.

For example:

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

Labels are available for target @-commands and for @-command referring to target elements such as @xref or @menu entry node argument as the extra ‘normalized’ element key.

For example, the first @xref argument ‘normalized’ element key may be used to get the node or anchor element it points to:

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

Tree elements not associated with a label are obtained each differently. For example, elements associated with index entries can be obtained using the Texinfo parsed document index entries with $converter->get_info('document')->indices_information() (see Converter General Information), or through sorted indices information (see Specific Formatting for Indices). Footnote elements can be obtained through the @footnote conversion function, and can also be passed to footnote formatting functions (see Customizing Footnotes). Floats elements in @listoffloats can be obtained from $converter->get_info('document')->floats_information() (see Converter General Information).

To get the identifier, file name and href of tree elements that may be used as link target, use command_id, command_filename and command_href:

Function: $identifier = $converter->command_id (\%target_element) ¶

Returns the id specific of the \%target_element tree element.

Function: $file_name = $converter->command_filename (\%target_element) ¶

Returns the file name of the \%target_element tree element.

Function: $href = $converter->command_href (\%target_element, $source_filename, $source_command, $specified_target) ¶

Return string for linking to \%target_element with <a href> or undef if not found or empty. $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. $specified_target is an optional identifier that overrides the target identifier if set.

To get the text of tree elements that may be used as link description, use command_text:

Function: $result = $converter->command_text (\%target_element, $type) ¶

Return the information to be used for a hyperlink to \%target_element. The information returned depends on $type:

text

Return text.

string

Return text in string context. See Init File Expansion Contexts: Normal, Preformatted, Code, String, Math.

Using those functions, a target element hyperlink can be constructed as:

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

To get a Texinfo tree of elements that may be used as link description, use command_tree:

Function: $result = $converter->command_tree (\%target_element, $no_number) ¶

Return the a Texinfo tree to be used for a hyperlink to \%target_element. If $no_number is set, return a Texinfo elements tree representing text without a chapter number being included.

To obtain the top level command element associated with a footnote, float or index entry target element, use command_root_element_command:

Function: \%top_level_element = $converter->command_root_element_command (\%target_element) ¶

Return the top level element, either a @node or a sectioning element \%target_element is in.

This is used in indices formatting to link to index entry associated sectioning element in addition to linking to the index entry location. For example:

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

To get the node element associated with a target element, use command_node:

Function: \%node_element = $converter->command_node (\%target_element) ¶

Return the node element associated with \%target_element.

For elements that are not target elements, use get_element_root_command_element to get the root level Perl tree element and the output unit containing the element:

Function: \%top_level_element, \%output_unit = $converter->get_element_root_command_element (\%element) ¶

Return the top level element and output unit a Texinfo tree \%element is in. Both the top level element and the output unit may be undefined, depending on how the converter is called and on the Texinfo tree. The top level element returned is also determined by the customization variable USE_NODES. If USE_NODES is set the @node is preferred, otherwise the sectioning command is preferred.

For example to get the @node or sectioning root command tree element containing a @printindex element tree and the associated identifier for the formatting of the @printindex Texinfo tree element:

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