Re: make dist after make maintainer-clean no XS for pod2texi

On Fri, Aug 14, 2026 at 12:45:49AM +0100, Gavin Smith wrote:
> The essence of the issue is that the XS modules are not built as a dependency
> of any program.  They are listed as built targets to be built with "make all"
> in tta/perl/XSTexinfo/Makefile.am, but not for "make dist".  "make dist" targets
> depend on programs themselves existing, such as rules under man/Makefile.am
> to get man pages with help2man by running the programs.  This works for
> texi2any for printing the usage message, but not for actually using the
> program to convert an input file.

I didn't realize that.  This seems to me that it is not robust, but
there is the possibility to use ctexi2any instead in the long term
and/or if --enable-using-c-texi2any is set.

> I reversed the commit you listed, and then ran "make maintainer-clean",
> "./configure" and "make dist".  Under "tta/perl" I ran "make texi2any" - this
> does very little work, successfully.  "TEXINFO_DEV_SOURCE=1 texi2any --help"
> then outputs the usage message (so there would no problem with running texi2any
> with help2man), but trying to run it on an input file fails:
> 
>   $ TEXINFO_DEV_SOURCE=1 ../tta/perl/texi2any ../doc/texinfo.texi
>   extension ManipulateTreeXS enabled required for Texinfo::ManipulateTree
>   BEGIN failed--compilation aborted at ../tta/perl//../perl/Texinfo/ManipulateTree.pm line 87.
>   Compilation failed in require at ../tta/perl//../perl/Texinfo/Document.pm line 48.
>   BEGIN failed--compilation aborted at ../tta/perl//../perl/Texinfo/Document.pm line 48.
>   Compilation failed in require at ../tta/perl//../perl/Texinfo/Parser.pm line 28.
>   BEGIN failed--compilation aborted at ../tta/perl//../perl/Texinfo/Parser.pm line 28.
>   Compilation failed in require at ../tta/perl/texi2any line 1535.

Ok.  Not very satisfying, but it seems to me that it is acceptable.

> I don't know a lot about how pod2texi works but from what I can tell it
> loads Perl modules that are part of texi2any.  However, this is not for
> conversion from Texinfo, but actually the other way around, converting
> to Texinfo from another documentation format (POD).

The Texinfo modules are needed to normalize node/anchor names, and to
apply transformations that protect what needs to be protected in node
names in @node or @*ref.

> I couldn't think of a simple way to get these modules built purely with
> "make dist".  I came up with the following:
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 5c124a6bc9..31d2a3dd09 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -44,7 +44,8 @@ if BUILD_PERL_API_TEXI
>  # Since Pod::Simple::Texinfo is not in CPAN, the @url first argument
>  # is post-processed by a sed one liner to point to the GNU web site. 
>  $(srcdir)/pod2texi.texi: $(pod2texi_pl)
> -       $(MAKEINFO_ENVIRONMENT) TEXINFO_XS=omit $(PERL) -I $(top_srcdir)/Pod-Simple-Texinfo/lib/ $(top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl --base-level=subsubsection --no-section-nodes --headings-as-sections --subdir=$(srcdir) $(pod2texi_pl) > /dev/null
> +       cd $(top_builddir)/tta && $(MAKE) $(AM_MAKEFLAGS)
> +       $(MAKEINFO_ENVIRONMENT) $(PERL) -I $(top_srcdir)/Pod-Simple-Texinfo/lib/ $(top_srcdir)/Pod-Simple-Texinfo/pod2texi.pl --base-level=subsubsection --no-section-nodes --headings-as-sections --subdir=$(srcdir) $(pod2texi_pl) > /dev/null
>         mv $(srcdir)/pod2texi.texi $(srcdir)/pod2texi_tmp.texi
>         sed 's;https://metacpan.org/pod/Pod::Simple::Texinfo;https://www.gnu.org/software/texinfo/manual/Pod/Simple/Texinfo.html;' $(srcdir)/pod2texi_tmp.texi > $(srcdir)/pod2texi.texi
>         rm -f $(srcdir)/pod2texi_tmp.texi
> 
> Basically, hard code building in the tta/ directory in the rule (I tried
> just tta/perl/XSTexinfo but this didn't work due to dependencies in e.g.
> tta/gnulib).  "make dist" succeeded with this - but it's not necessarily
> very easy to understand or maintainable going forward.

It is better than what I did.  We do something similar for swig modules
build.

> Nevertheless, I slightly prefer this solution to setting TEXINFO_XS=omit,
> as we'd like to be building, running and testing the C code where possible.

Agreed.

> The "Gordian knot" solution: remove pod2texi from Texinfo.  I don't think
> anybody uses it and it doesn't need to be part of Texinfo.

I use it to generate the tta_api/texi2any_internals.pdf file that I
personnally use when working on texi2any from time to time, when I have
forgotten about how some module worked.

> The way
> of pod2texi integrates with the internals of texi2any seems to force
> texi2any to remain as a Perl program.

Not really, but it requires keeping Texinfo modules.  It is not good,
since these modules are supposed to be internal.

>  In theory, there might also be
> ways to implement a pod2texi program that don't rely on using parts
> of texi2any.

A possibility that could be a solution for the long term would be to use
the swig interface instead of the internal modules and make pod2texi a
separate project.  That would probably solve the issue in a satisfactory
way.  The tta_api/texi2any_internals.pdf file would only be generated if 
pod2texi is present.

-- 
Pat