On Fri, Jul 03, 2026 at 12:04:35AM +0100, Gavin Smith wrote: > On Tue, Jun 23, 2026 at 11:51:20PM +0200, Patrice Dumas wrote: > > It is supposed to be a different purpose. The converter_format_data is > > almost only used to dispatch the different steps of conversion to per > > output format functions. It is about conversion code. There is > > information for converters that are fully implemented in C only. > > This data structure appears to have an association between output format > and Perl module name. I found the purpose of the Perl module name very > unclear. > > It is used by 'find_perl_converter_class_converter_format' in > C/convert/converter.c. This in turn is used by 'get_or_create_sv_converter' > in C/convert/get_converter_perl_info.c and 'converter_defaults' in > perl/XSTexinfo/convert/ConvertHTMLXS.xs. 'get_or_create_sv_converter' itself > is only called from perl/XSTexinfo/convert/ConvertHTMLXS.xs and > perl/XSTexinfo/convert/ConvertHTMLXS.xs and > perl/XSTexinfo/convert/ConvertConverterXS.xs.
Both cases deal with any converter object, the find_perl_converter_class_converter_format finds the C converter converter_format corresponding to the Perl converter, if this converter is implemented in C. One of the interface is in HTML because it is the only converter whose defaults may depend on the customization variables, but it is actually generic. > I can't easily tell whether these are for embedding C in Perl, or embedding > Perl in C (or possibly both). Hopefully it is for the former only, > because in that case there is a hope that we will be able to delete this > code in the future. It is more for calling C from Perl. But it is called if ctexi2any is used for converters implemented in Perl only and may be needed for HTML if Perl code is used, for example if an init file is loaded or LaTeX converter is used for math. Indeed, the Texinfo::XXXXXXX::converter() function is called from C, this function in turn calls the XS HTML converter_defaults and/or the XS _generic_converter_init Texinfo::Convert::Converter interface, which initialize the C converter. When the Info/Plaintext converters are fully implemented in C, this path will not be used from ctexi2any, only from texi2any.pl, which is more intuitive. The reason why the XS interface is used even if the Converter is only implemented in Perl, is that some XS interfaces are used even if the Converter is only implemented in Perl, at least customization options management (to avoid having to synchronize C and Perl) and indices sorting (more for speed). > As both are possibilities at present for texi2any, > it's hard to tell which one is relevant for particular parts of the source > code (unless it's stated in source code comments). There are different cases, and different code paths which can go from and to Perl. This is clearly complex and it is hard at time to remember which path is used without adding debugging output. As I tried to describe above, the complexity is reduced for full C implementations, but for HTML and full Perl implementations, there is this back and forth that it not intuitive. > When you see a Perl module name in a data structure like the one above, > you assume it would be for loading the (Perl) module, but instead it > seems to be used, as far as I can tell (with the time I've spent trying > to make sense of it), it's used when a converter module object on the > Perl side of the code is implemented with C code, and is used to lookup > which (C) code to use. Indeed. But it is not so unexpected, as we are calling C from Perl in that case. In my opinion, the interface in C is not so complex. Indeed, to do a new converter fully in C a new line should be added to the converter_format_data in converter.c for the dispatch of the functions and the functions implemented, but I think that it is not an unusual nor complex as interface. I wil add some information somewhere to document that, in fact. Is there an action to be taken? More comments, trying to simplify the interfaces? -- Pat
