lilypond-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Musings on our translated documentation build


From: Jonas Hahnfeld
Subject: Musings on our translated documentation build
Date: Wed, 04 Jan 2023 14:39:47 +0100
User-agent: Evolution 3.46.2

During the last months, I've played a bit with Texinfo and would like
to discuss some ideas / simplifications for our translated
documentation. The base assumption is that translated .info files are
not important, ie we only build and install the English versions. If
that's not the case, please let me know and you can probably stop
reading here.

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

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.

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.

Cheers
Jonas

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]