Date: Wed, 25 Aug 1999 11:55:10 +0100 From: Nik Clayton <nik@freebsd.org> To: Motoyuki Konno <motoyuki@snipe.rim.or.jp> Cc: Nik Clayton <nik@freebsd.org>, Tim Vanderhoek <vanderh@ecf.utoronto.ca>, freebsd-doc@freebsd.org Subject: Re: DocBook formatting style? Message-ID: <19990825115510.A96398@kilt.nothing-going-on.org> In-Reply-To: <199908250049.JAA00382@rei.snipe.rim.or.jp>; from Motoyuki Konno on Wed, Aug 25, 1999 at 09:49:35AM %2B0900 References: <19990822200737.A65807@ppp18344.on.bellglobal.com> <19990823141611.A1770@catkin.nothing-going-on.org> <19990823172005.C42397@ppp18344.on.bellglobal.com> <19990824172812.L65430@kilt.nothing-going-on.org> <199908250049.JAA00382@rei.snipe.rim.or.jp>
next in thread | previous in thread | raw e-mail | index | archive | help
Motoyuki,
On Wed, Aug 25, 1999 at 09:49:35AM +0900, Motoyuki Konno wrote:
> > I'm not aware of any such diff, I spent a little bit of time on-line today
> > trying to find one, but without much success. However, if we could find
> > one (or persuade someone with the appropriate skills to write one, possibly
> > even as a post-processor to diff(1)'s output) we could apply it to all the
> > existing documentation, not just the new documentation written by Tim.
>
> When FreeBSD handbook was converted to DocBook, there were so many
> changes like this.
There were? I know I made a few at the beginning, and Jun quickly told me
where I wasn't being careful enough, but after the first few (and there
were something like 60 or so different commits as part of the conversion)
I thought I'd made sure that all the commits were content only. There
was one huge white-space commit at the end of the conversion, but that was
clearly flagged as such in the commit message, so that the translation teams
could ignore it.
> Japanese doc team used GNU wdiff (see ports/textproc/wdiff) to find
> out the real changes, but it is inconvinient....
I'll experiment with wdiff later. Thanks for the pointer.
> *IF* we must refill or reformat the paragraphs of the English version,
I think we must. There are two reasons for this;
1. It makes the file easier to follow. If the file is easier to follow
then it makes it easier to add new documentation, see the structure
of the document, and so on.
2. (Related to 1) It lets the documentation serve as a good example of
DocBook to others. I get several messages a week (which I might start
forwarding on to -doc just for information) praising the FreeBSD
Handbook from people who are starting to learn DocBook, and who have
used the FreeBSD Handbook as a model of good markup and structure.
> the following steps will help the translator teams.
>
> 1. Announce to the -doc list.
> The translated version (Japanese, Chinese, etc.) is not synced
> with the English version very often. So, tranlation teams need
> time to work. In some cases, they need two or three weeks or more.
> For example, most of Japanese doc team members are very busy
> in January, February and March. Some of them must prepare for
> the examination of their university or highschool, and some of
> them must work hard in their office.
>
> 2. Make sure that all tranlated version are synched with the English
> version.
>
> 3. Refill or rewrite the English version.
> No *real* change please. Insert/delete whitespaces and newlines
> only.
>
> 4. Commit the changes in the step 3.
One of us is missing something here, I think, and I'm not sure who.
Suppose you have foo.sgml, at version 1.1, in both English and Japanese.
Now suppose that someone comes along, and makes some content changes to
the English version of foo.sgml. The commit trail looks something like;
1.2 Add a new sentence in the middle of a paragraph. No white space
change, so the new sentence runs over column 76, and the
formatting is generally ugly.
1.3 White space changes only, so that it looks better.
1.4 Adding a completely new paragraph. This can be added with the
correct formatting, because it is separate from all the other
content.
1.5 Adding a new sentence to the new paragraph. Again, because white
space changes are not allowed, this will result in the wrong
formatting.
1.6 White space changes only.
1.7 Deleting an existing paragraph.
OK? Now, the Japanese team come along to translate this. How are you doing
this?
I was expecting that you would do the following;
1. Take a diff between 1.1 and 1.2. This diff should be relatively easy
to follow, because there are no significant white space changes.
Translate, and commit, this new text. The Japanese version can be
committed with the correct formatting, because (AFAIK) we don't have
any translations that are using the Japanese text as the original
source.
2. Ignore revision 1.3 completely.
3. Take a diff between revision 1.3 and 1.4, to get the text of the new
paragraph. Because this is entirely new text you don't need to spend
any effort trying to disentangle it from text that hasn't changed, so
the translation process should be much easier.
4. Take a diff between 1.4 and 1.5, and handle this in the same way you
handled step 1.
5. Ignore 1.6.
[ Actually, this is a bit of a special case. Because of the order of
commits to the English version, you could take diffs between 1.4
and 1.6 to add the new paragraph -- this is unlikely to happen in
real life. ]
6. Duplicate 1.7, which should be easy to do.
That's certainly how I thought the process was working.
However, you make it sound that what you're actually doing is taking a diff
between 1.1 and 1.7, which will include all the white space changes, even
though they were originally entered as separate commits.
If this *is* what you're doing (and I stress that I'm confused now as to
whether it is or not) then I can see why you're having problems.
To requote your points above:
> the following steps will help the translator teams.
>
> 1. Announce to the -doc list.
> The translated version (Japanese, Chinese, etc.) is not synced
> with the English version very often. So, tranlation teams need
> time to work. In some cases, they need two or three weeks or more.
> For example, most of Japanese doc team members are very busy
> in January, February and March. Some of them must prepare for
> the examination of their university or highschool, and some of
> them must work hard in their office.
>
> 2. Make sure that all tranlated version are synched with the English
> version.
>
> 3. Refill or rewrite the English version.
> No *real* change please. Insert/delete whitespaces and newlines
> only.
>
> 4. Commit the changes in the step 3.
We shouldn't need to do this (at least, I don't think we should, unless I'm
missing something seriously fundamental). One of the big advantages of CVS
is that we don't need to agree in advance on a 'synchronisation' point. You
can pick which revision you want to sync to, based on what's convenient to
you. Right?
Comments from members of other translation teams would be useful at this
point.
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
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?19990825115510.A96398>