10:22 p.m.
On 05/27/2010 10:29 AM, Domingo Becker wrote:
Would you please ask him to generate a .pot file for a chapter?
So, if there are n chapters there will only be n .pot files.
The huge number of .pot files isn't helpful for translation. It even
makes Tx's life harder. It would also prevent string repetition. To
see this issue, just run "msgfmt -c *.po" in es-ES, for example.
As I said, I'm answering this is a separate thread because it's quite a
separate (and complicated!) issue from how untranslated books are linked
on the docs website...
The problem here has nothing to do with Publican and everything to do
with the XML structure of individual books. As you probably know, the
Installation Guide is highly unusual in this regard; /most/ books do
indeed have a single PO file per chapter (or at least, per major
section). The peculiar structure of the Installation Guide is due to the
interaction of two factors:
The first factor is the requirement of DocBook XML that the ID of a node
must be unique in the entire book. For example if you have:
<chapter id="Graphical_Installation">
<title>The Graphical Installation Process</title>
<para></para>
<para></para>
<para></para>
<para></para>
</chapter>
You can only have this chapter *once* in a <book>. Alternatively, if you
leave out the "id" attribute from the <chapter> tag, you cannot link to
the chapter from elsewhere in the book.
The second factor is the desire to reduce overall writer and translator
load by sharing as much content as possible between two Red Hat
Enterprise Linux books and two Fedora books. When combined with the
above restriction, this creates a special problem for the Installation
Guide, where we have many many identical paragraphs that are shared both
*inside* the Red Hat Enterprise Linux versions of the book, and
*between* the Red Hat Enterprise Linux versions and Fedora versions. In
fact, in eight places! :
Fedora Installation Guide
Fedora Installation Quick Start Guide
x86 part of the Red Hat Enterprise Linux 5 Installation Guide
PowerPC part of the Red Hat Enterprise Linux 5 Installation Guide
System z part of the Red Hat Enterprise Linux 5 Installation Guide
x86 part of the Red Hat Enterprise Linux 6 Installation Guide
PowerPC part of the Red Hat Enterprise Linux 6 Installation Guide
System z part of the Red Hat Enterprise Linux 6 Installation Guide
(note that we only really maintain a single "latest" version of the
Fedora books, but must actively maintain separate Red Hat Enterprise
Linux 5 and Red Hat Enterprise Linux 6 books; if we had more resources,
we really should maintain two separate versions of each of the Fedora
books too, to reflect the two versions of Fedora current at any time)
These eight places all contain a similar set of paragraphs but not every
paragraph is included in every one of those eight places or are exactly
the same in all eight places -- the places are *mostly* the same but not
*completely* the same. We get around it this way:
<book>
<part id="Installation-x86">
<title>Installing on x86 architecture</title>
<chapter id="Graphical_Installation-x86">
<xi:include title-1>
<xi:include para-1>
<xi:include para-2>
<xi:include para-3>
<xi:include para-4>
</chapter>
...many other chapters here...
</part>
<part id="Installation-ppc">
<title>Installing on PowerPC architecture</title>
<chapter id="Graphical_Installation-ppc">
<xi:include title-1>
<xi:include para-1>
<xi:include para-2>
<para>PowerPC has an extra paragraph here</para>
<xi:include para-3>
<xi:include para-4>
</chapter>
...many other chapters here...
</part>
<part id="Installation-s390">
<title>Installing on IBM System z architecture</title>
<chapter id="Graphical_Installation-s390">
<xi:include title-1>
<xi:include para-1>
<xi:include para-2>
<para>This para is different for System z</para>
<xi:include para-4>
</chapter>
...many other chapters here...
</part>
</book>
Each para that is used more than once is contained in a single XML file
and therefore a single POT and a single PO file per language.
A single PO file for any of these chapters would significantly increase
the amount of string repetition, not decrease it. It also means that any
correction to a single paragraph must happen in up to eight different
XML files and up to eight different PO files *per language*.
In saying all this, I'm certainly not trying to deny that structuring
the book this way also creates a different set of new problems for
translators. I'm just trying to explain the reasons behind the design
decision. I also acknowledge that the bigger problem of how these books
interact with their Red Hat Enterprise Linux counterparts (and how the
sections within the Red Hat Enterprise Linux books interact with each
other) might not have been clear up to now for those who have only seen
the Fedora books. Anyone who's interested in seeing the interaction more
closely should visit: http://www.redhat.com/docs/manuals/enterprise/
Thanks Domingo for the excellent question -- I'm sure this is something
that lots of people have wondered about when they confront the maze of
the Installation Guide...!
Cheers
Rudi