Date: Wed, 25 Aug 1999 22:00:34 +0100 From: Nik Clayton <nik@freebsd.org> To: Satoshi - Ports Wraith - Asami <asami@freebsd.org> Cc: Nik Clayton <nik@freebsd.org>, Tim Vanderhoek <vanderh@ecf.utoronto.ca>, freebsd-doc@freebsd.org Subject: Re: DocBook formatting style? Message-ID: <19990825220034.A45145@kilt.nothing-going-on.org> In-Reply-To: <vqciu64cdj8.fsf@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Wed, Aug 25, 1999 at 04:20:27AM -0700 References: <19990822200737.A65807@ppp18344.on.bellglobal.com> <19990823141611.A1770@catkin.nothing-going-on.org> <19990823172005.C42397@ppp18344.on.bellglobal.com> <vqcvha54hpl.fsf@silvia.hip.berkeley.edu> <19990824171937.K65430@kilt.nothing-going-on.org> <vqciu64cdj8.fsf@silvia.hip.berkeley.edu>
index | next in thread | previous in thread | raw e-mail
On Wed, Aug 25, 1999 at 04:20:27AM -0700, Satoshi - Ports Wraith - Asami wrote:
> * From: Nik Clayton <nik@freebsd.org>
>
> * About the only exception to this is if the changes can be carried out
> * completely mechanically, and the mechanism to do so is clearly described
> * in the commit message (or supporting e-mail / README file, or equivalent).
>
> The problem is that you can't separate the real change with formatting
> change with diff.
Yes, you can, but if, and only if, the original committer was considerate
enough to ensure that they didn't commit any white space changes.
Right? And we're trying to ensure that every FDP committer follows this
rule.
As an example, look at the English handbook, in the ppp-and-slip/chapter.sgml
file, revisions 1.10 and 1.11. You can see in 1.11 that the committer
(jkoshy in this case) hasn't rewrapped the lines after he's made changes
(with one exception, which is presumably human error).
Or revisions 1.14, 1.15, and 1.16 of the eresources/chapter.sgml file.
1.14 is the before the change, and the diff from 1.15 to 1.16 is white
space only (and is noted as such in the log) and can be ignored by the
translation teams.
Or revisions 1.32, 1.33, and 1.34 of ports/chapter.sgml, where the same
thing happens.
The idea is that we never commit formatting changes and content changes in
the same commit. They're always separate.
Unless the content and formatting change can be completely automated.
For example, the conversion of the FAQ from LinuxDoc to DocBook can be
automated, and described. This conversion involves some content changes
(elements changing names) and also some white space changes, where elements
appear on new lines, and the like).
But because it can be completely described, you can safely commit the
content and the whitespace changes at the same time. And I know that it
can be automated without worrying about the content of the translation,
because I followed my own instructions to convert the Chinese FAQ from
LinuxDoc to DocBook, without understanding the language it was written
in.
Yes?
If that doesn't make sense (or does make sense but you still think I'm
wrong) can you point me at an example in the doc/en* tree of a content
commit that also included a whitespace commit? I don't doubt that they
exist (as I say, in the early stages of the DocBook conversion I
inadvertently made a few myself) but they should be rare, and getting rarer.
And, always, if a particular commit is causing the Japanese team (or any
of the translation teams) problems, please mention it to the committer
concerned, and, if necessary, post a reminder to -doc. It certainly doesn't
hurt for us English speaking committers to be reminded every once in a while
to make things easier for the translation teams.
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
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990825220034.A45145>