Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
Japanese. I hope the work would finish within 1-2 months. My question
is how the translated docs could be merged into the doc source tree
once it is done. Maybe doc/ja/src/sgml?
--
Tatsuo Ishii

Mon, 18 Jun 2001 10:02:53 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Doc translation
Tatsuo Ishii <t-ishii@sra.co.jp> writes:
> Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> Japanese. I hope the work would finish within 1-2 months. My question
> is how the translated docs could be merged into the doc source tree
> once it is done. Maybe doc/ja/src/sgml?

Hmm, *should* they be merged into the source tree, or distributed as
a separate tarball?  I'm concerned that they'd always be out of sync
with the English docs :-(

			regards, tom lane

Sun, 17 Jun 2001 22:11:44 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: Doc translation 
> Tatsuo Ishii <t-ishii@sra.co.jp> writes:
> > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> > Japanese. I hope the work would finish within 1-2 months. My question
> > is how the translated docs could be merged into the doc source tree
> > once it is done. Maybe doc/ja/src/sgml?
> 
> Hmm, *should* they be merged into the source tree, or distributed as
> a separate tarball?  I'm concerned that they'd always be out of sync
> with the English docs :-(

Right. However, it would be greater for Japanese users to have the
Japanese docs in the *official* distribution of PostgreSQL, than
getting them from other places. What about setting up a new CVS module
for the Japanese docs, isolated from the source and English doc
module(pgsql)?
--
Tatsuo Ishii

Mon, 18 Jun 2001 12:06:09 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: Doc translation 

----- Original Message ----- 
From: Tatsuo Ishii <t-ishii@sra.co.jp>
Sent: Sunday, June 17, 2001 11:06 PM


> > Tatsuo Ishii <t-ishii@sra.co.jp> writes:
> > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> > > Japanese. I hope the work would finish within 1-2 months. My question
> > > is how the translated docs could be merged into the doc source tree
> > > once it is done. Maybe doc/ja/src/sgml?
> > 
> > Hmm, *should* they be merged into the source tree, or distributed as
> > a separate tarball?  I'm concerned that they'd always be out of sync
> > with the English docs :-(
> 
> Right. However, it would be greater for Japanese users to have the
> Japanese docs in the *official* distribution of PostgreSQL, than
> getting them from other places. What about setting up a new CVS module
> for the Japanese docs, isolated from the source and English doc
> module(pgsql)?

What about the possibility of having docs translated into another
languages? Would you then include all those translations into the
*official* PostgresSQL distribution? There're many languages out there,
and maybe eventually the PG docs will get translated to these (some of these)
languages. Wouldn't it be too much of the documentation per
distribution? I guess that the setting up a separate CVS module 
per language might be a good idea. People just grab the distribution and docs in
desired language, and plug the docs in, and here you go. And the docs are almost always
"out-of-sync" with the distribution anyway :), even the English ones...

Serguei




Mon, 18 Jun 2001 01:08:13 -0400
"Serguei Mokhov" <sa_mokho@alcor.concordia.ca>
Re: Doc translation 
> distribution? I guess that the setting up a separate CVS module 
> per language might be a good idea. People just grab the distribution and docs in
> desired language, and plug the docs in, and here you go. And the docs are almost always
> "out-of-sync" with the distribution anyway :), even the English ones...

Sounds good to me too.

For example, For 7.1 Japanese docs, people could grab
"postgresql-7.1-doc-ja.tar.gz" or whatever...
--
Tatsuo Ishii

Mon, 18 Jun 2001 14:26:00 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: Doc translation 
Tatsuo Ishii wrote:

> Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> Japanese. I hope the work would finish within 1-2 months. My question
> is how the translated docs could be merged into the doc source tree
> once it is done. Maybe doc/ja/src/sgml?
> --
> Tatsuo Ishii
>
> ---------------------------(end of broadcast)---------------------------
> TIP 5: Have you checked our extensive FAQ?
>
> http://www.postgresql.org/users-lounge/docs/faq.html

I think it's better to setup another cvs module, thus maintain
all other languages' docs except English( the English one act as
standard one), and may be we could also maintian a auto-generated
html (or other format if there are no other problems) version on web site
like
techdoc.postgresql.org or some other places for users to browse.
(I think most of people would first go to the main site to search methods
to resolve their problem.)

    regards    laser


Mon, 18 Jun 2001 13:55:05 +0800
He Weiping <laser@zhengmai.com.cn>
Re: Doc translation

----- Original Message ----- 
From: Tatsuo Ishii <t-ishii@sra.co.jp>
Sent: Monday, June 18, 2001 1:26 AM


