Re: Is a texi2any upgrade still wanted, and what would it take? (WAS: Re: New Lilypond logo?)

[Jean Abou Samra]

Le 24/10/2022 à 18:09, Karlin High a écrit :
> I understand there is a technical-debt issue in this area, though. 
> Related to an old version of Texinfo, and the older texi2html vs the 
> newer texi2any. Which is to generate the website concurrently with the 
> rest of the documentation.


Yes.


> 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.

- 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

- 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.

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

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

Personally, my dream would be to switch to a different documentation
tool entirely, like Sphinx, which supports HTML, LaTeX and Texinfo
output, with extensive HTML customization possibilities, and would
not need so much build system fuss (lilypond-book etc.), and supports
internationalization via po files on top of that. But that is going to
be controversial and the amount of work is magnitudes larger :)

Best,
Jean