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

List:       kde-i18n
Subject:    Where should translated documents go (was Re: Where should go translated documentations)
From:       Peter Silva <peter.silva () videotron ! ca>
Date:       1998-12-08 5:07:20
[Download RAW message or body]

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?


I'll start looking at getting the problems shown up by the audit URL
fixed
while people chew on this.


-- 
Peter

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