branch master updated: * tp/Texinfo/Convert/IXINSXML.pm (converter_initialize): reset 'converted_format' to be 'texinfosxml', as when called from the main program it is (rightly) set to 'ixinsxml'.

[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 d6a1350456 * tp/Texinfo/Convert/IXINSXML.pm (converter_initialize): 
reset 'converted_format' to be 'texinfosxml', as when called from the main 
program it is (rightly) set to 'ixinsxml'.
d6a1350456 is described below

commit d6a1350456c75316eaa8deb894af21520130c65f
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Sep 12 11:54:22 2022 +0200

    * tp/Texinfo/Convert/IXINSXML.pm (converter_initialize):
    reset 'converted_format' to be 'texinfosxml', as when called
    from the main program it is (rightly) set to 'ixinsxml'.
    
    * tp/Texinfo/Convert/IXINSXML.pm, tp/Texinfo/Convert/IXIN.pm,
    tp/texi2any.pl: add/update comments.
---
 ChangeLog                      |  9 ++++++
 tp/Texinfo/Convert/IXIN.pm     | 63 ++++++++++++++++++++++++++++++++++++------
 tp/Texinfo/Convert/IXINSXML.pm | 48 +++++++++++++++++++++++++++-----
 tp/texi2any.pl                 |  8 ++++--
 4 files changed, 110 insertions(+), 18 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 21ce3ee599..cc08944fc8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2022-09-12  Patrice Dumas  <pertusus@free.fr>
+
+       * tp/Texinfo/Convert/IXINSXML.pm (converter_initialize):
+       reset 'converted_format' to be 'texinfosxml', as when called
+       from the main program it is (rightly) set to 'ixinsxml'.
+
+       * tp/Texinfo/Convert/IXINSXML.pm, tp/Texinfo/Convert/IXIN.pm,
+       tp/texi2any.pl: add/update comments.
+
 2022-09-12  Patrice Dumas  <pertusus@free.fr>
 
        * tp/Texinfo/Convert/TexinfoSXML.pm (_sxml_attributes): rename
diff --git a/tp/Texinfo/Convert/IXIN.pm b/tp/Texinfo/Convert/IXIN.pm
index d5999928f0..8edbc6b0cc 100644
--- a/tp/Texinfo/Convert/IXIN.pm
+++ b/tp/Texinfo/Convert/IXIN.pm
@@ -1,6 +1,6 @@
-# IXIN.pm: output tree as IXIN.
+# IXIN.pm: output IXIN format.
 #
-# Copyright 2013-2020 Free Software Foundation, Inc.
+# Copyright 2013-2022 Free Software Foundation, Inc.
 # 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -17,11 +17,48 @@
 # 
 # Original author: Patrice Dumas <pertusus@free.fr>
 #
-# This module implements abstract functions that output the IXIN format
-# using lower level formatting funtions, here adapted to lisp like
-# output.  For other output, the output specific functions should be
-# redefined.  This module is not enough to output IXIN format, a module
-# inheriting both from a converter module and this module is required.
+#
+# The IXIN format "indexed Texinfo", contains both a representation of
+# a Texinfo manual contents, and additional information, using a specific
+# markup vocabulary to have a direct access to nodes, sections, labels,
+# indices, title...  It is designed to allow to render flexibly Texinfo.
+# The IXIN project is at https://savannah.nongnu.org/projects/ixin/.
+#
+#
+# This module alone is not sufficient to output the IXIN format, as it
+# calls convert_tree() but does not implement the conversion of Texinfo
+# (of the Texinfo tree) nor inherit from a module that does so.  A module
+# inheriting both from a converter module, for convert_tree(), and this module
+# should be used.  A functional implementation of IXIN is available as the
+# Texinfo::Convert::IXINSXML module which uses Texinfo::Convert::TexinfoSXML
+# for the Texinfo tree conversion.  Using a Texinfo tree converter that does
+# not lose information for Texinfo tree conversion in IXIN is in line with the
+# IXIN philosophy, so conversion modules like Texinfo::Convert::TexinfoXML or
+# Texinfo::Convert::TexinfoSXML are the best candidates.
+#
+# This module implements output of the IXIN format using lower level formatting
+# functions for the additional information markup, adapted to lisp-like
+# output.  To output the IXIN elements with another format, for example XML,
+# the abstract output specific functions ixin_* should be redefined in
+# another module a functional implementation would inherit from.  (This
+# approach is the same as the one used for Texinfo::Convert::TexinfoXML
+# and Texinfo::Convert::TexinfoSXML).
+#
+# This setup allows to cleanly separate the modules used for IXIN additional
+# information formatting and the modules used for Texinfo tree conversion.
+#
+#
+# This module is still work in progress, as is the IXIN project as a whole.
+# The IXIN project is inactive since 2015, this code is not actively
+# maintained either.  It is kept, in case the IXIN project resumes, and also
+# as an example of code adding additional information mixed with Texinfo
+# tree conversion.
+#
+# There are pending issues, in particular related to blobs, as can be seen
+# in the thread of
+#  https://lists.gnu.org/archive/html/help-texinfo/2013-01/msg00005.html
+# and
+#  https://lists.gnu.org/archive/html/help-texinfo/2015-02/msg00004.html
 
 package Texinfo::Convert::IXIN;
 
@@ -57,7 +94,7 @@ foreach my $command ('pagesizes', 'everyheading', 
'everyfooting',
 }
 
 # Here are all the commands that are misc_commands with type matching \d
-# and are also global_unique_commands/global_multiple_commands in Parser.pm
+# and are also global_unique_commands/global_multiple_commands
 # but are not setting commands.
 my %global_misc_not_setting_commands = (
   'printindex' => 1,
@@ -82,6 +119,8 @@ my %extension_mime_mapping = (
 sub ixin_header($)
 {
   my $self = shift;
+  # FIXME _ixin_version() should be public to be usable in other implementation
+  # of output specific functions.
   my $header = 'ixin '.$self->_ixin_version().';';
   if ($self->get_conf('OUTPUT_ENCODING_NAME')) {
     $header .= ' -*- coding: '. $self->get_conf('OUTPUT_ENCODING_NAME') 
.'-*-;';
@@ -183,6 +222,11 @@ sub ixin_none_element($$)
 # end output specific subs
 
 # FIXME this is rather non specific. Move to Converter?
+# FIXME need to be changed for {'structure'}->{'associated_unit'}.
+# There is a version HTML specific, _html_get_tree_root_element
+# which is up to date and handles better content in @insertcopying
+# or @titlepage, but has specific HTML code related to separate
+# elements, it could be used to update if needed.
 sub _get_element($$);
 sub _get_element($$)
 {
@@ -322,7 +366,8 @@ sub output_ixin($$)
   if ($self->{'parser_info'}->{'dircategory_direntry'}) {
     my $current_category;
     foreach my $dircategory_direntry 
(@{$self->{'parser_info'}->{'dircategory_direntry'}}) {
-      if ($dircategory_direntry->{'cmdname'} and 
$dircategory_direntry->{'cmdname'} eq 'dircategory') {
+      if ($dircategory_direntry->{'cmdname'}
+          and $dircategory_direntry->{'cmdname'} eq 'dircategory') {
         if ($current_category) {
           $result .= $self->ixin_close_element('category');
         }
diff --git a/tp/Texinfo/Convert/IXINSXML.pm b/tp/Texinfo/Convert/IXINSXML.pm
index 660d24aaaf..dd3f096303 100644
--- a/tp/Texinfo/Convert/IXINSXML.pm
+++ b/tp/Texinfo/Convert/IXINSXML.pm
@@ -1,21 +1,30 @@
-# IXIN.pm: output tree as IXIN with SXML converter.
+# IXINSXML.pm: output IXIN with Texinfo tree content converted to SXML.
+#
+# Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2022 Free Software
+# Foundation, Inc.
 #
-# Copyright 2013, 2014, 2015, 2016, 2017, 2018 Free Software Foundation, Inc.
-# 
 # This program 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.
-# 
+#
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
-# 
+#
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-# 
+#
 # Original author: Patrice Dumas <pertusus@free.fr>
+#
+#
+# This modules combines the Texinfo::Convert::IXIN module which
+# outputs the IXIN format and the Texinfo::Convert::TexinfoSXML
+# Texinfo tree converter, which converts Texinfo, and is called
+# from Texinfo::Convert::IXIN, to obtain a functional IXIN format
+# conversion implementation that can be called as a Texinfo converter.
+# See comments at the beginning of IXIN.pm for more information.
 
 package Texinfo::Convert::IXINSXML;
 
@@ -40,7 +49,12 @@ my %defaults = (
   'OUTPUT_ENCODING_NAME' => 'utf-8',
   'OUTFILE'              => undef,
   'SUBDIR'               => undef,
-  'converted_format'     => 'ixinsxml',
+  # next two are replaced by the main program value if called from
+  # the main program.  'output_format' is also 'ixinsxml' when set by
+  # the main program, but 'converted_format' is set to 'ixinsxml'.
+  # More on that subject below.
+  'converted_format'     => 'texinfosxml',
+  'output_format'        => 'ixinsxml',
   'SPLIT'                => 0,
   'documentlanguage'     => 'en',
   'USE_NODES'            => 1,
@@ -51,6 +65,26 @@ sub converter_defaults($$)
   return %defaults;
 }
 
+# In the main program, the 'converted_format' needs to be 'ixinsxml'
+# to find the right module used for conversion (this module).  However in
+# the Texinfo::Convert::IXIN output_ixin() function, and maybe in
+# Texinfo::Convert::TexinfoSXML convert_tree(), called from output_ixin(),
+# it may be better to have 'converted_format' set to the format converted
+# from the Texinfo tree, which is texinfosxml.  So far it is not needed,
+# inheriting format specific functions is used to select the output format,
+# but it could theoretically be needed for a flexible conversion
+# (since the IXIN project is inactive, the corresponding code is not updated
+# acively either, so it is unlikely to change, though).
+sub converter_initialize($) { my $self = shift;
+
+  $self->{'converted_format'} = $defaults{'converted_format'};
+
+  # need to call parent module converter_initialize, to initialize
+  # the converter state.  This method is actually implemented in
+  # the Texinfo::Convert::TexinfoSXML parent class.
+  $self->SUPER::converter_initialize(@_);
+}
+
 sub output($)
 {
   my $self = shift;
diff --git a/tp/texi2any.pl b/tp/texi2any.pl
index 2361a47af6..83706a73f2 100755
--- a/tp/texi2any.pl
+++ b/tp/texi2any.pl
@@ -586,9 +586,13 @@ my %formats_table = (
              'module' => 'Texinfo::Convert::TexinfoSXML',
              'floats' => 1,
            },
-  'ixinsxml' => {
+  'ixinsxml' => { # note that the Texinfo tree is converted to
+                  # 'texinfosxml', but the conversion as a whole
+                  # is 'ixinsxml', as Texinfo tree conversion is done
+                  # from within Texinfo::Convert::IXINSXML
              'nodes_tree' => 1,
-             'module' => 'Texinfo::Convert::IXINSXML'
+             'module' => 'Texinfo::Convert::IXINSXML',
+             'floats' => 1,
            },
   'docbook' => {
              'move_index_entries_after_items' => 1,