doc/tta_api/api_includes/Texinfo-Indices.texi

@node Texinfo@asis{::}Indices
@chapter Texinfo::Indices

@node Texinfo@asis{::}Indices NAME
@section Texinfo::Indices NAME

Texinfo::Indices - merging and sorting indices from Texinfo

@node Texinfo@asis{::}Indices SYNOPSIS
@section Texinfo::Indices SYNOPSIS

@verbatim
  use Texinfo::Indices;

  # $document is a parsed Texinfo::Document document.
  my $indices_information = $document->indices_information();
  my $merged_index_entries
     = Texinfo::Indices::merge_indices($indices_information);

  my $indices_sort_strings
    = Texinfo::Document::indices_sort_strings($document, undef);

  my $index_entries_sorted;
  if ($sort_by_letter) {
    $index_entries_sorted
      = Texinfo::Indices::sort_indices_by_letter($indices_sort_strings);
  } else {
    $index_entries_sorted
      = Texinfo::Indices::sort_indices_by_index($indices_sort_strings);
  }
@end verbatim

@node Texinfo@asis{::}Indices NOTES
@section Texinfo::Indices 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{::}Indices DESCRIPTION
@section Texinfo::Indices DESCRIPTION

Main functions merge and sort indices.  These functions should generally be
called indirectly.

Other functions help presenting sorting strings especially generated to be
output or are helper functions related to indices or index entries.

@node Texinfo@asis{::}Indices METHODS
@section Texinfo::Indices METHODS

No method is exported.

@code{merge_indices} may be used to merge indices.  Document indices may be sorted
with @code{sort_indices_by_index} or @code{sort_indices_by_letter}.  The sorting may
be influenced by the current language.  (In the current implementation,
sorting keys formatted internally in a language-independent manner are used.)

Note that, in general, the functions used to merge or sort indices
should not be called directly, corresponding functions
in @ref{Texinfo@asis{::}Document NAME,, Texinfo::Document} already call the functions in this module, and,
in addition, cache the result with the document.  Furthermore, it should
be even better to call converter functions, which call document functions.

@table @asis
@item $merged_indices = merge_indices($indices_information)
@anchor{Texinfo@asis{::}Indices $merged_indices = merge_indices($indices_information)}
@cindex @code{merge_indices}

Returns a structure holding all the index entries by index name
with all the entries of merged indices merged with those of the indice
merged into.  The @emph{$indices_information} argument should be an hash reference
with indices information, it is described in details in
@ref{Texinfo@asis{::}Document $indices_information = $document->indices_information(),, @code{Texinfo::Document::indices_information}}.

The @emph{$merged_indices} returned is a hash reference whose
keys are the index names and values arrays of index entry structures
described in details in @ref{Texinfo@asis{::}Document index_entries}.

In general, this method should not be called directly, instead
@ref{Texinfo@asis{::}Document $merged_indices = $document->merged_indices(),, @code{Texinfo::Document::merged_indices}}
should be called on a document, which calls @code{merge_indices} if needed and
associate the merged indices to the document.

@item $index_entries_sorted = sort_indices_by_index($document, $converter, $use_unicode_collation, $lang_sorting_locale)
@anchor{Texinfo@asis{::}Indices $index_entries_sorted = sort_indices_by_index($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale)}

@item $index_entries_sorted = sort_indices_by_letter($document, $converter, $use_unicode_collation, $lang_sorting_locale)
@anchor{Texinfo@asis{::}Indices $index_entries_sorted = sort_indices_by_letter($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale)}
@cindex @code{sort_indices_by_index}
@cindex @code{sort_indices_by_letter}

@code{sort_indices_by_letter} sorts by index and letter, while
@code{sort_indices_by_index} sort all entries of an index together.
In both cases, a hash reference with index names as keys @emph{$index_entries_sorted}
is returned.
Indices are obtained from @emph{$document}, and should have been merged
previously, in general by using
@ref{Texinfo@asis{::}Document $merged_indices = $document->merged_indices(),, @code{Texinfo::Document::merged_indices}}.

