branch master updated: * tp/Texinfo/Indices.pm: remove export of functions.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new c5920d020e * tp/Texinfo/Indices.pm: remove export of functions.
c5920d020e is described below

commit c5920d020eb50f5d02e46b531de47d1ad7f6cf8b
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Apr 14 12:32:57 2024 +0200

    * tp/Texinfo/Indices.pm: remove export of functions.
    
    * tp/Texinfo/*: fix import of modules related to indices.
    
    Update POD documentation and comments to explain better which method
    should be directly used and why there is no XS override for some
    functions.
---
 ChangeLog                       | 10 ++++++
 tp/Texinfo/Convert/Converter.pm | 60 +++++++++++++++++++--------------
 tp/Texinfo/Convert/HTML.pm      |  1 +
 tp/Texinfo/Convert/IXIN.pm      |  1 -
 tp/Texinfo/Convert/Plaintext.pm |  1 -
 tp/Texinfo/Document.pm          | 45 ++++++++++++++++++++-----
 tp/Texinfo/Indices.pm           | 75 +++++++++++++++++++++++++----------------
 tp/init/chm.pm                  |  1 -
 tp/t/test_utils.pl              |  1 +
 9 files changed, 128 insertions(+), 67 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0e3beaf3e5..f922844968 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2024-04-14  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Indices.pm: remove export of functions.
+
+       * tp/Texinfo/*: fix import of modules related to indices.
+
+       Update POD documentation and comments to explain better which method
+       should be directly used and why there is no XS override for some
+       functions.
+
 2024-04-13  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/XS/main/convert_utils.c (output_files_open_out),
diff --git a/tp/Texinfo/Convert/Converter.pm b/tp/Texinfo/Convert/Converter.pm
index 76f23ccfc7..d7acdaf07f 100644
--- a/tp/Texinfo/Convert/Converter.pm
+++ b/tp/Texinfo/Convert/Converter.pm
@@ -2378,6 +2378,40 @@ translation.  This function is similar to pgettext in 
the Gettext C API.
 
 =back
 
+=head2 Index sorting
+
+You should call the following methods to sort indices in conversion:
+
+=over
+
+=item $sorted_indices = $converter->get_converter_indices_sorted_by_index()
+
+=item $sorted_indices = $converter->get_converter_indices_sorted_by_letter()
+X<C<get_converter_indices_sorted_by_index>>
+X<C<get_converter_indices_sorted_by_letter>>
+
+C<get_converter_indices_sorted_by_letter> returns the indices sorted by index
+and letter, while C<get_converter_indices_sorted_by_index> returns the indices
+with all entries of an index together.
+
+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 I<letter> key with the letter, and an I<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 functions call L<< 
C<Texinfo::Document::sorted_indices_by_letter>|Texinfo::Document/$sorted_indices
 = $document->sorted_indices_by_letter($customization_information, 
$use_unicode_collation, $locale_lang) >>
+or L<< 
C<Texinfo::Document::sorted_indices_by_index>|Texinfo::Document/$sorted_indices 
= $document->sorted_indices_by_index($customization_information, 
$use_unicode_collation, $locale_lang) >>
+with arguments based on C<USE_UNICODE_COLLATION>, C<COLLATION_LANGUAGE> and
+C<DOCUMENTLANGUAGE_COLLATION> customization options, and, if relevant, current
+C<@documentlanguage>.
+
+=back
+
 =head2 Conversion to XML
 
 Some C<Texinfo::Convert::Converter> methods target conversion to XML.
@@ -2537,32 +2571,6 @@ better formatted with new lines added independently of 
the presence
 of newline or comment in the initial Texinfo line, so most converters
 are better off not using this method.
 
-=item $sorted_indices = $converter->get_converter_indices_sorted_by_index()
-
-=item $sorted_indices = $converter->get_converter_indices_sorted_by_letter()
-X<C<get_converter_indices_sorted_by_index>>
-X<C<get_converter_indices_sorted_by_letter>>
-
-C<get_converter_indices_sorted_by_letter> returns the indices sorted by index
-and letter, while C<get_converter_indices_sorted_by_index> returns the indices
-with all entries of an index together.
-
-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 I<letter> key with the letter, and an I<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 functions call L<< 
C<Texinfo::Document::sorted_indices_by_letter>|Texinfo::Document/$sorted_indices
 = $document->sorted_indices_by_letter($customization_information, 
$use_unicode_collation, $locale_lang) >>
-or L<< 
C<Texinfo::Document::sorted_indices_by_index>|Texinfo::Document/$sorted_indices 
= $document->sorted_indices_by_index($customization_information, 
$use_unicode_collation, $locale_lang) >>
-with arguments based on C<USE_UNICODE_COLLATION>, C<COLLATION_LANGUAGE> and
-C<DOCUMENTLANGUAGE_COLLATION> customization options, and, if relevant, current
-C<@documentlanguage>.
-
 =item $filename = sub $converter->node_information_filename($normalized, 
$label_element)
 X<C<node_information_filename>>
 
diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
index 6937da333b..991e5b46f2 100644
--- a/tp/Texinfo/Convert/HTML.pm
+++ b/tp/Texinfo/Convert/HTML.pm
@@ -73,6 +73,7 @@ use Texinfo::Convert::Text;
 use Texinfo::Convert::NodeNameNormalization;
 use Texinfo::ManipulateTree;
 use Texinfo::Structuring;
+# for index_entry_first_letter_text_or_command
 use Texinfo::Indices;
 use Texinfo::Convert::Converter;
 
diff --git a/tp/Texinfo/Convert/IXIN.pm b/tp/Texinfo/Convert/IXIN.pm
index df95b516ab..af0e2cdfa9 100644
--- a/tp/Texinfo/Convert/IXIN.pm
+++ b/tp/Texinfo/Convert/IXIN.pm
@@ -77,7 +77,6 @@ use Texinfo::Options;
 use Texinfo::Common;
 
 use Texinfo::Structuring;
-use Texinfo::Indices;
 
 use Texinfo::Convert::TexinfoSXML;
 
diff --git a/tp/Texinfo/Convert/Plaintext.pm b/tp/Texinfo/Convert/Plaintext.pm
index cf9a7ec309..24f0d483f6 100644
--- a/tp/Texinfo/Convert/Plaintext.pm
+++ b/tp/Texinfo/Convert/Plaintext.pm
@@ -39,7 +39,6 @@ use Encode;
 use Texinfo::Commands;
 use Texinfo::Common;
 use Texinfo::Structuring;
-use Texinfo::Indices;
 use Texinfo::Convert::Texinfo;
 use Texinfo::Convert::Utils;
 use Texinfo::Convert::Text;
diff --git a/tp/Texinfo/Document.pm b/tp/Texinfo/Document.pm
index 3966fcee71..97f33a9d95 100644
--- a/tp/Texinfo/Document.pm
+++ b/tp/Texinfo/Document.pm
@@ -31,11 +31,14 @@ use Texinfo::DocumentXS;
 use Texinfo::XSLoader;
 
 use Texinfo::Common;
-
 use Texinfo::Report;
+use Texinfo::Indices;
 
 our $VERSION = '7.1dev';
 
+# Full XS coverage.  See comments before methods definitions for an
+# explanation of why some methods have no XS override.
+
 my $XS_parser = Texinfo::XSLoader::XS_parser_enabled();
 
 our %XS_overrides = (
@@ -73,6 +76,7 @@ our %XS_overrides = (
     => "Texinfo::DocumentXS::document_floats_information",
   "Texinfo::Document::internal_references_information"
     => "Texinfo::DocumentXS::document_internal_references_information",
+
   "Texinfo::Document::setup_indices_sort_strings"
     => "Texinfo::DocumentXS::setup_indices_sort_strings",
   "Texinfo::Document::indices_sort_strings"
@@ -238,6 +242,9 @@ sub get_conf($$)
   return $self->{'options'}->{$var};
 }
 
+# No XS override, as there is no reason to call this function directly,
+# since it is already called by other methods, in particular
+# sorted_indices_by_*.
 sub merged_indices($)
 {
   my $self = shift;
@@ -251,10 +258,11 @@ sub merged_indices($)
   return $self->{'merged_indices'};
 }
 
-# call setup_index_entries_sort_strings and cache the result.
+# calls Texinfo::Indices::setup_index_entries_sort_strings and caches the
+# result.
 # In general, it is not needed to call that function directly,
-# as it is called by Texinfo::Indices::sort_indices_by_*.  It may
-# be called in advance, however, if errors need to be collected early.
+# as it is called by Texinfo::Indices::sort_indices_by_*.  It could
+# be called in advance if errors need to be collected early.
 sub setup_indices_sort_strings($$)
 {
   my $document = shift;
@@ -270,9 +278,9 @@ sub setup_indices_sort_strings($$)
   }
 }
 
-# similar to setup_indices_sort_strings, but returns the sort strings too.
-# A different function such that Perl data is only built for that function
-# in the XS override.
+# index_entries_sort_strings accessor.  A different function from
+# setup_indices_sort_strings such that it is possible to build Perl data
+# only for this function in XS.
 sub indices_sort_strings($$)
 {
   my $document = shift;
@@ -282,7 +290,10 @@ sub indices_sort_strings($$)
   return $document->{'index_entries_sort_strings'};
 }
 
-# call Texinfo::Indices::sort_indices_by_letter and cache the result
+# calls Texinfo::Indices::sort_indices_by_letter and caches the result.
+# No XS override, as there is no reason to call this function directly,
+# Texinfo::Convert::Converter get_converter_indices_sorted_by_letter
+# should be called directly.
 sub sorted_indices_by_letter($$$$)
 {
   my $document = shift;
@@ -314,7 +325,10 @@ sub sorted_indices_by_letter($$$$)
   return $document->{'sorted_indices_by_letter'}->{$lang_key};
 }
 
-# call Texinfo::Indices::sort_indices_by_index and cache the result
+# calls Texinfo::Indices::sort_indices_by_index and caches the result.
+# No XS override, as there is no reason to call this function directly,
+# Texinfo::Convert::Converter get_converter_indices_sorted_by_index
+# should be called directly.
 sub sorted_indices_by_index($$$$)
 {
   my $document = shift;
@@ -766,6 +780,10 @@ called to merge or sort the indices the first time the 
following
 methods are called.  The results are afterwards associated to the
 document and simply returned.
 
+In general, those methods should not be called directly, instead
+L<Texinfo::Convert::Converter/Index sorting> Converter methods should be
+used, which already call the following functions.
+
 =over
 
 =item $merged_indices = $document->merged_indices()
@@ -778,6 +796,9 @@ 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.
 
+In general, it is not useful to call this function directly, as it is already
+called by index sorting functions.
+
 =item $sorted_indices = 
$document->sorted_indices_by_index($customization_information, 
$use_unicode_collation, $locale_lang)
 
 =item $sorted_indices = 
$document->sorted_indices_by_letter($customization_information, 
$use_unicode_collation, $locale_lang)
@@ -816,6 +837,12 @@ L<< 
C<Texinfo::Indices::sort_indices_by_index>|Texinfo::Indices/$index_entries_s
 and L<< 
C<Texinfo::Indices::sort_indices_by_letter>|Texinfo::Indices/$index_entries_sorted
 = sort_indices_by_letter($document, $registrar, $customization_information, 
$use_unicode_collation, $locale_lang) >>
 are used to sort the indices, if needed.
 
+In general, those methods should not be called directly, instead
+L<< 
C<Texinfo::Convert::Converter::get_converter_indices_sorted_by_index>|Texinfo::Convert::Converter/$sorted_indices
 = $converter->get_converter_indices_sorted_by_index() >>
+and L<< 
C<Texinfo::Convert::Converter::get_converter_indices_sorted_by_letter>|Texinfo::Convert::Converter/$sorted_indices
 = $converter->get_converter_indices_sorted_by_letter() >>
+should be used.  The C<Texinfo::Convert::Converter> methods call
+C<sorted_indices_by_index> and C<sorted_indices_by_letter>.
+
 =back
 
 =head2 Getting errors and error registering object
diff --git a/tp/Texinfo/Indices.pm b/tp/Texinfo/Indices.pm
index 69b4e8c1b5..ba9dd0ccfa 100644
--- a/tp/Texinfo/Indices.pm
+++ b/tp/Texinfo/Indices.pm
@@ -17,6 +17,11 @@
 #
 # Original author: Patrice Dumas <pertusus@free.fr>
 # Parts (also from Patrice Dumas) come from texi2html.pl.
+#
+# Most methods in that module are called from documents or
+# converters methods that cache the results.  Therefore, the relevant
+# interface is, in the general case, with the document or converter
+# when possible.
 
 package Texinfo::Indices;
 
@@ -25,15 +30,16 @@ use 5.00405;
 # See comment at start of HTML.pm
 use if $] >= 5.012, feature => 'unicode_strings';
 
-use strict;
-# Can be used to check that there is no incorrect autovivfication
-#no autovivification qw(fetch delete exists store strict);
-
 # Cannot do that because of sort_indices_by_letter, probably for uc().
 # stop \s from matching non-ASCII spaces, etc.  \p{...} can still be
 # used to match Unicode character classes.
 #use if $] >= 5.014, re => '/a';
 
+use strict;
+
+# Can be used to check that there is no incorrect autovivfication
+#no autovivification qw(fetch delete exists store strict);
+
 use Carp qw(cluck confess);
 
 use Unicode::Normalize;
@@ -43,28 +49,35 @@ use Texinfo::IndicesXS;
 use Texinfo::XSLoader;
 
 use Texinfo::Common;
-
 use Texinfo::Convert::Text;
 
-require Exporter;
-use vars qw($VERSION @ISA @EXPORT_OK %EXPORT_TAGS);
-@ISA = qw(Exporter);
-
-%EXPORT_TAGS = ( 'all' => [ qw(
-  merge_indices
-  sort_indices_by_index
-  sort_indices_by_letter
-) ] );
+# In general, Texinfo::Document depends on this here module, but there
+# is also a dependence to Texinfo::Document through the call to
+# Texinfo::Document::indices_sort_strings call, hence a circular dependency.
+# It is more natural to have Texinfo::Document import the here module,
+# so we do not load Texinfo::Document here.  If we did, there should not be any
+# issue, though, as the modules do not setup data such that their order of
+# loading is not important.
+#use Texinfo::Document;
 
-@EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
+use vars qw($VERSION);
 
 $VERSION = '7.1dev';
 
+# The methods that are usefully called directly (outside of tests) are:
+# index_entry_element_sort_string
+# setup_index_entry_keys_formatting
+# index_entry_first_letter_text_or_command
+
+# There is therefore a full XS coverage of the module as
+# index_entry_first_letter_text_or_command has a C implementation, but no
+# XS override, because it is only a helper function, if needed the calling
+# functions should have XS interfaces.
+
 my $XS_convert = Texinfo::XSLoader::XS_convert_enabled();
 
 # used in conversion only, and should only be loaded with XS converters
 my %XS_convert_overrides = (
-
   "Texinfo::Indices::index_entry_element_sort_string"
     => "Texinfo::IndicesXS::index_entry_element_sort_string",
   "Texinfo::Indices::setup_index_entry_keys_formatting",
@@ -274,8 +287,8 @@ sub _setup_collator($$)
 }
 
 # Not documented, as, in general, it should not be called directly, but
-# through Texinfo::Document::indices_sort_strings that caches the result
-# in the document, itself, in general, called through sorting functions.
+# through Texinfo::Document::indices_sort_strings that caches the
+# result in the document, itself, in general, called through sorting functions.
 sub setup_index_entries_sort_strings($$$$;$)
 {
   my $registrar = shift;
@@ -456,6 +469,7 @@ sub _setup_sort_sortable_strings_collator($$$$$)
   return ($index_sortable_index_entries, $collator);
 }
 
+# Normally called through Texinfo::Document::sorted_indices_by_index only
 sub sort_indices_by_index($$$;$$)
 {
   my $document = shift;
@@ -599,6 +613,7 @@ sub index_entry_first_letter_text_or_command($;$)
   }
 }
 
+# Normally called through Texinfo::Document::sorted_indices_by_letter only
 sub sort_indices_by_letter($$$;$$)
 {
   my $document = shift;
@@ -693,22 +708,23 @@ Texinfo::Indices - merging and sorting indices from 
Texinfo
 
 =head1 SYNOPSIS
 
-  use Texinfo::Indices qw(merge_indices sort_indices_by_letter
-                          sort_indices_by_index);
+  use Texinfo::Indices;
 
   # $document is a parsed Texinfo::Document document.
   my $indices_information = $document->indices_information();
   my $merged_index_entries
-     = merge_indices($indices_information);
+     = 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 = sort_indices_by_letter($document, $registrar,
+    $index_entries_sorted
+      = Texinfo::Indices::sort_indices_by_letter($document, $registrar,
                                                    $config);
   } else {
-    $index_entries_sorted = sort_indices_by_index($document, $registrar,
+    $index_entries_sorted
+      = Texinfo::Indices::sort_indices_by_index($document, $registrar,
                                                   $config);
   }
 
@@ -728,11 +744,12 @@ index entry.
 Note that, in general, the functions used to merge or sort indices
 should not be called directly, corresponding functions
 in L<Texinfo::Document> already call the functions in this module, and,
-in addition, cache the result with the document.
+in addition, cache the result with the document.  Furthermore, it should
+be even better to call converter functions, which call document functions.
 
 =head1 METHODS
 
-No method is exported in the default case.
+No method is exported.
 
 =over
 
@@ -782,7 +799,7 @@ 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>.
 
-In general, this method should not be directly called, instead
+In general, this method should not be called directly, instead
 L<< C<Texinfo::Document::merged_indices>|Texinfo::Document/$merged_indices = 
$document->merged_indices() >>
 should be called on a document, which calls C<merge_indices> if needed and
 associate the merged indices to the document.
@@ -838,9 +855,9 @@ converters error messages reporting functions
 In general, those methods should not be called directly, instead
 L<< 
C<Texinfo::Document::sorted_indices_by_index>|Texinfo::Document/$sorted_indices 
= $document->sorted_indices_by_index($customization_information, 
$use_unicode_collation, $locale_lang) >>
 or L<< 
C<Texinfo::Document::sorted_indices_by_letter>|Texinfo::Document/$sorted_indices
 = $document->sorted_indices_by_letter($customization_information, 
$use_unicode_collation, $locale_lang) >>
-should be called on a document. These functions calls C<sort_indices_by_index> 
or
-C<sort_indices_by_letter> if needed and associate the sorted indices to
-the document.
+should be called on a document. The C<Texinfo::Document> functions call
+C<sort_indices_by_index> or C<sort_indices_by_letter> if needed and associate
+the sorted indices to the document.
 
 =back
 
diff --git a/tp/init/chm.pm b/tp/init/chm.pm
index 9491d72e5e..e52014cc92 100644
--- a/tp/init/chm.pm
+++ b/tp/init/chm.pm
@@ -42,7 +42,6 @@ use Texinfo::Common;
 use Texinfo::Convert::Unicode;
 use Texinfo::Convert::Utils;
 use Texinfo::Convert::Text;
-use Texinfo::Indices;
 
 texinfo_set_format_from_init_file('html');
 
diff --git a/tp/t/test_utils.pl b/tp/t/test_utils.pl
index 9774668ef5..8255cc0ee0 100644
--- a/tp/t/test_utils.pl
+++ b/tp/t/test_utils.pl
@@ -72,6 +72,7 @@ use Texinfo::Document;
 use Texinfo::Convert::PlainTexinfo;
 use Texinfo::ManipulateTree;
 use Texinfo::Structuring;
+# for format_index_entries_sort_strings
 use Texinfo::Indices;
 use Texinfo::Translations;
 use Texinfo::Convert::Plaintext;