> Date: Sun, 10 Aug 2025 21:21:14 +0200 > From: Patrice Dumas <pertu...@free.fr> > > On Sun, Aug 10, 2025 at 07:43:00PM +0100, Gavin Smith wrote: > > I see you (Patrice) implemented a C version of a change I'd made to a Perl > > function: > > > > How was I supposed to know that the C function existed? > > You can grep the name in the C code, except for a few functions, the > names are the same or very similar. > > > The only explanation I have is that these C functions are used directly > > by C versions of the conversion code, but they are not available from > > Perl code as XSUBs. > > Exactly. There are lots of C code that do the same as Perl code, but is > not directly called as XS. Actually, the less XS interfaces there are > and the more C only (and Perl only) code there are, the simpler, as > having interfaces always require doing additional error prone codes to > make sure that the two underlying data are in sync. > > > Is it correct that these functions are not available as XSUBs? If so, > > what's the difference between the Perl functions that have XSUB versions > > and those that do not? And how is somebody working on the Perl source code > > supposed to know when there is a C version they should be updating too? > > For parsing, structure, transformations, conversion back to Texinfo, > conversion to raw Text and to identifiers, conversion to HTML and main > program (texi2any.pl), there is a complete coverage in C, so every > function in the Perl codes is supposed to have a at least one > corresponding function (or, sometime, when there is not a perfect > mapping between the functions in the two langauges, equivalent code) in > C. This includes Texinfo::Indices, Texinfo::ManipulateTree, > Texinfo::Document, Texinfo::Translations and Texinfo::OutputUnits.pm, > and most of Texinfo::Common and Texinfo::Convert::Unicode functions used > in the previously mentionned codes. There can be, in addition, some XS > interface code, and some code to call Perl from C. For conversion > helper functions, such as functions in Texinfo::Convert::Converter, > probably some functions in Texinfo::Common and some functions in > Texinfo::Convert::Utils, but probably not all (I haven't checked in > details). > > For the main program, the corresponding code is in texi2any.c and > convert/texinfo.c. For the other codes, sometime the organization of > the code is similar to Perl, but not always, because of the different > contraints for both codebases. For instance, delayed loading of Perl > modules for Transformations on the Perl side, and Gnulib C/Perl C > constraints of C + no undefined.
Perhaps we should have an internal-design README which would include all this important information (and then some)?
