Texinfo::Convert::Utils
***********************

Texinfo::Convert::Utils NAME
============================

Texinfo::Convert::Utils - miscellaneous functions usable in all converters

Texinfo::Convert::Utils SYNOPSIS
================================

  use Texinfo::Convert::Utils;

  my $today_tree = Texinfo::Convert::Utils::expand_today($converter);
  my $verbatiminclude_tree
     = Texinfo::Convert::Utils::expand_verbatiminclude(undef, $converter,
                                                       $verbatiminclude);

Texinfo::Convert::Utils NOTES
=============================

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats.  There is no promise of API stability.

Texinfo::Convert::Utils DESCRIPTION
===================================

miscellaneous methods that may be useful for backends converting texinfo trees.  This module contains the methods that can be used in converters which do not inherit from Texinfo::Convert::Converter.

Texinfo::Convert::Utils METHODS
===============================

No method is exported in the default case.

Most methods takes a $converter as argument, in some cases optionally, to get some information, see Texinfo::Convert::Converter Getting and setting customization variables and use methods for error reporting, see Texinfo::Convert::Converter and Texinfo::Report, and for strings translations, see Texinfo::Translations.

Even when the caller does not inherit from Texinfo::Convert::Converter, it could implement the required interfaces and could also have a converter available in some cases, to call the functions which require a converter.

$result = add_heading_number($converter, $heading_element, $heading_text, $do_number)

     The $converter argument may be undef.  $heading_element is a heading command tree element.  $heading_text is the already formatted heading text.  if the $do_number optional argument is defined and false, no number is used and the text is returned as is. This function returns the heading with a number and the appendix part if needed.  If $converter is not defined, the resulting string won't be translated.

($category, $class, $type, $name, $arguments) = definition_arguments_content($element)

     $element should be a @def* Texinfo tree element.  The $category, $class, $type, $name are elements corresponding to the definition @-command line.  Texinfo elements on the @-command line corresponding to arguments in the function definition are returned in the $arguments array reference. Arguments correspond to text following the other elements on the @-command line.  If there is no argument, $arguments will be undef.

$tree = definition_category_tree($converter, $def_line)

     The $converter argument may be undef.  $def_line is a def_line texinfo tree container.  This function returns a texinfo tree corresponding to the category of the $def_line taking the class into account, if there is one. If $converter is not defined, the resulting string won't be translated.

($encoded_name, $encoding) = $converter->encoded_input_file_name($converter, $character_string_name, $input_file_encoding)

($encoded_name, $encoding) = $converter->encoded_output_file_name($converter, $character_string_name)

     Encode $character_string_name in the same way as other file names are encoded in converters, based on customization variables, and possibly on the input file encoding.  Return the encoded name and the encoding used to encode the name.  The encoded_input_file_name and encoded_output_file_name functions use different customization variables to determine the encoding.  The $converter argument is not optional and is used both to access to customization variables and to access to parser information.

     The <$input_file_encoding> argument is optional.  If set, it is used for the input file encoding.  It is useful if there is more precise information on the input file encoding where the file name appeared.

$tree = expand_today($converter)

     Expand today's date, as a texinfo tree with translations.  The $converter argument is not optional and is used both to retrieve customization information and to translate strings.

$tree = expand_verbatiminclude($registrar, $customization_information, $verbatiminclude)

     The $registrar argument may be undef.  The $customization_information argument is required and is used to retrieve customization information Texinfo::Convert::Converter Getting and setting customization variables. $verbatiminclude is a @verbatiminclude tree element.  This function returns a @verbatim tree elements after finding the included file and reading it.  If $registrar is not defined, error messages are not registered.

(\@contents, \@accent_commands) = find_innermost_accent_contents($element)

     $element should be an accent command Texinfo tree element.  Returns an array reference containing the innermost accent @-command contents, normally a text element with one or two letter, and an array reference containing the accent commands nested in $element (including $element).

$heading_element = find_root_command_next_heading_command($element, $expanded_format_raw, $do_not_ignore_contents, $do_not_ignore_index_entries)

     Return an heading element found in the $element contents if it appears before contents that could be formatted.  $expanded_format_raw is a hash reference with raw output formats (html, docbook, xml...) as keys, associated value should be set for expanded raw output formats. $do_not_ignore_contents is optional.  If set, @contents and @shortcontents are considered to be formatted. $do_not_ignore_index_entries is optional.  If set, index entries are considered to be formatted.

     Only heading elements corresponding to @heading, @subheading and similar @-commands that are not associated to nodes in general are found, not sectioning commands.

Texinfo::Convert::Utils SEE ALSO
================================

Texinfo::Convert::Converter and Texinfo::Translations.

Texinfo::Convert::Utils AUTHOR
==============================

Patrice Dumas, <pertusus@free.fr>

Texinfo::Convert::Utils COPYRIGHT AND LICENSE
=============================================

Copyright 2010- Free Software Foundation, Inc.  See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.