texinfo-commits
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[no subject]


From: Patrice Dumas
Date: Thu, 25 Jan 2024 17:14:23 -0500 (EST)

branch: master
commit 5e91dcbf227970707f29d0d504e52b53283309c4
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Thu Jan 25 20:59:15 2024 +0100

    * tp/Texinfo/Document.pm: update POD documentation.
---
 ChangeLog              |   4 ++
 tp/TODO                |  28 ++++++++------
 tp/Texinfo/Document.pm | 103 +++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 117 insertions(+), 18 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 90a7043367..620ad70da6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2024-01-25  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Document.pm: update POD documentation.
+
 2024-01-25  Patrice Dumas  <pertusus@free.fr>
 
        * Pod-Simple-Texinfo/pod2texi.pl (_parsed_manual_tree),
diff --git a/tp/TODO b/tp/TODO
index 192bab8066..f2197e999a 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -10,20 +10,11 @@ This is the todo list for texi2any
 Before next release
 ===================
 
-Keep/document *XS_EXTERNAL_FORMATTING *XS_EXTERNAL_CONVERSION?
-
-Document that Texinfo::Document::rebuild_document or
-Texinfo::Document::rebuild_tree should be called after tree modifications
-if the parser is XS but converters are perl.
-Also if conversion 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);
-
 
 Bugs
 ====
 
+
 HTML API
 ========
 
@@ -59,6 +50,17 @@ 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
+docuent MainConfig.
+
+Document *XS_EXTERNAL_FORMATTING *XS_EXTERNAL_CONVERSION?
+
 
 Delayed bugs
 ============
@@ -637,9 +639,13 @@ Solaris 11
 cpan> o conf urllist push http://backpan.perl.org/
 cpan RJBS/Test-Deep-1.127.tar.gz
 
-Also possible to install Texinfo dependencies with CSW, like
+Also possible to install Texinfo dependencies with openCSW, like
 pkgutil -y -i CSWhelp2man CSWpm-data-compare CSWpm-test-deep
 
+The system perl may not be suitable to build XS modules, and the
+system gawk may be too old, openCSW may be needed.  For example: 
+./configure PERL=/opt/csw/bin/perl GAWK=/opt/csw/bin/gawk
+
 
 Misc notes
 ==========
diff --git a/tp/Texinfo/Document.pm b/tp/Texinfo/Document.pm
index adf1b3ae03..da1338efc2 100644
--- a/tp/Texinfo/Document.pm
+++ b/tp/Texinfo/Document.pm
@@ -125,7 +125,6 @@ sub _XS_set_document_global_info($$$)
 {
 }
 
-# TODO document
 sub set_document_global_info($$$)
 {
   my $document = shift;
@@ -307,7 +306,7 @@ sub remove_document($)
   my $document = shift;
 }
 
-# this method does nothing, but the XS override rebuilds the perl
+# this method does nothing, but the XS override rebuilds the Perl
 # document based on XS data.
 sub rebuild_document($;$)
 {
@@ -317,7 +316,7 @@ sub rebuild_document($;$)
   return $document;
 }
 
-# this method does nothing, but the XS override rebuilds the perl
+# this method does nothing, but the XS override rebuilds the Perl
 # tree based on XS data.
 sub rebuild_tree($;$)
 {
@@ -372,6 +371,8 @@ a Texinfo parser call, there is no need to setup the 
document.
 
 =head1 METHODS
 
+=head2 Getting document information
+
 The main purpose of Texinfo::Document methods is to retrieve information
 on a Texinfo document.
 
@@ -572,6 +573,8 @@ If C<name> is not set, it is set to the index name.
 
 =back
 
+=head2 Registering document and information in document
+
 The setup of a document is described next, it should only be used in
 parsers codes.
 
@@ -585,8 +588,7 @@ information returned by the other methods.
 
 =back
 
-Further information can be registered in the document.  Those
-methods should be called during the processing of document structure.
+Further information can be registered in the document.
 
 =over
 
@@ -594,13 +596,100 @@ methods should be called during the processing of 
document structure.
 X<C<register_document_nodes_list>>
 
 Register the I<$nodes_list> array reference as I<$document> nodes
-list.
+list.  This method should be called after the processing of document
+structure.
 
 =item register_document_sections_list ($document, $sections_list)
 X<C<register_document_sections_list>>
 
 Register the I<$sections_list> array reference as I<$document> sections
-list.
+list.  This method should be called after the processing of document
+structure.
+
+=item set_document_global_info($document, $key, $value)
+X<C<set_document_global_info>>
+
+Add I<$value> I<$key> information to I<$document>.  This method should not be
+generally useful, as document global information is already set by the
+Texinfo parser.  The information set should be available through
+the next calls to L<global_information|/$info = global_information($document)>.
+The method should in general be called before the calls to
+C<global_information>.
+
+=back
+
+=head2 Methods for Perl and C code interactions
+
+The parsing of Texinfo code, structuring and transformations of the tree
+called through Texinfo Perl modules may be done by pure Perl modules or
+by C code called through XS interfaces.  In general, it makes no difference
+whether pure Perl or C code is used. In some cases, however, specific functions
+need to be called to pass information from C to Perl or perform actions related
+to C data.
+
+The methods can always be called on pure Perl modules even if they do nothing.
+Therefore it is, in general, better to call them assuming that modules
+setting up C data were called, even when it is not the case.
+
+First, C<document_descriptor> can be called to get the document identifier
+document used by C code to retrieve the document data in C.  In general
+this identifier is directly and transparently taken from the document, but may
+need to be set on other objects in rare cases.
+
+=over
+
+=item $document_descriptor = $document->document_descriptor()
+X<C<document_descriptor>>
+
+Returns the document descriptor if the document is available as C data,
+0 or C<undef> if not.
+
+=back
+
+When the document and tree are accessed in Perl but are modified by
+C code, for instance called through L<Texinfo::Common>,
+L<Texinfo::Structuring> or L<Texinfo::Transformations> methods, the
+Perl structures need to be rebuilt from the C data with C<rebuild_document>
+or C<rebuild_tree>:
+
+=over
+
+=item $rebuilt_document = rebuild_document($document, $no_store)
+
+=item $rebuilt_document = rebuild_tree($tree, $no_store)
+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.
+
+If the optional I<$no_store> argument is set, remove the C data.
+
+=back
+
+Some methods allow to release the memory or remove error messages held
+by C data associated to a Texinfo parsed document:
+
+=over
+
+=item clear_document_errors($document)
+X<C<clear_document_errors>>
+
+Remove the document errors and warnings held in C data.
+
+The method can be called on pure Perl modules but does nothing as the errors
+and warnings are already in a L<Texinfo::Report> object and not associated to a
+document.
+
+B<the document errors may be in C<< $document->{'errors'} >>, but this is not
+documented anywhere.>
+
+=item remove_document($document)
+X<C<remove_document>>
+
+Remove the C data corresponding to I<$document>.
 
 =back
 



reply via email to

[Prev in Thread] Current Thread [Next in Thread]