On Tue, Aug 29, 2023 at 10:58:21AM +0200, Jonas Hahnfeld via Bug reports for the GNU Texinfo documentation system wrote: > Dear Texinfo / texi2any developers, > > if some of the experts have time, I would highly appreciate some > feedback on a texi2any customization file for LilyPond: > https://gitlab.com/lilypond/lilypond/-/merge_requests/2089 > As a bit of context, LilyPond uses texi2html for its HTML documentation > since quite some time because it had superior customization > possibilities when the switch was made from makeinfo to texi2html. With > texi2html being legacy now, it would of course be nice to transition > "back" to texi2any.
That's a very good news. > A couple of specific questions to start with: > * For lilypond_label_target_name, we need to deal with three different > function signatures if we want to support a range of Texinfo versions: > four arguments in current master / post-7.0; three arguments in Texinfo > 7.0; two arguments before Texinfo 7.0. Can we expect this signature > (and others) to be stable after the release of Texinfo 7.1? (originally > I thought Texinfo 7.0 already marked a stable API, but here we are...) The API is not stable, and will not be for some time for two reasons. The first one is that it is very new and has not been really tested. The priority is still a complete and consistent API for now rather than a stable one. LilyPond is probably the first (and maybe only one...) active project to use complex customization. I understand how it is a pain for you not to have a stable API, but it is also an opportunity, as the API can still change to accomodate for your need if they are generally relevant. The other reason is that there is a translation to C of perl code going on with, hopefully, the possibility to have both perl and C implementations of the HTML converter. But it leads to quite a bit of changes in the tree and in the perl API, in particular to have a similar API in C, and also because it reveals flaws of the API. It may not be so easy for you, but I think that you should force users rebuilding the documentation to use the latest official Texinfo release only. 7.1 will be the first to have a complete API, so it seems to me that it makes sense to force users to have that. Given the rapid pace of API breakage there are still many breakage of the API to be expected for a few years, though, which may not be so fine for you. > * Is it possible to format the external reference href without dealing > with the entire reference in lilypond_format_ref? It seems possible to > control the manual's directory name using htmlxrefs, but there seems to > be no hook to control the node file names, ie lower-case them > (label_target_name seems to be called though). texi2html had a hook to > customize the external_href and I also see left-overs in older versions > of texi2any. Would you accept adding such hook again? label_target_name is for internal references only. There are indeed two possibilities to customize external references like you propose, either omething similar to label_target_name, or a hook replacing _external_node_href. I think that something similar with label_target_name would be better, as we try to have hooks that use only non internal functions, such that the users can base their functions on existing functions, and it seems to be complicated to to that for _external_node_href. The difficulty to use something similar to label_target_name is that internal references are setup very early, while external reference are formatted during the document formatting, but it could be possible to change that. > * What would be the best way to translate some of the extra strings in > our customization file? Using libintl-perl from a process with LANG=C > and forcing it to honor documentlanguage seems a pain, at least from my > experiments and looking at gdt() and _switch_messages_locale() in > tp/Texinfo/Translations.pm... Using libintl-perl for that is probably impractical. I think that the best would be to use the new API for that, which will be in the next release. But beware that it has already changed importantly in the branch I use for the post-release code, so be preprared for unstable API for strings customization. This is actually a case where your feedback would be much appreciated. > But please, if you see anything in the customization that should not be > done that way and / or is likely to break in the future, please let me > know or directly comment on the merge request! I could not find a way to register without giving a phone number or credit card number, so I will send you mails directly (you can then add comments on my behalf if you want to). -- Pat
