Date: Thu, 16 Mar 2000 23:41:29 -0800 From: Doug Barton <Doug@gorean.org> To: Sheldon Hearn <sheldonh@uunet.co.za> Cc: doc@FreeBSD.ORG Subject: Re: Proposal re SGML style Message-ID: <38D1E1A9.F17E87F3@gorean.org> References: <56968.953140144@axl.ops.uunet.co.za>
next in thread | previous in thread | raw e-mail | index | archive | help
Sheldon Hearn wrote:
> 1) Each new sentence begins flush against the indented left margin.
> 2) Where a sentence is too long to fit onto an XX-column line (where XX
> seems to be 80 in the status quo), it is broken on sentence
> fragments (clauses). That means on non-terminal punctiation (parens,
> commas, colons, semi-colons, maybe others), prepositions etc.
> 3) Block tags do not share a line with the text they wrap.
These are all sensible suggestions, especially the last one. Breaking
the sentences up into smaller chunks reduces the size of diffs to the
text down the road, makes revision tracking easier, etc. It also makes
it easier for translators, since they get visual cues as to word
grouping (which isn't always obvious to non-native speakers).
I'm not sure that I understand your emphasis on whitespace changes
though, maybe I'm just missing something. I realize it's a pita, but if
you're just making ws changes you really should do a seperate commit.
The temporary pain is well worth it down the road. Think revision
history. Think ten years from now, think twenty years from now when
we're all off doing other things.
I think the suggestion that trying to make any kind of editorial
decisions based on diffs to large text documents isn't likely to be
fruitful is a good one. This is one setting where context diffs actually
work better than unified diffs, but I would never give a final approval
to a document I hadn't read "clean" first. It's just too easy to lose
the flow.
A lot of my programming work involves CGI, much of it with large chunks
of text/HTML embedded. I use similar "guidelines" for my own work and
I've found them useful, FWIW.
Doug
--
"While the future's there for anyone to change, still you know it seems,
it would be easier sometimes to change the past"
- Jackson Browne, "Fountain of Sorrow"
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?38D1E1A9.F17E87F3>