@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization
@chapter Texinfo::Convert::NodeNameNormalization

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization NAME
@section Texinfo::Convert::NodeNameNormalization NAME

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

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization SYNOPSIS
@section Texinfo::Convert::NodeNameNormalization SYNOPSIS

@verbatim
  use Texinfo::Convert::NodeNameNormalization qw(normalize_node
                                        normalize_transliterate_texinfo);

  my $normalized = normalize_node({'contents' => $node_contents});

  my $file_name = normalize_transliterate_texinfo({'contents'
                                            => $section_contents});
@end verbatim

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization NOTES
@section Texinfo::Convert::NodeNameNormalization NOTES

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

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization DESCRIPTION
@section Texinfo::Convert::NodeNameNormalization DESCRIPTION

@code{Texinfo::Convert::NodeNameNormalization} allows to normalize node names,
with @code{normalize_node} following the specification described in the
Texinfo manual @emph{HTML Xref} node.  This is useful whenever one want a
unique identifier for Texinfo content, which is only composed of letter,
digits, @code{-} and @code{_}.  In @ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser}, @code{normalize_node} is used
for @code{@@node}, @code{@@float} and @code{@@anchor} names normalization, but also @code{@@float}
types and @code{@@acronym} and @code{@@abbr} first argument.

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

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

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization METHODS
@section Texinfo::Convert::NodeNameNormalization METHODS

@table @asis
@item $partially_normalized = convert_to_normalized($tree)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $partially_normalized = convert_to_normalized($tree)}
@cindex @code{convert_to_normalized}

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

@item $normalized = normalize_node($tree)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $normalized = normalize_node($tree)}
@cindex @code{normalize_node}

The Texinfo @emph{$tree} is returned as a string, normalized as described in the
Texinfo manual @emph{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
@code{@@node} or block commands.

@item $transliterated = normalize_transliterate_texinfo($tree, $no_unidecode)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $transliterated = normalize_transliterate_texinfo($tree@comma{} $no_unidecode)}
@cindex @code{normalize_transliterate_texinfo}

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

@item $transliterated = transliterate_texinfo($tree, $no_unidecode)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $transliterated = transliterate_texinfo($tree@comma{} $no_unidecode)}
@cindex @code{transliterate_texinfo}

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

@item $file_name = transliterate_protect_file_name($string, $no_unidecode)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $file_name = transliterate_protect_file_name($string@comma{} $no_unidecode)}
@cindex @code{transliterate_protect_file_name}

The string @emph{$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 @emph{$no_unidecode} argument is set,
@code{Text::Unidecode} is not used for characters whose transliteration is not
built-in.

@end table

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization AUTHOR
@section Texinfo::Convert::NodeNameNormalization AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Convert@asis{::}NodeNameNormalization COPYRIGHT AND LICENSE
@section 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.