Texinfo::Convert::Text
**********************

NAME
====

Texinfo::Convert::Text - Convert Texinfo tree to simple text

SYNOPSIS
========

  use Texinfo::Convert::Text qw(convert ascii_accent text_accents);

  my $result = convert($tree);
  my $result_encoded = convert($tree,
             {'enabled_encoding' => 'utf-8'});
  my $result_converter = convert($tree,
             {'converter' => $converter});

  my $result_accent_text = ascii_accent('e', $accent_command);
  my $accents_text = text_accents($accents, 'utf-8');

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

Texinfo::Convert::Text is a simple backend that converts a Texinfo tree to simple text.  It is used for some command argument expansion in Texinfo::Parser, for instance the file names, or encoding names. The converter is very simple, and, in the default case, cannot handle output strings translation or error handling.

METHODS
=======

$result = convert($tree, $options)

     Convert a Texinfo tree to simple text.  $options is a hash reference of options.  The converter is very simple, and has no internal state besides the options.  It cannot handle as is output strings translation or error storing.

     If the converter option is set, some additional features may be available for the conversion of some @-commands, like output strings translation or error reporting.

     The following options may be set:

     enabled_encoding

          If set, the value is considered to be the encoding name texinfo accented letters should be converted to.  This option corresponds to the --enable-encoding option, or the ENABLE_ENCODING customization variable.

     sc

          If set, the text is upper-cased.

     code

          If set the text is in code style.  (mostly --, ---, '' and `` are kept as is).

     NUMBER_SECTIONS

          If set, sections are numbered when output.

     sort_string

          A somehow internal option to convert to text more suitable for alphabetical sorting rather than presentation.

     converter

          If this converter object is passed to the function, some features of this object may be used during conversion.  Mostly error reporting and strings translation, as the converter object is also supposed to be a Texinfo::Report NAME objet.  See also Texinfo::Convert::Converter NAME.

     expanded_formats_hash

          A reference on a hash.  The keys should be format names (like html, tex), and if thecorresponding  value is set, the format is expanded.

$result_accent_text = ascii_accent($text, $accent_command)

     $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.  The function returns a transliteration of the accented character.

$result_accent_text = ascii_accent_fallback($converter, $text, $accent_command)

     Same as ascii_accent but  with an additional first argument converter, which is in ignored, but needed if this function is to be in argument of functions that need a fallback for accents conversion.

$accents_text = text_accents($accents, $encoding, $set_case)

     $accents is an accent command that may contain other nested accent commands.  The function will format the whole stack of nested accent commands and the innermost text.  If $encoding is set, the formatted text is converted to this encoding as much as possible instead of being converted as simple ascii.  If $set_case is positive, the result is meant to be upper-cased, if it is negative, the result is to be lower-cased.

AUTHOR
======

Patrice Dumas, <pertusus@free.fr>

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

Copyright 2010, 2011, 2012 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.