Date: Thu, 26 Aug 1999 11:14:47 +0100 From: Nik Clayton <nik@freebsd.org> To: Tim Vanderhoek <vanderh@ecf.utoronto.ca> Cc: Nik Clayton <nik@freebsd.org>, Motoyuki Konno <motoyuki@snipe.rim.or.jp>, freebsd-doc@freebsd.org Subject: Re: DocBook formatting style? Message-ID: <19990826111447.C66300@kilt.nothing-going-on.org> In-Reply-To: <19990825194348.G18970@ppp18415.on.bellglobal.com>; from Tim Vanderhoek on Wed, Aug 25, 1999 at 07:43:48PM -0400 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> <19990825115510.A96398@kilt.nothing-going-on.org> <19990825194348.G18970@ppp18415.on.bellglobal.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Aug 25, 1999 at 07:43:48PM -0400, Tim Vanderhoek wrote:
> On Wed, Aug 25, 1999 at 11:55:10AM +0100, Nik Clayton wrote:
> >
> > 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.
>
> Are you objecting to my suggestion with this?
I don't think I am.
To use one of the first paragraphs of en*/books/handbook/ports/chapter.sgml
as an example, you're thinking of turning
<para>For all the hype about open standards, getting a program to work on
different versions of Unix in the real world can be a tedious and tricky
business, as anyone who has tried it will know. You may be lucky enough
to find that the program you want will compile cleanly on your system,
install itself in all the right places and run flawlessly “out of
the box”, but this is unfortunately rather rare. With most
programs, you will find yourself doing a fair bit of head-scratching, and
there are quite a few programs that will result in premature greying, or
even chronic alopecia...</para>
into
<para>For all the hype about open standards, getting a program to work on
different versions of Unix in the real world can be a tedious and tricky
business, as anyone who has tried it will know.
You may be lucky enough to find that the program you want will compile
cleanly on your system, install itself in all the right places and run
flawlessly “out of the box”, but this is unfortunately
rather rare.
With most programs, you will find yourself doing a fair bit of
head-scratching, and there are quite a few programs that will result
in premature greying, or even chronic alopecia...</para>
yes? I don't object to this (particularly as you say your planning on
confining it to your own submissions) but I do note:
1. It removes some of the functionality of my favourite editor (*sniff*).
2. It reads oddly. It might just be my brain, but I can't read the
altered one as a 'smooth' paragraph. The line breaks make it seem
much more disjoint, which makes it harder to read it when proofing,
or rewording.
3. I'm not convinced it actually makes things markedly easier for the
translators, when compared to our current scheme of commiting content
changes and white space changes in separate commits.
But, these aren't objections, just notes. I don't see any reason why we
can't try it out on some of your documentation for a few months, and, if
it works out well, whistle up some Emacs Lisp, or Perl, or something, to
automagically make the other English docs do this.
I think Foxfair (I think it was, anyway) made an interesting suggestion
which was to not bother doing this in the repository copies of the files,
but to have some tool which could post-process DocBook documents so they
looked like this. The translators would then check out the before and
after versions of the document they're translating, run both copies through
this tool (to get an 'easier to translate and/or see the diffs' version),
and then base their translations on that. This then gives us the best of
both worlds.
Have I understood your proposal properly?
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?19990826111447.C66300>