Installation Guide structure (was: default link for untranslated books)

[Ruediger Landmann]

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