> > distribution? I guess that the setting up a separate CVS module 
> > per language might be a good idea. People just grab the distribution and docs in
> > desired language, and plug the docs in, and here you go. And the docs are almost always
> > "out-of-sync" with the distribution anyway :), even the English ones...
> 
> Sounds good to me too.
> 
> For example, For 7.1 Japanese docs, people could grab
> "postgresql-7.1-doc-ja.tar.gz" or whatever...

... and also one can put translations not only for the docs in that language CVS module/tarball,
but also for all PG messaging, especially when now PG goes international (see Peter Eisentraut's
post and the follow up thread of June 4 entitled "FYI: status of native language support").

Serguei



Mon, 18 Jun 2001 02:15:28 -0400
"Serguei Mokhov" <sa_mokho@alcor.concordia.ca>
Re: Doc translation 

Tatsuo ... setting up a seperate CVS module for this does sound like a
great idea ... you already have access to the CVS repository, right?  Can
you send me a tar file containing what you have so far, and I'll get it
into CVS and then you'll be able to update that at will?

If we set it up as:

pgsql-docs/ja

we could move the english docs out of pgsql itself and into this module
too, as:

pgsql-docs/en

and any other language too ...

On Mon, 18 Jun 2001, Tatsuo Ishii wrote:

> > Tatsuo Ishii <t-ishii@sra.co.jp> writes:
> > > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> > > Japanese. I hope the work would finish within 1-2 months. My question
> > > is how the translated docs could be merged into the doc source tree
> > > once it is done. Maybe doc/ja/src/sgml?
> >
> > Hmm, *should* they be merged into the source tree, or distributed as
> > a separate tarball?  I'm concerned that they'd always be out of sync
> > with the English docs :-(
>
> Right. However, it would be greater for Japanese users to have the
> Japanese docs in the *official* distribution of PostgreSQL, than
> getting them from other places. What about setting up a new CVS module
> for the Japanese docs, isolated from the source and English doc
> module(pgsql)?
> --
> Tatsuo Ishii
>
> ---------------------------(end of broadcast)---------------------------
> TIP 6: Have you searched our list archives?
>
> http://www.postgresql.org/search.mpl
>

Marc G. Fournier                   ICQ#7615664               IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org           secondary: scrappy@{freebsd|postgresql}.org


Mon, 18 Jun 2001 09:51:32 -0300 (ADT)
The Hermit Hacker <scrappy@hub.org>
Re: Doc translation 
The Hermit Hacker <scrappy@hub.org> writes:
> we could move the english docs out of pgsql itself and into this module
> too, as:
> pgsql-docs/en

Hmm, I'm not sure that that's a good idea; seems it would lose the
coupling between versions of the source and versions of the
documentation.

I quite agree that we should have an official distribution of
non-English documentation if possible.  I'm just wondering how best to
keep track of which set of docs goes with which Postgres release.
Since the English docs are (we hope) kept up to date with the sources,
it seems best to keep those as part of the master CVS tree.

We could imagine keeping non-English docs in the same tree, but that
would require lots of attention to branch management --- for example,
we'd have to be careful to commit these Japanese translations of 7.1
docs into the REL7_1_STABLE branch.  OTOH maybe that's just as true
if there's a separate CVS tree for docs; you'd still want to deal with
a new version per source release.  So maybe a single tree is the right
answer after all.

Anyone have experience with managing this sort of situation under CVS?
Is separate tree or combined tree better?

			regards, tom lane

Mon, 18 Jun 2001 10:42:52 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: Doc translation 
Tatsuo Ishii writes:

> Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> Japanese. I hope the work would finish within 1-2 months. My question
> is how the translated docs could be merged into the doc source tree
> once it is done. Maybe doc/ja/src/sgml?

A while ago I sent a proposal to -docs about how to handle this (basically
doc/src/sgml-<lang>).  No one protested so I was going to implement it; in
fact, I already have in some private branch I have lying around here.  It
even includes some nice side-effects, such as fallback to English for
incomplete translations (so you can look at the result while translation
is still going on) and the integration of the translated SQL reference
pages with the internationalized psql that is currently taking shape.
(Someone else is working on a French translation and has been very anxious
for this to happen, too.)

I would not be in favour of a separate CVS module, for several reasons:
First, it will marginalize the efforts.  I bet there are a sufficient
number of people how would be willing to track documentation upgrades and
keep their language up-to-date.  Second, the build machinery would get
gratuitously complicated and spread around (makefiles, stylesheets,
graphics, URL strings, etc.).  Third, the (undoubtedly real) problem of
keeping these translations up to date would not be helped by this at all.
The maintainers of these translations will simply have to be honest to not
label their documentation set as corresponding to version X.Y when the
content is still based on the original documentation for X.(Y-2).

About "I don't want to download all this stuff I can't read":  We already
have chunked distribution tarballs.  It would be possible to "chunk out"
the files pertaining to a particular language (which would include the
message catalogs as well).

While other open source projects sometimes keep their entire documentation
in a separate cvs module, they generally keep all languages together for
the reasons given above.

-- 
Peter Eisentraut   peter_e@gmx.net   http://funkturm.homeip.net/~peter


Mon, 18 Jun 2001 17:47:34 +0200 (CEST)
Peter Eisentraut <peter_e@gmx.net>
Re: Doc translation
On Mon, 18 Jun 2001, Peter Eisentraut wrote:

> Tatsuo Ishii writes:
>
> > Hi, some PostgreSQL users in Japan have been translating 7.1 docs into
> > Japanese. I hope the work would finish within 1-2 months. My question
> > is how the translated docs could be merged into the doc source tree
> > once it is done. Maybe doc/ja/src/sgml?
>
> A while ago I sent a proposal to -docs about how to handle this (basically
> doc/src/sgml-<lang>).  No one protested so I was going to implement it; in
> fact, I already have in some private branch I have lying around here.  It
> even includes some nice side-effects, such as fallback to English for
> incomplete translations (so you can look at the result while translation
> is still going on) and the integration of the translated SQL reference
> pages with the internationalized psql that is currently taking shape.
> (Someone else is working on a French translation and has been very anxious
> for this to happen, too.)
>
> I would not be in favour of a separate CVS module, for several reasons:
> First, it will marginalize the efforts.  I bet there are a sufficient
> number of people how would be willing to track documentation upgrades and
> keep their language up-to-date.  Second, the build machinery would get
> gratuitously complicated and spread around (makefiles, stylesheets,
> graphics, URL strings, etc.).  Third, the (undoubtedly real) problem of
> keeping these translations up to date would not be helped by this at all.
> The maintainers of these translations will simply have to be honest to not
> label their documentation set as corresponding to version X.Y when the
> content is still based on the original documentation for X.(Y-2).
>
> About "I don't want to download all this stuff I can't read":  We already
> have chunked distribution tarballs.  It would be possible to "chunk out"
> the files pertaining to a particular language (which would include the
> message catalogs as well).
>
> While other open source projects sometimes keep their entire documentation
> in a separate cvs module, they generally keep all languages together for
> the reasons given above.

I definitely have no problems with this ... one comment about Tom's "how
to keep releases together" point though ... that is what Tags/Branches are
for ... as long as we tag all modules, things shouldn't "fall out of sync"
...

But, if you already have a clean method of doign this, please, by all
means, continue ...


Mon, 18 Jun 2001 13:57:12 -0300 (ADT)
The Hermit Hacker <scrappy@hub.org>
Re: Doc translation
Peter Eisentraut <peter_e@gmx.net> writes:
> About "I don't want to download all this stuff I can't read":  We already
> have chunked distribution tarballs.  It would be possible to "chunk out"
> the files pertaining to a particular language

That works for picking up tarballs, but (AFAIK) not for people who
update from the CVS server.  However, seeing that doc/src/sgml is
presently only about a tenth of the total CVS tree bulk, it'll probably
be a long while before the docs form an overwhelming load on CVS users.

Your other arguments seem good to me, so I agree with keeping the
translated documents in the main tree, at least for now.

			regards, tom lane

Mon, 18 Jun 2001 13:05:45 -0400
Tom Lane <tgl@sss.pgh.pa.us>
Re: Doc translation 
> > we could move the english docs out of pgsql itself and into this module
> > too, as:
> > pgsql-docs/en
> Hmm, I'm not sure that that's a good idea; seems it would lose the
> coupling between versions of the source and versions of the
> documentation.

We could (and should, imho) leave the English docs where they are, but
they could be included as a module in the pgsql-docs repository.

> Anyone have experience with managing this sort of situation under CVS?

Yes.

> Is separate tree or combined tree better?

I would suggest defining a "pgsql-docs" module, which might contain the
actual code for non-English docs. We can define a logical module
"pgsql-en" which is included in the *logical* pgsql-docs module (the
latter also contains the *physical* pgsql-docs module).

We've done this on other projects. I can help set up the module
definitions (which are fairly simple when worked out, but perhaps not
trivial to derive from first principles. I'll steal the solution from
work I've done earlier ;)

                      - Thomas

Mon, 18 Jun 2001 22:15:32 +0000
Thomas Lockhart <lockhart@alumni.caltech.edu>
Re: Doc translation