From owner-freebsd-doc Tue Jun 29 2:31:39 1999 Delivered-To: freebsd-doc@freebsd.org Received: from hitpro.hitachi.co.jp (hitpro.hitachi.co.jp [133.145.224.7]) by hub.freebsd.org (Postfix) with ESMTP id B5A1A14CEB; Tue, 29 Jun 1999 02:31:34 -0700 (PDT) (envelope-from horikawa@ebina.hitachi.co.jp) Received: from newton.ebina.hitachi.co.jp by hitpro.hitachi.co.jp (8.9.3/3.7W-hitpro) id SAA18654; Tue, 29 Jun 1999 18:44:08 +0900 (JST) Received: from localhost (horikawa@[172.16.103.145]) by newton.ebina.hitachi.co.jp (8.9.0/3.7W-EBINA) with ESMTP id SAA06314; Tue, 29 Jun 1999 18:30:31 +0900 (JST) 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) In-Reply-To: Your message of "Mon, 28 Jun 1999 11:57:43 +0100" <19990628115743.G15628@lehman.com> References: <19990628115743.G15628@lehman.com> X-Mailer: Mew version 1.93 on Emacs 19.34 / Mule 2.3 (SUETSUMUHANA) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-Id: <19990629183030J.horikawa@ebina.hitachi.co.jp> Date: Tue, 29 Jun 1999 18:30:30 +0900 (JST) From: Kazuo Horikawa X-Dispatcher: imput version 980923(IM101) Lines: 119 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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