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