Re: Is a texi2any upgrade still wanted, and what would it take?

[Jonas Hahnfeld]

On Mon, 2022-10-24 at 18:43 +0200, Jean Abou Samra wrote:
> Le 24/10/2022 à 18:09, Karlin High a écrit :
> 
> > Near as I can tell, this reference best captures the issue:
> > 
> > <https://gitlab.com/lilypond/lilypond/-/issues/1557>
> > 
> > I have had my eye on this area as a potential future personal project, 
> > a long-term seasons-of-code level effort.
> > 
> > However, my levels of Linux development know-how are quite varied. 
> > What foundational knowledge would be needed for that effort? Reading 
> > the texinfo 1.82 manual, as well as a newer version?
> 
> The work amounts to:
> 
> - Reading and understanding the contents of our
>    Documentation/lilypond-texi2html.init texi2html configuration file
>    (over a thousand lines of Perl code), and porting that to texi2any.

I think it may be better to rewrite the needed customizations more or
less from scratch. From a few preliminary tests some time ago, many
things will work very differently with texi2any; some customizations
won't be necessary anymore (because there are options to get the same
effect) and some new ones will be needed. Blindly porting the current
code over to texi2any will make it very tiring to clean things up
afterwards, as opposed to starting from a clean slate (it's of course
possible to look for "inspiration" in the old code).

Let me also make a comment now (hopefully early enough) so I don't
receive complaints of being too pedantic during MR review: In my
opinion, the above should be done incrementally over multiple commits
instead of just dumping the new setup. This will ensure that somebody
ten years from now can still understand why a customization is there
(assuming the individual commit messages are written well enough).

Maybe a structure similar to the following:
1. Completely delete current customizations in lilypond-texi2html.init
2. Switch over to texi2any --html
3. Introduce most basic customizations for texi2any (probably related
to naming the individual HTML files)
4. Gradually add other customizations (CSS, navigation menu handling)
5. Add customizations related to formatting improvements (if needed)

It's also likely that there will be "unrelated" things discovered on
the way, that can already be done "today" in the current setup with
texi2html. Needless to say that I would highly recommend splitting them
into separate merge requests...

> - Along the way, identifying what features are missing in texi2any,
>    and asking upstream to implement them; the maintainer expressed
>    willingness to do that just today:
> 
> https://lists.gnu.org/archive/html/help-texinfo/2022-10/msg00006.html

As a comment on that, you may want to limit the number of texinfo
versions to test. Right now, we require texinfo 6.1 while our CI images
already have 6.5. If we switch to Ubuntu 20.04 (which I think we should
do after 2.24.0 and 2.25.0 are out), we may bump the requirement to 6.7
which only leaves three versions to test (assuming 6.9 is released by
that time).

> - Amending the build system to search and invoke texi2any instead of 
> texi2html
>    (in configure.ac, Documentation/GNUmakefile, etc.), and building 
> updated Docker
>    images for the GitLab CI system.

(the Docker images should be fine, famous last words; we can remove
texi2html in a secondary step)

> - Possibly revamping (?) the way cross-references work
>    (scripts/build/extract_texi_filenames, etc.) to cater for the new tool.

... or trying to get away completely without the xref-maps? I think it
would be possible (greatly simplifying the build setup already today),
but there are some disadvantages for the translators...

> Don't be mistaken: this is a large undertaking.

Oh yes. I don't want to scare anybody away willing to work on this, but
my informed guesstimate would be no less than 2-3 months of "full"
free-time work. So to avoid duplicate work, it may be good to announce
if somebody is working on it beyond just toying around 😉


Jonas

signature.asc
Description: This is a digitally signed message part