Re: Request for feedback on texi2any customization file

[Patrice Dumas]

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