Install Guide now in Publican

[Ruediger Landmann]

Hey all,

just letting you know that the Installation Guide is now fully 
"Publicanized".

I can confirm that every language version of the guide builds in html, 
html-single, and PDF, with only one exception -- Chinese Simplified. I 
/can/ confirm that Chinese Simplified builds in html and html-single, 
but I haven't been able to confirm that it builds in PDF [1].

RPM building also works.

I've placed the publicanized version of the guide in the master branch 
of the repo, and the f10 version in its own branch.

There are small structural changes between the f10 version of the files 
and the files in the current master branch, specifically:

* the Guide now includes Publican's standard Preface, which explains the 
typographic conventions used in the document
* by default, Publican places the "Feedback" section in the Preface, so 
I've moved it there from its previous position in the "Introduction"
* the "Colophon" wasn't really a colophon; I've renamed it to 
"Contributors and production methods", which is what it actually 
contains. The "Contributors" section within this now includes a full 
list of the community translators who have worked on the guide (I drew 
these from the translation files).
* the Tamil translation file didn't actually contain any translations; 
I've removed it for the moment.
* I've removed most of the entities that were used in the document; not 
only were they a real mess, but they were going to create significant 
problems when positioning the guide upstream of the RHEL Installation Guide
* I've added country codes to folders containing translation files for 
certain languages, so Publican can take advantage of the Common Content 
already built into Publican for these languages. Note that these folders 
are named according to the IETF RFC 4646 standard that XML uses for 
language and country codes, not the GNU hybrid of "ISO 639-2 language 
code and two-letter ISO 3166 country code separated by an underscore". 
Publican expects to see the RFC 4646 version. I'm aware that the 
inclusion of a country code is a contentious area for some translators, 
and have filed a bug about this [2]. Note that this issue doesn't 
presently affect languages that we don't have any Common Content for, 
but I've also renamed the Serbian-with-Latin-alphabet folder in 
compliance with RFC 4646.

Some urgent action is now needed on the localization front:
* f10 needs to be presented as a valid branch in the Transifex system; 
and the separate .po files of the Publicanized version need to be made 
available to translators
* Publican includes two "Common Content" files that need translation 
into languages that Red Hat doesn't support. They are "Conventions" 
(which explains the document conventions) and "Feedback" [3]. The great 
news here is that once these have been translated into any given 
language, they will be available for /all/ Publicanized Fedora docs 
produced in that language, since the .po files can be built into the 
Fedora brand that installs with Publican. I've generated .pot files for 
these three sections. Other than approaching translators directly, is 
there another way to bring these to community attention?

On the RPM front:
* What needs to happen to get an RPM of this document approved for 
inclusion in Fedora?

What I'm doing next:
* working out how content can be merged between the Fedora and Red Hat 
Enterprise Linux Installation Guides, which will allow the Fedora 
version to be positioned upstream

Cheers
Rudi

[1] on my machine, the build process finishes successfully and generates 
a PDF file, but the body text contains nothing but whitespace (although 
the chapter and section headings render correctly). I suspect this is 
simply a problem on my machine, however, and haven't tested it on anyone 
else's yet.
[2] https://bugzilla.redhat.com/show_bug.cgi?id=487256
[3] the Installation Guide doesn't use the Common "Feedback" section – 
it has its own, custom "Feedback" section instead. We still need to get 
this translated into as many languages as possible ASAP, both for the 
sake of other Fedora Docs, and in case we want future versions of the 
Installation Guide to line up with what's in the docs that /are/ using 
the standard "Feedback" section.