Il giorno mer 4 gen 2023 alle 14:39:47 +0100, Jonas Hahnfeld
<hah...@hahnjo.de> ha scritto:
The other two formats we care about for the translated documentation
are PDF and HTML. Of the two, HTML is arguably the more complex one in
terms of infrastructure for cross-references: For PDF, we just link to
the (translated) heading in the right PDF file, and that's it. For the
split HTML build, however, we want the @node's to end up in a .html
file based on their English equivalent so that automatic language
works
if you open a page without the .html extension (question 0: do we want
to keep this ability?).
It's a good question. Some find it annoying, e.g. if you have a
localised browser but you want to read the english pages (because
translation is out-of-date or for other reasons). There is a
workaround: setting english as preferred language, but this affects any
website you visit.
I would prefer if setting a language was an explicit choice of the user.
So an italian page should link to the italian pages, if available,
otherwise fall back to english.
See also:
https://gitlab.com/lilypond/lilypond/-/issues/2273
> On the other hand, we obviously want the link
text to be translated, which is why we have translated @node's and
@section's but the English version in the @translationof annotations.
Based on the latter, we generate .xref-map files to have a mapping for
cross references and then adjust file names and links to them in our
texi2html customization file.
Now, this works in our current setup, but it seems to me that there is
an easier way to achieve this with "native" Texinfo tools: Instead of
@node Translated
@section Translated
@translationof Original
we could also write
@node Original
@section Translated
which would take care of the .html file names automatically (modulo
the
lower-casing which we do for aesthetics, but that's easy and
potentially even more debatable).
It sounds interesting...
The obvious downside is that references in the translated
documentation
get a bit more complex:
* For references in the same document (say inside the NR), we'd have
to write @ref{Original} instead of @ref{Translated}. Together with
@xrefautomaticsectiontitle on, this will still show the translated
section title for PDF and HTML (does not seem to work for .info, but
see first paragraph why this isn't actually a problem), even if it
looks a bit weird / funny.
* For cross-references, we'd have to manually provide the mapping. So
instead of @ruser{Translated}, we'd have to write
@rusernamed{Original,Translated} to make the link text appear
translated.
It would be better IMO, because a translator would not have to update
all the @ref after translating a page. IIRC updating/translating the
@ref is not necessary for HTML documents, but it is for PDF documents.
What you write below is probably the explanation of this difference.
For historical context: It appears that in the distant past,
translated
documentation was written with
@node Original
@section Original
which obviously works for the .html file names. To still get
translated
link text, there were two scripts: html-gettext.py replaced the text
in
the already generated .html files, and texi-gettext.py did the same
before calling texi2pdf. Compared to that state, using "@section
Translated" automatically takes care of references in the same
document
(only requiring us to specify the @node in English). Looking at the
French documentation, that's the largest fraction with around 1400
occurrences while there are "only" 94 matches of plain @ruser
(@rusernamed doesn't count here because the removal of .xref-map would
just change the first argument from the translated version to the
English @node, while the actual display text stays exactly the same).
What do people think, especially translators? Would this "annoyance"
be
acceptable if it provides a significant simplification of our
infrastructure? Another advantage would be that each document is self-
contained, ie no more recompilation of all documentation for changes
that do not affect cross-references at all.
What is the "annoyance" exactly?
I would like to see a test for a language in order to better understand.
Would you take care of all the changes required in translated files?
("swapping" @translationof and @section, changing the @ref occurrences,
...)
