[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n
Subject:    Re: Where should translated documents go (was Re: Where should go translated documentations)
From:       Stephan Kulow <coolo () kde ! org>
Date:       1998-12-08 10:20:00
[Download RAW message or body]

Peter Silva wrote:
> 
> Stephan Kulow wrote:
> >
> > Bertrand Leconte wrote:
> > >
> > > Hi,
> > >
> > > Currently, we have documentations in two places:
> > > - in source CVS (kdebase, kdenetwork,...) for the english language
> > >   and some translated ones
> > > - in www for the i18n project.
> > >
> > > Who is responsible for merging the two?
> > > If it's done when we make the distributions, we should only
> > > keep the english version in sources. If it's developpers' job,
> > > we should say it.
> > >
> > > We is responsible to put in www english version?
> > >
> > This is a topic where many things went wrong I have to say.
> > There is still noone that came up with a good idea how to
> > handle it.
> >
> > Greetings, Stephan
> >
> 
> Since I'm the head of the "English Team" (which consists of 1 person
> :-),
> this is my problem.  Being a programmer, I wrote a script, look at the
> output here:
> 
> http://pages.infinit.net/psilva/kde/kde/doc_audit.html
> 
> (I didn't say it was pretty...)
> (a link to the source for the script is at the end of that page.)
> 
> This audit brings to light a few problems:
> 
>   1) The directory structures are different:
> 
>        a) module/app/doc/<app>.sgml   in the package,
>        b) <lang>/<category>/<app>/index.sgml  under www/documentation,
>        c) KDEDIR/doc/<lang>/<app>/index.html  once installed.
> 
>   Typically, the sgml is in the same dir as the html.
> 
>   My suggestion:
>                 have apps conform to the c) style path, so that:
> 
>         1.1) An author can compose documentation in a language other
>            than English, and the translation team can pick it up.
>            Eric (ebisch@cybercable.tm.fr) is ready to receive foreign
>            language original docs and send them to the right translation
>            team.
> 
>         1.2) There is no guesswork in figuring out which document corresponds
>            to which part of which package.
> 
>         1.3) There is an easy and clear way to copy the tree back
>            to the source (renaming <app>.sgml --> <app>/index.sgml,
>            and vice-versa is a pain.), and we can add other
>            languages back into the package.  (with only doc/ currently,
>            the only language reasonable to copy back is English.)
> 
> 
>   2) Two versions of every manual are supposed to be revision
>      controlled (development version, and www/doc/en version.)
>      This is bad, merging the two versions will be a constant pain.
> 
>      I think the right thing to do is to put all the documentation
>      in the code tree (ie with the applications) and have a cron job
>      generate the tree under wwww/documentation from the code tree.
> 
>      good:
>         -- ensures consistency, with 0 labour.
>         -- maintains ability to download docs separate from apps,
>            if a way can be found to exclude them from snapshot
>            generation (is that possible/easy ?)
> 
>      bad ?:
>         -- CVS source code modules now include all translations,
>            but they already include i18n anyways, so I think this
>            is more consistent.  They're not all that big, I don't
>            see this as a major issue. Perhaps others do.  I'm only
>            referring to the CVS itself.  I think binary packages built
>            from it could exclude languages other than English,
>            it would only require a little work on the generation
>            scripts.
> 
>         -- Documentation team will be explicitly committing files
>            into packages.  I think this is what CVS is made to allow.
>            It will be good for corrections to be applied to the original
>            documentation, and if authors change it, that it remain
>            traceable (via CVS) to find what was added so translators
>            may be able to only translate what has been added/changed.
> 
>            The people committing the sgml would also be responsible for
>            updating the html.
> 
>         -- what to do about doc installation on make install ?
>            I don't know, some kind of a flag to say what langs to
> install
>            docs/i18n for ?  It only has to install .html files.
> 
>         -- Need a hook to allow for inclusion of non-CVS packages in
>            the same tree.  Do we really?  We could just as well send
>            the translations back to the author/distributor, so at least
>            they would stay with the package.  Not sure about this.
> 
> 
>    3)   There is no way to know when an app is "finished."  We only
>         want to translate apps when they are finished, to avoid re-doing
>         the translation unnecesarily.  The changes described in 2) will
>         at least make it obvious when the source has changed, so perhaps
>         the overal team leader can prod the developer with a question like
>         "is that doc stable, or are you about to revise it more?"
>         and only pass it on to translators once we get the right answer.
> 
> This is kind of a major change, What do people think?
> 
OK, let's start a discussion about this NOW. I wanted to wait for 1.1,
but
it's no problem to discuss before ;)

What we want is to move the i18n and doc stuff out of the sources and
keep
them in a seperate module. Even the english docs could/should be moved
out to be
fair within the languages ;)

The po files are already much too big and noone has an advantage of
having
26 languages at once, so we need a mechanism to select the right
language
while installing (with RPM/DEBs this shouldn't be too hard).

Adding the docs to the sources as well, would dramatise the situation
even
more and I'm still not in favour of that.

The to be created module should contain all po files of applications
within
standard packages, perhaps structured as this. External applications
_may_
be held there as well, but don't have to.

When the module gets too big as well, we could split it further into
smaller parts, but for the start I see one module. 

Greetings, Stephan

-- 
Carol: When you first entered the restaurant, I thought you were 
handsome... and then, of course, you spoke. - As Good as It Gets

[prev in list] [next in list] [prev in thread] [next in thread]