Texinfo::Convert::Converter
***************************

NAME
====

Texinfo::Convert::Converter - Parent class for Texinfo tree converters

SYNOPSIS
========

  package Texinfo::Convert::MyConverter;

  use Texinfo::Convert::Converter;
  @ISA = qw(Texinfo::Convert::Converter);

  sub converter_defaults ($$) {
    return %myconverter_defaults;
  }
  sub converter_initialize($) {
    my $self = shift;
    $self->{'document_context'} = [{}];
  }
  sub converter_global_commands($) {
    return ('documentlanguage', documentencoding', 'paragraphindent');
  }

  sub convert($$) {
    ...
  }
  sub convert_tree($$) {
    ...
  }
  sub output ($$) {
    ...
  }

  # end of Texinfo::Convert::MyConverter

  my $converter = Texinfo::Convert::MyConverter->converter(
                                               {'parser' => $parser});
  $converter->output($texinfo_tree);

DESCRIPTION
===========

Texinfo::Convert::Converter is a super class that can be used to simplify converters initialization.  The class also provide some useful methods.

In turn, the converter should define some methods.  Three are optional, converter_defaults, converter_initialize and converter_global_commands and used for initialization, to give Texinfo::Convert::Converter some informations.

The convert_tree method is more or less mandatory and should convert portions of Texinfo tree.  The output and convert are not required, but customarily used by converters as entry points for conversion to a file with headers and so on, or conversion of a whole Texinfo tree.

Existing backends may be used as examples that implement those methods.  Texinfo::Convert::Texinfo together with Texinfo::Convert::PlainTexinfo, as well as Texinfo::Convert::TextContent are trivial examples. Texinfo::Convert::Text is less trivial, although still simplistic, while Texinfo::Convert::DocBook is a real converter that is also not too complex.

Texinfo::Common NAME, Texinfo::Convert::Unicode NAME and Texinfo::Report NAME document modules or additional function that may be useful for backends, while the parsed Texinfo tree is described in Texinfo::Parser NAME.

METHODS
=======

Initialization
--------------

A module subclassing Texinfo::Convert::Converter is created by calling the converter method that should be inherited from Texinfo::Convert::Converter.

$converter = MyConverter->converter($options)

     The $options hash reference holds options for the converter.  In this option hash reference a parser object may be associated with the parser key.  The other options should be configuration options described in the Texinfo manual. Those options, when appropriate, override the document content.

     The converter function returns a converter object (a blessed hash reference) after checking the options and performing some initializations, especially when a parser is given among the options.  The converter is also initialized as a Texinfo::Report NAME.

To help with these initializations, the modules can define three methods:

%defaults = $converter->converter_defaults($options)

     The converter can provide a defaults hash for configurations options. The $options hash reference holds options for the converter.

@global_commands = $converter->converter_global_commands()

     The list returned is the list of Texinfo global commands (like @paragraphindent, @documentlanguage...) that are relevant for the converter.

converter_initialize

     This method is called at the end of the converter initialization.

Helper methods
--------------

Texinfo::Convert::Converter provides methods that may be useful for every converter:

$converter->get_conf($option_string)

     Returns the value of the Texinfo configuration option $option_string.

$converter->set_conf($option_string, $value)

     Set the Texinfo configuration option $option_string to $value if not set as a converter option.

$converter->force_conf($option_string, $value)

     Set the Texinfo configuration option $option_string to $value. This should rarely be used, but the purpose of this method is to be able to revert a configuration that is always wrong for a given output format, like the splitting for example.

$result = $converter->convert_document_sections($root, $file_handler)

     This method splits the $root Texinfo tree at sections and calls convert_tree on the elements.  If the optional $file_handler is given in argument, the result are output in $file_handler, otherwise the resulting string is returned.

$result = $converter->convert_accents($accent_command, \&format_accents, $in_upper_case)

     $accent_command is an accent command, which may have other accent commands nested.  The function returns the accents formatted either as encoded letters, or formatted using \&format_accents. If $in_upper_case is set, the result should be upper cased.

Other Texinfo::Convert::Converter methods target conversion to XML:

$protected_text = $converter->xml_protect_text($text)

     Protect special XML characters (&, <, >, ") of $text.

$comment = $converter->xml_comment($text)

     Returns an XML comment for $text.

$result = xml_accent($text, $accent_command, $in_upper_case, $use_numeric_entities)

     $text is the text appearing within an accent command.  $accent_command should be a Texinfo tree element corresponding to an accent command taking an argument.  $in_upper_case is optional, and, if set, the text is put in upper case.  The function returns the accented letter as XML entity if possible.  $use_numeric_entities is also optional, and, if set, and there is no XML entity, the numerical entity corresponding to unicode points is preferred to an ascii transliteration.

$result = $converter->xml_accents($accent_command, $in_upper_case)

     $accent_command is an accent command, which may have other accent commands nested.  If $in_upper_case is set, the result should be upper cased.  The function returns the accents formatted as XML.

SEE ALSO
========

Texinfo::Common NAME, Texinfo::Convert::Unicode NAME, Texinfo::Report NAME and Texinfo::Parser NAME.

AUTHOR
======

Patrice Dumas, <pertusus@free.fr>

COPYRIGHT AND LICENSE
=====================

Copyright (C) 2011, 2012, 2013 Free Software Foundation, Inc.

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.