By default, indices are sorted according to the @emph{Unicode Collation Algorithm}
defined in the @url{http://www.unicode.org/reports/tr10/, Unicode Technical Standard
#10}, without language-specific collation
tailoring.  If @emph{$use_unicode_collation} is set to 0, the sorting will not use
the @emph{Unicode Collation Algorithm} and simply sort according to the codepoints.
The optional @emph{$lang_sorting_locale} language is used for linguistic
tailoring of the sorting, if possible.

When sorting by letter, an array reference of letter hash references is
associated with each index name.  Each letter hash reference has two
keys, a @emph{letter} key with the letter, and an @emph{entries} key with an array
reference of sorted index entries beginning with the letter.  The letter
is a character string suitable for sorting letters, but is not necessarily
the best to use for output.

When simply sorting, the array of the sorted index entries is associated
with the index name.

The optional argument @emph{$converter} is used for error reporting if present,
otherwise the @emph{$document} is used.

In general, those methods should not be called directly, instead
@ref{Texinfo@asis{::}Document $sorted_indices = sorted_indices_by_index($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale),, @code{Texinfo::Document::sorted_indices_by_index}}
or @ref{Texinfo@asis{::}Document $sorted_indices = sorted_indices_by_letter($document@comma{} $converter@comma{} $use_unicode_collation@comma{} $lang_sorting_locale),, @code{Texinfo::Document::sorted_indices_by_letter}}
should be called on a document. The @code{Texinfo::Document} functions call
@code{sort_indices_by_index} or @code{sort_indices_by_letter} if needed and associate
the sorted indices to the document.

@end table

Functions help setting up textual sorting strings, for instance for output.
Although they may be generated by calling the same functions, these sorting
strings are independent from the sorting keys used internally to sort indices.

@table @asis
@item $sort_string = index_entry_element_sort_string($document_info, $main_entry, $index_entry_element, $options, $prefer_reference_element, $converter, $debug_level)
@anchor{Texinfo@asis{::}Indices $sort_string = index_entry_element_sort_string($document_info@comma{} $main_entry@comma{} $index_entry_element@comma{} $options@comma{} $prefer_reference_element@comma{} $converter@comma{} $debug_level)}
@cindex @code{index_entry_element_sort_string}

Return a string suitable as a sorting string for index entries, possibly
to be used in output.
@emph{$document_info} is solely used by C code to retrieve the document data.
@emph{$document_info} can be a converter based on @ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter} or
a @ref{Texinfo@asis{::}Document NAME,, Texinfo::Document} document.

The tree element index entry processed is @emph{$index_entry_element},
and can be a @code{@@subentry}.  @emph{$main_entry} is the main index entry
that can be used to gather information.

The @emph{$options} are options used for Texinfo conversion to text for the
generation of the sorting string and, when called directly (and not through
index sorting functions), are generally obtained from
@ref{Texinfo@asis{::}Indices $option = setup_index_entry_keys_formatting($customization_information),, setup_index_entry_keys_formatting}
early on, and reused in every call.

If @emph{$prefer_reference_element} is set, prefer an untranslated
element for the formatting as sorting string.

If @emph{$converter} is set use the converter function for translation.
This argument is ignored in XS, so should only be set when called
from a function with an XS override, such that the argument
is set only from functions used if XS is not being used at all.

@item $option = setup_index_entry_keys_formatting($customization_information)
@anchor{Texinfo@asis{::}Indices $option = setup_index_entry_keys_formatting($customization_information)}
@cindex @code{setup_index_entry_keys_formatting}

Return options relevant for index keys sorting for conversion of Texinfo
to output.

Should be called early, since it sets up language information corresponding to
the language current at the end of the preamble.  (Note that commands appearing
in index entry whose output may depend on a language are rare.)

@end table

Other functions.

@table @asis
@item $entry_content_element = index_content_element($element, $prefer_reference_element, $converter, $debug_level)
@anchor{Texinfo@asis{::}Indices $entry_content_element = index_content_element($element@comma{} $prefer_reference_element@comma{} $converter@comma{} $debug_level)}

FIXME incorrect, does not exist anymore, converter and document variants.

Return a Texinfo tree element corresponding to the content of the index
entry associated to @emph{$element}.  If @emph{$prefer_reference_element} is set,
prefer an untranslated element.  If the element is an index command like
@code{@@cindex} or an @code{@@ftable} @code{@@item}, the content element is the argument
of the command.  If the element is a definition line, the index entry
element is based on the name and class.  If the @emph{$converter} optional
argument is set, use a converter method for the translation.

@item ($text, $command) = index_entry_first_letter_text_or_command($index_entry, $converter, $debug_level)
@anchor{Texinfo@asis{::}Indices ($text@comma{} $command) = index_entry_first_letter_text_or_command($index_entry@comma{} $converter@comma{} $debug_level)}

Return the @emph{$index_entry} leading text @emph{$text} or textual command Texinfo
tree hash reference @emph{$command}.  Here textual commands means accent
commands, brace commands without arguments used for character and glyph
insertion and @code{@@U}.

This method can in particular be used to format the leading letter
of an index entry using @emph{$command} instead of using the sort string letters
returned by @code{sort_indices_by_letter}.

@end table

@node Texinfo@asis{::}Indices SEE ALSO
@section Texinfo::Indices SEE ALSO

@url{http://www.gnu.org/s/texinfo/manual/texinfo/, Texinfo manual},
@ref{Texinfo@asis{::}Document NAME,, Texinfo::Document}.

@node Texinfo@asis{::}Indices AUTHOR
@section Texinfo::Indices AUTHOR

Patrice Dumas, <bug-texinfo@@gnu.org>

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