Date: Tue, 24 Aug 1999 17:28:12 +0100 From: Nik Clayton <nik@freebsd.org> To: Tim Vanderhoek <vanderh@ecf.utoronto.ca> Cc: Nik Clayton <nik@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: DocBook formatting style? Message-ID: <19990824172812.L65430@kilt.nothing-going-on.org> In-Reply-To: <19990823172005.C42397@ppp18344.on.bellglobal.com>; from Tim Vanderhoek on Mon, Aug 23, 1999 at 05:20:05PM -0400 References: <19990822200737.A65807@ppp18344.on.bellglobal.com> <19990823141611.A1770@catkin.nothing-going-on.org> <19990823172005.C42397@ppp18344.on.bellglobal.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Aug 23, 1999 at 05:20:05PM -0400, Tim Vanderhoek wrote:
> >> Would you [encourage|discourage] me from writing new hunks of
> >> documentation that use DocBook with a formatting style such that each
> >> new sentence begins on a new line? The idea here is that this would
> >> make future diffs clearer and easier to read. This would directly
> >> make synchronization of translations easier.
I don't suppose anyone knows of a 'diff' that works on a per-sentence
basis, rather than a per-line basis do they?
If I'm understanding this right, the main benefit of this sort of change
is when the English version goes from;
<para>This is the first sentence, less than one line. This is the
second sentence, which will span several lines, in the course of
its long, rambling nature. This is the third sentence, which
can be as long, or short, as necessary.</para>
to
<para>This is the first sentence, less than one line. Second
sentence is here, which will quite definitely span several lines, in
the course of which it might ramble uncontrollably. This is the
third sentence, which can be as long, or short, as necessary.</para>
If you do a diff of this, then obviously all four lines will be shown as
changed, because they have. But to the translators, only the second
sentence has changed, but they still have to read and compare the first
and third sentences, because they appear in the diff(1) output.
If we had a "sentence oriented" diff, it might be persuaded to blank out
the first and third sentences, because although their position in the file
has changed, their content has not.
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.
[ Note: Please don't interpret this as an objection to Tim's idea. I
just want to see if there's another way of tackling this problem that
we haven't thought of yet. ]
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?19990824172812.L65430>