[no subject]

[Patrice Dumas]

branch: master
commit 1a5d96d0dff06ac99a4648973d0bedc35b24b91f
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Feb 4 16:27:52 2024 +0100

    Update POD documentation
---
 tp/Texinfo/Document.pm | 28 +++++++++++++++++++---------
 tp/Texinfo/Indices.pm  | 35 +++++++++++++++++++++++++++--------
 2 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/tp/Texinfo/Document.pm b/tp/Texinfo/Document.pm
index ec984315ba..cf362df8ee 100644
--- a/tp/Texinfo/Document.pm
+++ b/tp/Texinfo/Document.pm
@@ -421,7 +421,7 @@ in the document.
 =item included_files
 
 An array of included file paths as they appear in the document.  Binary
-strings.
+strings.  From both C<@include> and C<@verbatiminclude>.
 
 =item input_encoding_name
 
@@ -516,8 +516,9 @@ by a call to 
L<register_document_sections_list|/register_document_sections_list
 
 =back
 
-Information about defined indices, merged indices and index entries is
-also available through the C<indices_information> method.
+Information about defined indices, indices merging and index entries is
+also available through the C<indices_information> method.  Merged document
+indices are available through C<merged_indices>.
 
 =over
 
@@ -589,6 +590,15 @@ the indices corresponding to the following texinfo
 
 If C<name> is not set, it is set to the index name.
 
+=item $merged_indices = $document->merged_indices()
+
+Merge indices if needed and return merged indices.  The I<$merged_indices>
+returned is a hash reference whose keys are the index names and values arrays
+of index entry structures described in L</index_entries>.
+
+L<< C<Texinfo::Indices::merge_indices>|Texinfo::Indices/$merged_indices = 
merge_indices($indices_information) >>
+is used to merge the indices.
+
 =back
 
 =head2 Registering document and information in document
@@ -601,8 +611,8 @@ parsers codes.
 =item $document = Texinfo::Document::register($tree, $global_information, 
$indices_information, $floats_information, $internal_references_information, 
$global_commands_information, $identifier_target, $labels_list)
 
 Setup a document. There is no reason to call this method out of parsers, as
-it is already done by the Texinfo parsers.  The arguments correspond to
-information returned by the other methods.
+it is already done by the Texinfo parsers.  The arguments are gathered
+during parsing and correspond to information returned by the other methods.
 
 =back
 
@@ -678,10 +688,10 @@ or C<rebuild_tree>:
 X<C<rebuild_document>> X<C<rebuild_tree>>
 
 Return a I<$rebuilt_document>, rebuilt from C data if needed.  If there
-is no need to rebuild the document, the document is returned as is.  The
-document rebuilt is based on the Texinfo parsed I<$document> if
-C<rebuild_document> is called, or on the Texinfo parsed document associated
-to the Texinfo tree I<$tree> if C<rebuild_tree> is called.
+is not C data, the document is returned as is.  The document rebuilt is
+based on the Texinfo parsed I<$document> if C<rebuild_document> is
+called, or on the Texinfo parsed document associated to the Texinfo
+tree I<$tree> if C<rebuild_tree> is called.
 
 If the optional I<$no_store> argument is set, remove the C data.
 
diff --git a/tp/Texinfo/Indices.pm b/tp/Texinfo/Indices.pm
index ff45f49a3b..3aa75c6e1c 100644
--- a/tp/Texinfo/Indices.pm
+++ b/tp/Texinfo/Indices.pm
@@ -248,6 +248,7 @@ sub index_entry_element_sort_string($$$$;$)
   return $sort_string;
 }
 
+# $DOCUMENT_INFO is used in XS to retrieve the document.
 sub _index_entry_element_sort_string_key($$$$$;$)
 {
   my $document_info = shift;
@@ -750,7 +751,7 @@ __END__
 
 =head1 NAME
 
-Texinfo::Indices - sorting and merging indices in Texinfo
+Texinfo::Indices - merging and sorting indices from Texinfo
 
 =head1 SYNOPSIS
 
@@ -791,11 +792,16 @@ with C<sort_indices_by_index> or 
C<sort_indices_by_letter>.
 No method is exported in the default case.
 
 Some methods takes a L<Texinfo::Report> C<$registrar> as argument for
-error reporting.  Some also require Texinfo customization variables
+error reporting.  Error reporting also require Texinfo customization variables
 information, which means an object implementing the C<get_conf> method, in
 practice the main program configuration or a converter
 (L<Texinfo::Convert::Converter/Getting and setting customization
-variables>).  Other common input arguments such as indices information
+variables>).  If the C<$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
+(L<Texinfo::Convert::Converter/Registering error and warning messages>).
+
+Other common input arguments such as indices information
 are obtained from a parsed document, see L<Texinfo::Document>.
 
 =over
@@ -812,12 +818,24 @@ The tree element index entry processed is 
I<$index_entry_element>,
 and can be a C<@subentry>.  I<$main_entry> is the main index entry
 that can be used to gather information.  The I<$options> are options
 used for Texinfo to text conversion for the generation of the sort
-string, typically obtained from
+string.  If the sort string is supposed to be output, the I<$options>
+are typically obtained from
 L<setup_index_entry_keys_formatting|/$option = 
setup_index_entry_keys_formatting($customization_information)>.
 If I<$prefer_reference_element> is set, prefer an untranslated
 element for the formatting as sort string.
 
-=item $merged_entries = merge_indices($indices_information)
+=item ($text, $command) = 
index_entry_first_letter_text_or_command($index_entry)
+
+Return the I<$index_entry> leading text I<$text> or textual command Texinfo
+tree hash reference I<$command>.  Here textual commands means accent
+commands, brace commands without arguments used for character and glyph
+insertion and C<@U>.
+
+This method can in particular be used to format the leading letter
+of an index entry using I<$command> instead of the sort string set by
+C<sort_indices_by_letter>.
+
+=item $merged_indices = merge_indices($indices_information)
 X<C<merge_indices>>
 
 Using information returned by L<< 
C<Texinfo::Document::indices_information>|Texinfo::Document/$indices_information
 = $document->indices_information() >>,
@@ -825,14 +843,15 @@ a structure holding all the index entries by index name 
is returned,
 with all the entries of merged indices merged with those of the indice
 merged into.
 
-The I<$merged_entries> returned is a hash reference whose
+The I<$merged_indices> returned is a hash reference whose
 keys are the index names and values arrays of index entry structures
 described in details in L<Texinfo::Document/index_entries>.
 
 =item $option = setup_index_entry_keys_formatting($customization_information)
 X<C<setup_index_entry_keys_formatting>>
 
-Return options for conversion of Texinfo to text relevant for index keys 
sorting.
+Return options relevant for index keys sorting for conversion of Texinfo
+to text to be output.
 
 =item ($index_entries_sorted, $index_entries_sort_strings) = 
sort_indices_by_index($registrar, $customization_information, 
$merged_index_entries, $indices_information)
 
@@ -857,7 +876,7 @@ with the index name.
 I<$index_entries_sort_strings> is a hash reference associating the index
 entries with the strings that were used to sort them.
 
-Register errors in I<$registrar>.
+Register errors in I<$registrar> or through I<$customization_information>.
 
 =back