Date: Tue, 29 Jun 1999 18:30:30 +0900 (JST) From: Kazuo Horikawa <horikawa@ebina.hitachi.co.jp> To: nclayton@lehman.com Cc: motoyuki@snipe.rim.or.jp, kuriyama@sky.rim.or.jp, doc@FreeBSD.ORG, freebsd-translate@ngo.org.uk, jdp@FreeBSD.ORG Subject: tags under doc (Re: Resolution: FDP reorganisation) Message-ID: <19990629183030J.horikawa@ebina.hitachi.co.jp> In-Reply-To: Your message of "Mon, 28 Jun 1999 11:57:43 %2B0100" <19990628115743.G15628@lehman.com> References: <19990628115743.G15628@lehman.com>
next in thread | previous in thread | raw e-mail | index | archive | help
I changed subject, because I think that tagging files under doc
repository is off topic of "FDP reorganisation".
>>> So he asked me to come up with a way that minimises the number of
>>> repository copies that are necessary. Which is what I've done. Obviously,
>>> there's a trade off in terms of the information that can be preserved if
>>> you can't do a repository copy, and what I'm trying to do is strike the
>>> right balance between what we keep and what we lose.
>>
>> Under doc/ja/man, there are following tags:
>> tag=release_3_2_0
>> tag=release_3_1_0
>> tag=release_3_0_0
>> tag=release_2_2_7
>> tag=RELEASE_2_2_6
>> tag=release_2_2_5
>>
>> We can retrieve Japanese online manuals for the RELEASE which the tag
>> represents. It is quite useful to track translation error later. So,
>> we do not want to lose the tags.
> Hmm, that's interesting. How do you use these tags (I'm not being obtuse
> here, I'm genuinely interested).
> We stopped tagging the English documentation to co-incide with the releases
> a while ago, and I didn't think anyone else found it useful either. How
> does this help you do the translations? The other translation teams might
> find this a useful trick as well.
Online manuals are (external) specifications of commands (section
1,6,8), files (section 5), and etc. Some specifications change
between two RELEASEs (say RELEASE-A and RELEASE-B). So people who use
RELEASE-A should refer to RELEASE-A's online manuals. And people who
use RELEASE-B should refer to RELEASE-B's online manuals.
For example, specifications of ppp.8 are updated frequently. So,
people who use ppp on RELEASE-A should refer to the RELEASE-A's ppp.8.
%%
The reason why tag is needed (1)
Basically, we provide Japanese online manuals which are syncing with
English manuals, when RELEASE occurs (say X.Y-RELEASE). CVS tag
release_X_Y_0 is for X.Y-RELEASE.
Someone may say that we can retrieve Japanese manuals if we know
release date of X.Y-RELEASE. But some Japanese online manuals
sometimes happen to be not syncing with English manuals, when
X.Y-RELEASE is released. In that case, when we have finished to sync
with X.Y-RELEASE, cvs tag release_X_Y_0 under doc/ja/man, in order to
users of Japanese manuals can retrieve correct manuals from CVS
repository.
# I pray that new commit for English online manuals (other than
# amendment of typo) will not be made immediately before RELEASE
# occurs every time :-)
%%
The reason why tag is needed (2)
Some people want to use old RELEASE, because they bought FreeBSD
related books or magazines with old RELEASE's CD-ROM. We can serve
package ja-man-doc-X.Y (ports/japanese/man-doc) for them. But people
who dislike package need to retrieve Japanese online manuals from CVS
repository. Tags like release_X_Y_Z under doc/ja/man are necessary
for them.
%%
The reason why tag is needed (3)
I will show our procedure to translate English manuals to Japanese.
Assume that we have RELEASE-A's English manuals and RELEASE-A's
Japanese manuals. Following is the procedure:
(1) retrieve English diffs between RELEASE-A and RELEASE-B (*1).
(2) apply English diffs to RELEASE-A's Japanese manual (and translate
English into Japanese), and get RELEASE-B's Japanese manual.
(*1) RELEASE-B may be SNAPSHOTS.
We receive bug reports that we had forgot to apply some English diffs
to Japanese (e.g. some Japanese paragraphs do not sync with English).
In that case, we should know when we had forfot to apply the diffs.
And we should investigate whether another part of diffs in same
English revision was applied or not. (e.g.
1. Assume we have Japanese foo.1, which is a translation of English
foo.1 whose (English) revision is 1.3.
2. We find that Japanese foo.1 was not applied a part of English
diffs between 1.1 and 1.2.
3. We should retrieve foo.1's English diffs between 1.1 and 1.2,
and investigate whether another part of diffs was applied or not.)
Someone may say we do not need to have tags like release_X_Y_Z. If we
do not have tags, we must have English revision number in EACH
Japanese manuals. But doc/ja/man do not have originial revision
number yet. (doc/ja/handbook and doc/ja/FAQ have "Original revision:"
comment to catch up with origianl (English) revision.)
And I can say that
retrieving English diffs between RELEASE-A and RELEASE-B
and
retrieving Japanese diffs between RELEASE-A and RELEASE-B
is easier than
retrieving English diffs between revision-a and revision-b
and
retrieving Japanese diffs between revision-a's translation and
revision-b's translation.
%%
I showed three reasons why tag is needed for doc/ja/man.
Even if doc/ja/man is cvs remove'd, I wish Attics under doc/ja/man/
will not be removed.
--
Kazuo Horikawa
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990629183030J.horikawa>