On Wed, 2023-01-04 at 22:58 +0100, Federico Bruni wrote: > 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.
Yes, that's me basically. I could probably solve my personal use case by proposing a patch that keeps the .html extension in links inside the English documentation (so whenever you chose English, you stay with the untranslated version), but I'm pretty sure others want a different behavior (for example you below, I think). Anyway, I will take this as "we probably want some automatic switching in one way or another", which requires identical .html file names to start with. > 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. This is the current behavior, no? Apart from the fact that the language choice is currently coming from the browser... > 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. Interesting. I guess this is another aspect of what I described as "self-contained"... > 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. Our texi2html customization has a lot of fallback code, so I guess it transparently handles untranslated cross-references correctly? > > 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? 1. All @ref{Translated} become @ref{Origin}, but as far as I understand that may actually be an advantage. 2. All @ruser{Translated} become @rusernamed{Origin,Translated}, ie you have to provide both the original @node *and* the translated display text. For @unnumberedsec, we may even need a third argument to get the anchor correct - not sure how often that is actually needed. > 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, > ...) Yes, this would be automated, I hope. It's actually funny that the script for the last change in 2008 / 2009, from the state that I describe in the "historical context" above to what we have today, is still in the repository: scripts/auxiliar/tely-gettext.py
signature.asc
Description: This is a digitally signed message part
