neysx at gentoo
Oct 11, 2004, 9:55 AM
Post #2 of 10
(746 views)
Permalink
|
|
Re: GDP Projects - Let's Get Things Moving (long)
[In reply to]
|
|
Sven Vermeulen wrote:
> Okay, I'm feeling productive again and have a lot of ideas for the GDP.
> Some of them have been brought up earlier but dismissed due to insufficient
> resources, others are ideas I've stolen from people that didn't dare to tell
> it out loud, the rest is fairly new and due to a huge cafe�ne concentration
> in my body.
The blood level of my cafeïne is rather low ;-)
> My first observation is that we have an abstract tag in each of our
> documents (mandatory) that's only used for the upper right corner. It seems
> to me that this abstract can very well be used as a description of the
> document for our index page.
Indeed. BTW, allowing both "file.xml" and "/path/to/doc/LANG/file.xml" might
be a problem, but more about that later...
> What I was thinking about is to write an XML format (to be chained to
> GuideXML) that includes each document and automatically uses the abstract as
> a description. This format would make it possible to have two documentation
> index'es:
> - index.xml, desktop.xml and additional index'es that look the same as
> they are now (but with the abstract information)
> - list.xml which contains links to every single document we have without
> additional information
>
> This latter is something cam also requested (one document that lists them
> all) and I proposed something along the lines of
>
> <ul>
> <li>
> Category 1
> <ul>
> <li><uri link="${DOCUMENT}">${DOCUMENT_TITLE}</uri></li>
> ...
> </ul>
> </li>
> <li>
> Category 2
> ...
> </li>
> ...
> </ul>
>
> Writing such an XML (well, actually DTD+XSL+XML) is fairly simple, *but*
> since I'm always trying to get Xavier on my neck with my proposals, I'd like
> to go even further and have his TradsXML format that he uses for the translation
> summary incorporated. I believe (although I haven't written a POC yet) that
> we can have such a translation summary incorporated so that this is
> available on the official website.
I also think it's about time we had a list.xml of our docs. It might even be
the first step to an index generator (I mean an index like at the end of
books, not like the current index.xml).
We'd need to list documents and also files for multi-file docs like a
handbook, categories (one doc can appear in several categories), some meta
information like whether the doc is required to be translated, whether it is
translatable. Originals' revision number would be best stored in each file
because CVS can ensure it is up-to-date ($Revision$). Anything else?
It needs to allow listing docs outside of /doc/en/ as well BTW.
Another thing: list active languages and known languages. Active ones could be
used to generate the list of languages at the beginning of our indexes, the
known ones would be used when processing document paths. i.e. if anything from
known languages appears between //, i.e. .../fr/..., we know the document is
a translation of .../en/... I'm not too keen on having an attribute like
translation_of="/doc/en/original.xml" in the <guide> element.
> And, to make things even worse, I'm thinking about extending the book.dtd
> definition to have a <version> and <date> entity within the <sections>
> entity (mandatory) so that each hb-* file has it's own version/date
> information.
YeaHa!
It's a real PITA to update those in all handbook-ARCH.xml whenever anything
has been changed in a common part. It's a double-PITA when you update
translations at the same time.
We need to be able to display "updated #{max(hb*xml.date)}" on handbook pages BTW.
> I was (but have dropped the idea) thinking about adding an optional
> attribute to the "version" tag that had information about the English
> revision, so that translated documents could have:
> <version english="1.32">2.1</version>
> in which the "english" attribute referenced the CVS Revision of the English
> document to which the document was translated, but I dropped the idea
> because it's confusing and the above proposal (Xavier's TradXML format)
> includes the necessary information already.
I'm happy you dropped that idea ;-)
I quite dislike mentioning the original's revision in a translation because it
means whenever a new revision of an original is committed purely for language
reasons (i.e. typos, rephrasing...), you need to commit a new revision of the
translation as well just to say "nothing has changed".
> So, short summary:
> - Write an XML to be chained to GuideXML that incorporates Xavier's
> TradXML format
> - Have index.xml and others automatically generated from the abstract
> information
> - Have a single document that links to all existing documents
>
> Thoughts? Ideas? I won't do anything about this for at least 5 days so that
> everything can be thought of and discussed properly (I know I have the bad
> habit of pushing things which is why I force myself upon this 5 days "lag").
My TradsXML cannot be used a such because it holds information like the path
to the local CVS copy on the translator's disk, contributors' email, bla bla
bla. I'll update my TMS --Translation Management System :-) -- to use whatever
solution we decide to implement.
The one thing it holds that we could use is the revision number of the English
revision that has been translated. I definitely want to keep that out of the
translated docs themselves and a common format used for all languages would be
an improvement IMO.
> A second thing I am thinking about is to add a warning to all outdated
> documentation. Outdated would mean that it's not accurate to the definition
> in the Translators Howto [1].
>
> The warning would constitute something like this:
>
> <warn>
> This translation is not up to date with the latest <uri
> link="path/to/english.xml">English document</uri> conform the documentation
> project's <uri link="path/to/accuracy.xml">Translation Accuracy
> Guidelines</uri>. If you want to help us update this document, please
> contact <mail link="lead [at] translato">Franky Oobar</mail>, the Bleh Lead
> Translator, or file a <uri link="http://bugs.gentoo.org">bugreport</uri> and
> attach an updated version.
> </warn>
I'm 100% behind this.
> This would be translated first (we might want to store this translation
> somewhere) and can easily be filled in. The warning would be put before the
> first sentence (<p> entity) although I don't think we need to add a specific
> <chapter><title>...</title><section><body> construct just for this.
>
> This not only informs users about the not-so-updated documentation (which
> reduces the number of mails sent to www [at] gentoo) but might also result in
> more contributions (who knows).
>
> We _can_ (but it's hackish) include the translation (which is two-fold) in
> the inserts-${LANG}.xml file
Not at the moment. IIRC, our gettext will only work with a single string, not
a node-set. No big deal but you need to know.
Maybe /doc/{LANG}/outdated.xml is a neater way even though it's yet another file.
> and add an attribute to the GuideXML format so we
> can just include
> <version outdated="yes">...</version>
> which will automatically add in this warning (although the location may be
> different here).
Hmmm.
The lead translator simply removes this attribute when updating the
translation but what or who sets this attribute, when and how?
+++++++++++++++++++++++++++++++++++++++++++++
Hey, wait a minute!
Can't it all be simpler?
Let's say we have a list.xml with a list of documents and some metadata.
We can use it to generate indexes, lists of documents...
Let's say we can rely on the <version> and <link> elements.
When a <guide|book> document is processed, use the following pseudo-code:
If no /en/ in link attribute or lang attribute not 'en',
# Doc is a translation
Find original (replace /{LANG}/ with /en/)
compare <version> elements of both docs
if versions differ,
issue warning
# We may even display version numbers or
# add "('very' | '' | 'slightly') outdated"
# depending on (en.version - {LANG}.version)
If we rely on <version>, lead translators do not need to commit anything to
say "my translation is still up-to-date" because <version>'s match as long as
there is no content change.
It looks like Sven has started a very interesting thread!
BTW, any reason we have 2.x and 3.x versions of our handbook?
$ grep '<version>' h*-*xml
handbook-alpha.xml:<version>2.94</version>
handbook-amd64.xml:<version>3.2</version>
handbook-arm.xml:<version>2.97</version>
handbook-hppa.xml:<version>2.94</version>
handbook-mips.xml:<version>2.84</version>
handbook-ppc64.xml:<version>2.63</version>
handbook-ppc.xml:<version>3.4</version>
handbook-sparc.xml:<version>2.95</version>
handbook-x86.xml:<version>2.118</version>
Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\
|
signature.asc
