Date: Wed, 15 Mar 2000 16:36:05 -0800 From: "Sean Kelly" <kelly@ad1440.net> To: "Sheldon Hearn" <sheldonh@uunet.co.za>, <doc@FreeBSD.ORG> Subject: Re: Proposal re SGML style Message-ID: <00d101bf8edf$9ddbc460$24d39580@jpl.nasa.gov> References: <56968.953140144@axl.ops.uunet.co.za>
next in thread | previous in thread | raw e-mail | index | archive | help
> This message is long. Please don't read it now if you don't have time > to think about what I'm saying before shooting me down. :-) Ready ... aim ... :-) Seriously, I haven't written for the FreeBSD project in some time, so whatever I say can't carry much weight. However, just let me play advocatus diaboli for a moment. Strict formatting for computer languages, being what they are (type 1 grammars in Chomsky's hierarchy, if I recall correctly), makes sense, since they follow a regular, coherent pattern of production. Imposing a mathematical style on the physical formatting of a C program, for example, is a no-brainer. A uniform style used across a project also makes using tools like diff possible. If you've got revisions to a function, you need only examine the differences to determine that they compute the new intended function, or fix the bug, or what-have-you. Natural languages are quite a bit more complex than computer languages, naturally. From implicit subjunctive comparisons to puns, there's a lot more that's communicated than what's actually written. Imposing a mathematical style on the physical formatting might cause writers to focus more on inserting newlines on phrase boundaries, instead of on *communicating well*. Using a tool like diff makes far less sense. Professional editors would probably be aghast at reading a revision to a chapter by its differences from the previous version, since the differences lack the context of the chapter as a whole. There's a personality to a chapter---an ethos. Even if you had a very bright diff tool that could work on such material, you'd only gain glimpses of that personality. When I review chapters for O'Reilly, they give me entire chapters to read, not just the differences from the last time 'round. I'd say that if you've got 2000 lines of diffs, then the whole flavor of the chapter is going to be different. And in that case it's better to apply the diffs and read the new version of the chapter from start to finish---looking at technical accuracy, consistency, flow, grammar, spelling, and personality---rather than looking at the context-free glimpes of "before versus after." Whether the chapter "computes its intended function" is a subjective measure anyway. But you'll better gauge all at once. Take care, --Sean 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?00d101bf8edf$9ddbc460$24d39580>