Re: Request for feedback on texi2any customization file

[Jonas Hahnfeld]

On Mon, 2023-09-04 at 13:29 +0200, Patrice Dumas wrote:
> On Tue, Aug 29, 2023 at 10:58:21AM +0200, Jonas Hahnfeld wrote:
> 
> > 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.

Understood.

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

Does this mean texi2any will move away from being a pure Perl program?

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

I don't think I like that idea: For CI testing and also for producing
the official documentation, LilyPond uses a Docker image based on
Ubuntu 20.04 with Texinfo 6.7. Even if we moved to Ubuntu 22.04, we'd
still only get version 6.8. We could of course build our own texi2any
into the container image, but I don't think requiring a yet unreleased
version is a good idea: LilyPond is already hard to build right now.
The switch away from texi2html is supposed to make this easier, not
more difficult by requiring the very latest texi2any which doesn't even
build with the very latest gettext 0.22...

So no, I think the minimum required version has to stay Texinfo 6.7 for
now, with the potential of bumping to Texinfo 6.8 if we find something
that absolutely cannot be done. But on the other hand, everything is
free game for released versions, we can use any undocumented and
private API as long as we have a better alternative available in the
future because those old versions are never going to change.


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

Ok, not replacing external_node_href makes sense then (our texi2html
setup just called the default implementation after tweaking some
arguments).

As I write above, label_target_name is already called for external
references (via _normalized_label_id_file). So all we would need is
something like node_file_name for external nodes (or just use the same
function) and a hook to tweak the manual directory, with the default
returning $manual_base.'_'.$converter->{'output_format'}, right?


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

Ok, so then let's explore how to use it once that iterated API is in.
The current way of having an array with strings works fine for now.


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

Thanks for taking a look!
I think you should be able to login with a GitHub account (if you have
one) or via one of the other service providers. A credit card number is
only needed to use continuous integration and I wasn't even aware that
GitLab is asking for phone numbers these days...

Jonas

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