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.
On Wed, Feb 25, 2009 at 02:07:12PM +1000, 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.
Superb! Great news Ruediger -- thank you for your work on this.
There are small structural changes between the f10 version of the files and the files in the current master branch, specifically:
[...snip...]
- 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
Really? Isn't using &DISTRO; a pretty good way to go, as opposed to doing manual search and replace on "Fedora"? On the other hand, I'm sure the usage wasn't consistent throughout which is surely a problem in itself.
[...snip...]
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?
I'd say this is something to bring to fedora-trans-list, which is the mailing list for the global Fedora L10n team.
On the RPM front:
- What needs to happen to get an RPM of this document approved for
inclusion in Fedora?
Probably the regular stuff -- produce a spec file and SRPM, and file a bug for package review. There's more information on the package maintainers site, but I believe Eric is going through (has been through?) this process too.
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
Nice work.
Paul W. Frields wrote:
Really? Isn't using &DISTRO; a pretty good way to go, as opposed to doing manual search and replace on "Fedora"? On the other hand, I'm sure the usage wasn't consistent throughout which is surely a problem in itself.
Some languages attach various grammatical elements (articles, prepositions, case markers) to nouns, which means that an entity that always appears exactly the same way in English may take a number of different forms in a target language that behaves this way.
By way of illustration: In Czech, if "Fedora" is the subject of a sentence, it's written "Fedora". However, if "Fedora" is the direct object of the sentence, it becomes "Fedoru", if it has a possessive sense ("Fedora's" or "of Fedora" in English), it becomes "Fedory", if it's an indirect object or indicating a location ("to Fedora", "in Fedora") it's "Fedoře", and if it has an "instrumental" sense ("with Fedora") it's "Fedorou" . So:
"Fedora is a Linux distribution" -> "Fedora je linuxová distribuce" (note also what happens to "Linux" in this sentence; if it were the subject of the sentence it would be "linuxové")
but
"Get Fedora" -> "Stáhnout Fedoru"
and
"Installation of Fedora" -> "Inštalácia Fedory"
and
"People involved in Fedora" -> "Lidé podílející se na Fedoře"
and
"The most common problems with Fedora" -> "Nejběžnější problémy s Fedorou"
(there's another form as well, the "vocative", which you would use when calling out to Fedora – "Oh mighty Fedora!" – but I can't find a practical example of this) But in short: seven different grammatical cases represented by six different forms of the word; all supposed to be represented by one single entity in English. [1]
English pronouns still inflect for grammatical case, so this would be like deciding to set an entity for the word "he". That's fine as the subject of a sentence, but what do you do when the sentence needs the pronoun to change to "him" or "his"?
Thanks Paul for the pointers to fedora-trans-list and the package maintainer's site. I still need a few of these signposts :) and thanks to all for the positive feedback so far.
Cheers Rudi
[1] Actually, I'm not a Czech speaker. The situation is very similar in Russian (which I know a little) but didn't want to use that as an example because of the different alphabet. The examples I've used here, however, are collected from the Internet (in particular, from http://www.fedora.cz/ ), and are not of my own devising. My apologies to any Czech speakers reading this if I haven't got things quite right! Even if I have munged things up a little at some point, I think it still illustrates the pitfalls of using entities that indicate a particular form in English when translating into a highly-inflected target language. Russian and Czech have seven cases for nouns. Finnish has fifteen, and Hungarian has seventeen.
On Wed, Feb 25, 2009 at 7:44 PM, Ruediger Landmann r.landmann@redhat.com wrote:
Paul W. Frields wrote:
Really? Isn't using &DISTRO; a pretty good way to go, as opposed to doing manual search and replace on "Fedora"? On the other hand, I'm sure the usage wasn't consistent throughout which is surely a problem in itself.
Some languages attach various grammatical elements (articles, prepositions, case markers) to nouns, which means that an entity that always appears exactly the same way in English may take a number of different forms in a target language that behaves this way.
By way of illustration: In Czech, if "Fedora" is the subject of a sentence, it's written "Fedora". However, if "Fedora" is the direct object of the sentence, it becomes "Fedoru", if it has a possessive sense ("Fedora's" or "of Fedora" in English), it becomes "Fedory", if it's an indirect object or indicating a location ("to Fedora", "in Fedora") it's "Fedoře", and if it has an "instrumental" sense ("with Fedora") it's "Fedorou" . So:
"Fedora is a Linux distribution" -> "Fedora je linuxová distribuce" (note also what happens to "Linux" in this sentence; if it were the subject of the sentence it would be "linuxové")
but
"Get Fedora" -> "Stáhnout Fedoru"
and
"Installation of Fedora" -> "Inštalácia Fedory"
and
"People involved in Fedora" -> "Lidé podílející se na Fedoře"
and
"The most common problems with Fedora" -> "Nejběžnější problémy s Fedorou"
(there's another form as well, the "vocative", which you would use when calling out to Fedora - "Oh mighty Fedora!" - but I can't find a practical example of this) But in short: seven different grammatical cases represented by six different forms of the word; all supposed to be represented by one single entity in English. [1]
English pronouns still inflect for grammatical case, so this would be like deciding to set an entity for the word "he". That's fine as the subject of a sentence, but what do you do when the sentence needs the pronoun to change to "him" or "his"?
Thanks Paul for the pointers to fedora-trans-list and the package maintainer's site. I still need a few of these signposts :) and thanks to all for the positive feedback so far.
Cheers Rudi
[1] Actually, I'm not a Czech speaker. The situation is very similar in Russian (which I know a little) but didn't want to use that as an example because of the different alphabet. The examples I've used here, however, are collected from the Internet (in particular, from http://www.fedora.cz/ ), and are not of my own devising. My apologies to any Czech speakers reading this if I haven't got things quite right! Even if I have munged things up a little at some point, I think it still illustrates the pitfalls of using entities that indicate a particular form in English when translating into a highly-inflected target language. Russian and Czech have seven cases for nouns. Finnish has fifteen, and Hungarian has seventeen.
-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
I may be showing my ignorance here.....but I thought that since Fedora is a trademark, and a proper name that it was always Fedora. Much as I am always David regardless of what country I may be in or language I may be speaking.
David Nalley wrote:
I may be showing my ignorance here.....but I thought that since Fedora is a trademark, and a proper name that it was always Fedora. Much as I am always David regardless of what country I may be in or language I may be speaking.
Short answer: No
A longer and more complete answer:
Inflected languages inflect proper nouns as well (including trademarks). It's worth keeping in mind that these inflections are not just something "tacked onto" the noun; they represents a fundamentally different way of structuring the language from the way that Modern English does it. They're an essential part of how these languages work, which is counter-intuitive for English speakers.
To stick with the previous example, if people were talking about you in Czech:
Subject in a sentence: David
Possessive: Davida "David's book" -> "Kniha Davida"
Direct object in a sentence: Davida
Indirect object of a sentence: Davidovi
Vocative: Davide "Hey David!" -> "Ahoj Davide!"
I'm on shaky ground here with the specifics, so I'll leave it at that. Note that English has a tiny remnant of this as well; your name changes from "David" to "David's" to indicate possession. [1]
To give you an idea of the range of languages for which this is an issue, they include, just in Europe, all the Slavic languages (eg. Russian, Czech, Polish, Serbian, Croatian and many many more) the Finno-Ugaric languages (Finnish, Hungarian, Estonian and others – these have a /highly/ complex case system), as well as Turkish, Greek, and Armenian.
Note that so far, I've only discussed the way that grammatical case can change nouns, but languages change nouns for other reasons too, such as to affix or suffix articles onto them.
Cheers Rudi
[1] Old English (Anglo-Saxon) also had a system of inflected endings for nouns, but with only four cases, rather than Czech's seven and Hungarian's seventeen. The possessive singular ending for masculine nouns in Anglo-Saxon was "es" (so "David's book" -> "Davides boke"). This carried over into Middle English for almost all nouns, regardless of grammatical gender or number. Modern English retains an apostrophe to show where an "e" has been left out for the past 600 years or so, in precisely the same way that the apostrophe in "don't" shows where an "o" has been left out.
On Thu, Feb 26, 2009 at 10:44:19AM +1000, Ruediger Landmann wrote:
Paul W. Frields wrote:
Really? Isn't using &DISTRO; a pretty good way to go, as opposed to doing manual search and replace on "Fedora"? On the other hand, I'm sure the usage wasn't consistent throughout which is surely a problem in itself.
Some languages attach various grammatical elements (articles, prepositions, case markers) to nouns, which means that an entity that always appears exactly the same way in English may take a number of different forms in a target language that behaves this way.
As soon as I read the first sentence I remembered exactly this problem that we had in our translations originally. That's why, in the Fedora Docs toolchain, our entites are parsed before being committed to the POT. That way the translators see the real text and can translate appropriately for their parts of speech.
So if our XML text included:
<para>Welcome to &DISTRO;.</para>
...in the POT that would end up as:
msgid "" "Welcome to Fedora."
...and then the translator could handle that string as any other. We tried leaving the entities in the POT file for about a week, and the translators quickly reminded us of the same thing you did -- requirements for noun declinations, and so forth. So we reverted to the behavior above. The precise way we do this is with the command 'xml2po -e', using the gnome-doc-utils package. We tried the '-k' switch in the past, which caused the problem I just described, so we went back to '-e'. In fact, I think you'll find a note in our old toolchain Makefile saying something like "Don't ever use '-k', that would be stupid." :-D
So would I be correct in thinking that's not what Publican does, and that entities are only supposed to be used in Publican docs to represent non-translatables like a year or a company name?
Thanks Paul for the pointers to fedora-trans-list and the package maintainer's site. I still need a few of these signposts :) and thanks to all for the positive feedback so far.
Thank you for all your hard work.
Paul W. Frields wrote:
So would I be correct in thinking that's not what Publican does, and that entities are only supposed to be used in Publican docs to represent non-translatables like a year or a company name?
Yes, that's correct. Publican is built on the KDE tool xml2pot, not the GNOME tool xml2po, and xml2pot doesn't have the "-e" option that xml2po does.
Publican uses xml2pot because it is /significantly/ faster than xml2po, which is important when handling the huge documents that we work with in Red Hat Engineering Content Services. To put the difference in perspective: while Publican was in early development, conversions of the Red Hat Enterprise Linux Deployment Guide (a document of around 300,000 words) were done with both tools. Xml2pot finished the entire run in all 23 languages around the same time that xml2po finished the /first/ language!
That said, there are such obvious advantages to using entities such as &DISTRO; so this is something that will no doubt be revisited if and when xml2pot ever gets an option equivalent to "-e". But for now, we just can't do it.
Cheers Rudi
On Fri, Feb 27, 2009 at 09:01:10AM +1000, Ruediger Landmann wrote:
Paul W. Frields wrote:
So would I be correct in thinking that's not what Publican does, and that entities are only supposed to be used in Publican docs to represent non-translatables like a year or a company name?
Yes, that's correct. Publican is built on the KDE tool xml2pot, not the GNOME tool xml2po, and xml2pot doesn't have the "-e" option that xml2po does.
Publican uses xml2pot because it is /significantly/ faster than xml2po, which is important when handling the huge documents that we work with in Red Hat Engineering Content Services. To put the difference in perspective: while Publican was in early development, conversions of the Red Hat Enterprise Linux Deployment Guide (a document of around 300,000 words) were done with both tools. Xml2pot finished the entire run in all 23 languages around the same time that xml2po finished the /first/ language!
Having sat through our toolchain's build process innumerable times, I definitely see your point. Not sure why the xml2po tool hasn't been fully ported to C at this point, but meh.
That said, there are such obvious advantages to using entities such as &DISTRO; so this is something that will no doubt be revisited if and when xml2pot ever gets an option equivalent to "-e". But for now, we just can't do it.
*nod*
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.
-
David Nalley -
Joshua Wulf -
Paul W. Frields -
Ruediger Landmann