branch master updated: * tp/Texinfo/Document.pm (%XS_overrides, register_document_options), tp/Texinfo/XS/main/DocumentXS.xs (register_document_options), tp/t/test_utils.pl (test), tp/texi2any.pl: rename register_options as register_document_options. Pass a hash of customization variables to register_document_options, call get_customization_options_hash in the calling code. Remove _XS_set_document_options.

[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 dc184dcf36 * tp/Texinfo/Document.pm (%XS_overrides, 
register_document_options), tp/Texinfo/XS/main/DocumentXS.xs 
(register_document_options), tp/t/test_utils.pl (test), tp/texi2any.pl: rename 
register_options as register_document_options.  Pass a hash of customization 
variables to register_document_options, call get_customization_options_hash in 
the calling code.  Remove _XS_set_document_options.
dc184dcf36 is described below

commit dc184dcf36271fd8bf787e4192bbe5865ab854b9
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Tue Apr 9 00:49:49 2024 +0200

    * tp/Texinfo/Document.pm (%XS_overrides, register_document_options),
    tp/Texinfo/XS/main/DocumentXS.xs (register_document_options),
    tp/t/test_utils.pl (test), tp/texi2any.pl: rename register_options as
    register_document_options.  Pass a hash of customization variables to
    register_document_options, call get_customization_options_hash in the
    calling code.  Remove _XS_set_document_options.
    
    * tp/t/test_utils.pl (test): remove a useless setting of
    document_descriptor in document.
    
    Update POD documentation.
---
 ChangeLog                        | 14 +++++++++
 tp/TODO                          |  9 ------
 tp/Texinfo/Document.pm           | 62 ++++++++++++++++++++++++++--------------
 tp/Texinfo/Structuring.pm        | 17 +++++------
 tp/Texinfo/Transformations.pm    |  2 +-
 tp/Texinfo/XS/main/DocumentXS.xs |  2 +-
 tp/t/test_utils.pl               |  9 +++---
 tp/texi2any.pl                   |  5 ++--
 8 files changed, 72 insertions(+), 48 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index af40132627..e87a39fab0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2024-04-08  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Document.pm (%XS_overrides, register_document_options),
+       tp/Texinfo/XS/main/DocumentXS.xs (register_document_options),
+       tp/t/test_utils.pl (test), tp/texi2any.pl: rename register_options as
+       register_document_options.  Pass a hash of customization variables to
+       register_document_options, call get_customization_options_hash in the
+       calling code.  Remove _XS_set_document_options.
+
+       * tp/t/test_utils.pl (test): remove a useless setting of
+       document_descriptor in document.
+
+       Update POD documentation.
+
 2024-04-08  Patrice Dumas  <pertusus@free.fr>
 
        * tp/t/test_utils.pl (test): rename $main_configuration* variables as
diff --git a/tp/TODO b/tp/TODO
index 3309b9654b..c087d6bb68 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -50,15 +50,6 @@ Other
 For converter writers,
 'output_init_conf' and 'converter_init_conf'.
 
-It may be relevant to document that if conversion is done with XS, and
-there is a MainConfig, the configuration should be registered in the
-document if it is needed in structuring and indices sorting.
-$main_configuration->register_XS_document_main_configuration($document);
-However, there is, somewhat on purpose, no documentation at all for
-MainConfig given that it is considered as some internal implementation
-detail, not to be used in external code.  So probably would need first to
-document MainConfig.
-
 Document *XS_EXTERNAL_FORMATTING *XS_EXTERNAL_CONVERSION?
 
 
diff --git a/tp/Texinfo/Document.pm b/tp/Texinfo/Document.pm
index 996a88bc8a..3ee3b01228 100644
--- a/tp/Texinfo/Document.pm
+++ b/tp/Texinfo/Document.pm
@@ -51,8 +51,8 @@ our %XS_overrides = (
     => "Texinfo::DocumentXS::rebuild_tree",
   "Texinfo::Document::tree"
     => "Texinfo::DocumentXS::document_tree",
-  "Texinfo::Document::_XS_set_document_options"
-    => "Texinfo::DocumentXS::set_document_options",
+  "Texinfo::Document::register_document_options"
+    => "Texinfo::DocumentXS::register_document_options",
   "Texinfo::Document::get_conf",
     => "Texinfo::DocumentXS::document_get_conf",
   "Texinfo::Document::global_information"
@@ -217,26 +217,13 @@ sub registrar($)
   return $self->{'registrar'};
 }
 
-sub _XS_set_document_options($$)
-{
-  my $self;
-  my $document_options;
-}
-
-# $OPTIONS should be a Texinfo::MainConfig object.
-# For options used in structuring.
-sub register_options($$)
+# Should be for options used in structuring.
+sub register_document_options($$)
 {
   my $self = shift;
   my $options = shift;
 
-  my $document_options = $options->get_customization_options_hash();
-
-  if ($self->document_descriptor()) {
-    _XS_set_document_options($self, $document_options);
-    return;
-  }
-  $self->{'options'} = $document_options;
+  $self->{'options'} = $options;
 }
 
 sub get_conf($$)
@@ -683,13 +670,15 @@ to the same document with @-commands that refer to node, 
anchors or floats.
 =item $nodes_list = nodes_list($document)
 
 Returns an array reference containing the document nodes.  In general set to
-the nodes list returned by L<Texinfo::Structuring 
nodes_tree|Texinfo::Structuring/$nodes_list = nodes_tree($document, 
$customization_information)>,
-by a call to L<register_document_nodes_list|/register_document_nodes_list 
($document, $nodes_list)>.
+the nodes list returned by L<Texinfo::Structuring
+nodes_tree|Texinfo::Structuring/$nodes_list = nodes_tree($document)>, by a call
+to L<register_document_nodes_list|/register_document_nodes_list ($document,
+$nodes_list)>.
 
 =item $sections_list = sections_list($document)
 
-Returns an array reference containing the document sections.  In general set 
to the
-sections list returned by L<Texinfo::Structuring 
sectioning_structure|Texinfo::Structuring/$sections_list = 
sectioning_structure($document, $customization_information)>,
+Returns an array reference containing the document sections.  In general set 
to the sections list returned by
+L<Texinfo::Structuring 
sectioning_structure|Texinfo::Structuring/$sections_list = 
sectioning_structure($document)>,
 by a call to 
L<register_document_sections_list|/register_document_sections_list ($document, 
$sections_list)>.
 
 =back
@@ -852,6 +841,26 @@ in 
L<C<Texinfo::Report::errors>|Texinfo::Report/($error_warnings_list, $error_co
 
 =back
 
+=head2 Getting customization options values registered in document
+
+By default, customization information is registered in a document object
+after parsing the Texinfo code. This is used by structuring and tree
+transformation methods that find customization variables values in the
+document object they get in argument. The customization variable set by
+default may only be a subset of the possible customization variables,
+selected to be useful for structuring and tree transformation codes.
+
+To retrieve Texinfo customization variables you can call C<get_conf>:
+
+=over
+
+=item $value = $document->get_conf($variable_name)
+
+Returns the value of the Texinfo customization variable I<$variable_name>
+(possibly C<undef>), if the variable value was registered in the document,
+or C<undef>.
+
+=back
 
 =head2 Registering document and information in document
 
@@ -886,6 +895,15 @@ Register the I<$sections_list> array reference as 
I<$document> sections
 list.  This method should be called after the processing of document
 structure.
 
+=item register_document_options ($document, $options)
+X<C<register_document_options>>
+
+The I<$options> hash reference holds options for the document. These options
+should be Texinfo customization options.  Usually, the options registered in
+the document are those useful for structuring and tree transformation
+getting place between Texinfo code parsing and conversion to output formats.
+The method should in general be called before the calls to C<get_conf>.
+
 =item set_document_global_info($document, $key, $value)
 X<C<set_document_global_info>>
 
diff --git a/tp/Texinfo/Structuring.pm b/tp/Texinfo/Structuring.pm
index c080f18dc0..12e5f15511 100644
--- a/tp/Texinfo/Structuring.pm
+++ b/tp/Texinfo/Structuring.pm
@@ -2251,7 +2251,8 @@ Texinfo::Structuring - information on Texinfo::Document 
tree
     units_directions units_file_directions);
 
   # $document is a parsed Texinfo::Document document, $tree is the
-  # associated Texinfo document tree. $config is an object implementing
+  # associated Texinfo document tree. When customization variables
+  # information is needed, it is obtained from the $document by calling
   # the get_conf() method.
   my $sections_list = sectioning_structure($document);
   my $identifier_target = $document->labels_information();
@@ -2270,7 +2271,7 @@ Texinfo::Structuring - information on Texinfo::Document 
tree
     $output_units = split_by_section($document);
   }
   split_pages($output_units, $split);
