doc/tta_api/api_includes/Texinfo-Convert-NodeNameNormalization.texi

@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(convert_to_node_identifier
                                        normalize_transliterate_texinfo);

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

  my $file_name
    = normalize_transliterate_texinfo($section_element->{'contents'}->[0]);
@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{convert_to_normalized} and @code{convert_to_node_identifier}.
@code{convert_to_node_identifier} follows 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{_},
for example for @code{@@node}, @code{@@float} and @code{@@anchor} names normalization.
@code{convert_to_identifier} leaves out the step of normalizing @code{Top}.
@code{convert_to_normalized} leaves out the step of protecting characters.

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 = convert_to_node_identifier($tree)
@anchor{Texinfo@asis{::}Convert@asis{::}NodeNameNormalization $normalized = convert_to_node_identifier($tree)}

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

@cindex @code{convert_to_identifier}
@cindex @code{convert_to_node_identifier}


With @code{convert_to_node_identifier}, the Texinfo @emph{$tree} is returned as a
string, normalized as described in the Texinfo manual @emph{HTML Xref} node.
@code{convert_to_identifier} leaves out the normalization of the name if it
is a @emph{Top} node name.

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{convert_to_identifier}
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, <bug-texinfo@@gnu.org>

@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.