Install Guide now in Publican

[Joshua Wulf]

r0ck out!

Ruediger Landmann wrote:
> 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.
>


-- 
Joshua J Wulf
Engineering Content Services
Red Hat Asia Pacific

eml: jwulf at redhat.com
tel: +61 (0)7 3514 8140
mob: +61 (0)431 929 675
tmz: GMT +10

(0) - omit when dialling internationally