-  units_directions($config, $identifier_target, $output_units);
+  units_directions($document, $identifier_target, $output_units);
   units_file_directions($output_units);
 
 =head1 NOTES
@@ -2312,13 +2313,13 @@ output units by the user.
 
 No method is exported in the default case.
 
-Most methods takes a L<Texinfo::Report> C<$registrar> as argument for
-error reporting.  Most also require Texinfo customization variables
+Most methods use the L<Texinfo::Report> registrar from a parsed document
+for error reporting. Most 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 target elements associated
-to identifiers or refs are obtained from a parsed document, see
+general a parsed document with registered customization, or, sometime,
+a converter (L<Texinfo::Convert::Converter/Getting and setting customization
+variables>).  Other common data needed such as target elements associated to
+identifiers or refs are obtained from a parsed document, see
 L<Texinfo::Document>.
 
 =over
diff --git a/tp/Texinfo/Transformations.pm b/tp/Texinfo/Transformations.pm
index 1e9cc2e7f2..e88f0e8b6a 100644
--- a/tp/Texinfo/Transformations.pm
+++ b/tp/Texinfo/Transformations.pm
@@ -967,7 +967,7 @@ Add menu entries or whole menus for nodes associated with 
sections,
 based on the sectioning tree.  If the optional
 C<$add_section_names_in_entries> argument is set, a menu entry
 name is added using the section name.  This function should be
