Texinfo::Convert::NodeNameNormalization
***************************************

Texinfo::Convert::NodeNameNormalization NAME
============================================

Texinfo::Convert::NodeNameNormalization - Normalize and transliterate Texinfo trees

Texinfo::Convert::NodeNameNormalization SYNOPSIS
================================================

  use Texinfo::Convert::NodeNameNormalization qw(convert_to_identifier
                                        normalize_transliterate_texinfo);

  my $normalized = convert_to_identifier($node_element->{'args'}->[0]);

  my $file_name
    = normalize_transliterate_texinfo($section_element->{'args'}->[0]);

Texinfo::Convert::NodeNameNormalization 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::NodeNameNormalization DESCRIPTION
===================================================

Texinfo::Convert::NodeNameNormalization allows to normalize node names with convert_to_normalized and convert_to_identifier. convert_to_identifier follows the specification described in the Texinfo manual HTML Xref node.  This is useful whenever one want a unique identifier for Texinfo content, which is only composed of letter, digits, - and _, for example for @node, @float and @anchor names normalization. convert_to_normalized leaves out the step of protecting characters.

It is also possible to transliterate non-ASCII letters, instead of mangling them, with normalize_transliterate_texinfo, losing the uniqueness feature of normalized node names.

Another method, transliterate_protect_file_name transliterates non-ASCII letters and protect characters that should not appear on file names.

Texinfo::Convert::NodeNameNormalization METHODS
===============================================

$partially_normalized = convert_to_normalized($tree)

     The Texinfo $tree is returned as a string, with @-commands and spaces normalized as described in the Texinfo manual HTML Xref node.  ASCII 7-bit characters other than spaces and non-ASCII characters are left as is in the resulting string.

$normalized = convert_to_identifier($tree)

     The Texinfo $tree is returned as a string, normalized as described in the Texinfo manual HTML Xref node.

     The result will be poor for Texinfo trees which are not @-command arguments (on an @-command line or in braces), for instance if the tree contains @node or block commands.

$transliterated = normalize_transliterate_texinfo($tree, $no_unidecode)

     The Texinfo $tree is returned as a string, with non-ASCII letters transliterated as ASCII, but otherwise similar with convert_to_identifier output.  If the optional $no_unidecode argument is set, Text::Unidecode is not used for characters whose transliteration is not built-in.

$transliterated = transliterate_texinfo($tree, $no_unidecode)

     The Texinfo $tree is returned as a string, with non-ASCII letters transliterated as ASCII.  If the optional $no_unidecode argument is set, Text::Unidecode is not used for characters whose transliteration is not built-in.

$file_name = transliterate_protect_file_name($string, $no_unidecode)

     The string $string is returned with non-ASCII letters transliterated as ASCII, and ASCII characters not safe in file names protected as in node normalization.  If the optional $no_unidecode argument is set, Text::Unidecode is not used for characters whose transliteration is not built-in.

Texinfo::Convert::NodeNameNormalization AUTHOR
==============================================

Patrice Dumas, <pertusus@free.fr>

Texinfo::Convert::NodeNameNormalization 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.