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);
# $registrar is a Texinfo::Report object. $config is an object
# implementing the get_conf() method.
my $index_entries_sorted;
if ($sort_by_letter) {
$index_entries_sorted
= Texinfo::Indices::sort_indices_by_letter($document, $registrar,
$config);
} else {
$index_entries_sorted
= Texinfo::Indices::sort_indices_by_index($document, $registrar,
$config);
}
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.
merge_indices may be used to merge indices. Document indices may be sorted
with sort_indices_by_index or sort_indices_by_letter. Other functions
deal with formatting of index entries as text or getting information on
index entry.
Note that, in general, the functions used to merge or sort indices should not be called directly, corresponding functions in 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.
No method is exported.
Return a string suitable as a sort string, for index entries.
$document_info is used by C code to retrieve the document data,
using the document_descriptor key. $document_info can be a
converter based on Texinfo::Convert::Converter, a Texinfo::Document
document, otherwise document_descriptor need, in general, to be
set up explicitely.
The tree element index entry processed is $index_entry_element,
and can be a @subentry. $main_entry is the main index entry
that can be used to gather information.
The $options are options used for Texinfo to text conversion for the generation of the sort string. If the sort string is supposed to be output, the $options are typically obtained from setup_index_entry_keys_formatting.
If $prefer_reference_element is set, prefer an untranslated element for the formatting as sort string.
Return the $index_entry leading text $text or textual command Texinfo
tree hash reference $command. Here textual commands means accent
commands, brace commands without arguments used for character and glyph
insertion and @U.
This method can in particular be used to format the leading letter
of an index entry using $command instead of the sort string set by
sort_indices_by_letter.
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 $indices_information argument should be an hash reference
with indices information, it is described in details in
Texinfo::Document::indices_information.
The $merged_indices returned is a hash reference whose keys are the index names and values arrays of index entry structures described in details in Texinfo::Document index_entries.
In general, this method should not be called directly, instead
Texinfo::Document::merged_indices
should be called on a document, which calls merge_indices if needed and
associate the merged indices to the document.
Return options relevant for index keys sorting for conversion of Texinfo to text to be output.
sort_indices_by_letter sorts by index and letter, while
sort_indices_by_index sort all entries of an index together.
Indices are obtained from $document, and should have been merged
previously, in general by using
Texinfo::Document::merged_indices.
In both cases, a hash reference with index names as keys $index_entries_sorted
is returned.
By default, indices are sorted according to the Unicode Collation Algorithm defined in the Unicode Technical Standard #10, without language-specific collation tailoring. If $use_unicode_collation is set to 0, the sorting will not use the Unicode Collation Algorithm and simply sort according to the codepoints. If $locale_lang is set, the 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 letter key with the letter, and an 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 $registrar argument can be set to a Texinfo::Report object.
Error reporting also requires Texinfo customization variables
information, which means an object implementing the get_conf method, a
converter (Getting and setting customization variables) or a document Getting customization options values registered in document) as $customization_information argument. If
the $registrar argument is not set, the object used to get customization
information is assumed to be a converter, and the error reporting uses
converters error messages reporting functions
(Registering error and warning messages).
In general, those methods should not be called directly, instead
Texinfo::Document::sorted_indices_by_index
or Texinfo::Document::sorted_indices_by_letter
should be called on a document. The Texinfo::Document functions call
sort_indices_by_index or sort_indices_by_letter if needed and associate
the sorted indices to the document.
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.