-called after L<sectioning_structure|Texinfo::Structuring/$sections_list = 
sectioning_structure($document, $customization_information)>.
+called after L<sectioning_structure|Texinfo::Structuring/$sections_list = 
sectioning_structure($document)>.
 
 =item complete_tree_nodes_missing_menu($document, 
$use_section_names_in_entries)
 X<C<complete_tree_nodes_missing_menu>>
diff --git a/tp/Texinfo/XS/main/DocumentXS.xs b/tp/Texinfo/XS/main/DocumentXS.xs
index 7790f5fcda..6f52cdf957 100644
--- a/tp/Texinfo/XS/main/DocumentXS.xs
+++ b/tp/Texinfo/XS/main/DocumentXS.xs
@@ -133,7 +133,7 @@ document_errors (SV *document_in)
 
 
 void
-set_document_options (SV *document_in, SV *sv_options_in)
+register_document_options (SV *document_in, SV *sv_options_in)
     PREINIT:
         DOCUMENT *document = 0;
      CODE:
diff --git a/tp/t/test_utils.pl b/tp/t/test_utils.pl
index ade8fc394a..bdd8d7b78f 100644
--- a/tp/t/test_utils.pl
+++ b/tp/t/test_utils.pl
@@ -982,7 +982,7 @@ sub test($$)
     delete $parser_options->{'init_files'};
   }
 
-  # Setup main configuration options at this point to remove
+  # Setup test configuration options at this point to remove
   # structuring options from parser options.
   my $test_customization_options = {};
   # gather options for structuring.
@@ -1084,9 +1084,10 @@ sub test($$)
     $test_customization->set_conf('novalidate', 1);
   }
 
-  # Now that all the configuration has been set, associate it with the
+  # Now that all the configuration has been set, register with the
   # document
-  $document->register_options($test_customization);
+  my $document_options = $test_customization->get_customization_options_hash();
+  $document->register_document_options($document_options);
 
   if ($tree_transformations{'fill_gaps_in_sectioning'}) {
     Texinfo::Transformations::fill_gaps_in_sectioning($tree);
@@ -1171,8 +1172,6 @@ sub test($$)
   my ($sorted_index_entries, $index_entries_sort_strings);
   my $indices_sorted_sort_strings;
   if ($merged_index_entries) {
-    $document->{'document_descriptor'}
-      = $document->document_descriptor();
     my $use_unicode_collation
       = $document->get_conf('USE_UNICODE_COLLATION');
     my $locale_lang;
diff --git a/tp/texi2any.pl b/tp/texi2any.pl
index 8d34563e06..ac9e492860 100755
--- a/tp/texi2any.pl
+++ b/tp/texi2any.pl
@@ -1557,9 +1557,10 @@ while(@input_files) {
     $main_configuration->set_conf('novalidate', 1);
   }
 
-  # Now that all the configuration has been set, associate it to the
+  # Now that all the configuration has been set, register with the
   # document
-  $document->register_options($main_configuration);
+  my $document_options = $main_configuration->get_customization_options_hash();
+  $document->register_document_options($document_options);
 
   if (defined(get_conf('MACRO_EXPAND')) and $file_number == 0) {
     require Texinfo::Convert::Texinfo;