Subject: Re: AbiWord DTD
From: Paul Rohr (paul@abisource.com)
Date: Tue Feb 22 2000 - 18:37:37 CST
Yikes, it's a DTD! Guess that's what I get for taking the holiday weekend
off, huh?
To be honest, I have *very* mixed emotions about seeing this. DTDs just
look so darned official, you know? It makes people think they know exactly
what does and doesn't belong in our file format. But they're wrong.
As one of the designated file format enforcers, I've gleefully taken
advantage of the fact that nobody thinks they understand our file format
well enough to write a DTD. You *have* to look at the source of our product
to know what the file format currently is.
IMHO, this lack of documentation is a Good Thing.
A. No documentation is better than wrong documentation.
--------------------------------------------------------
This may sound like heresy, but don't get me wrong. Documentation is good.
I *like* documentation -- provided it's accurate.
However, there have been far too many times in my life that I've gotten
burned by misleading or outdated documentation, particularly when I didn't
*know* how flawed it was. I'd much rather do without documentation than get
confused by something that's inaccurate.
B. The file format is currently in flux.
-----------------------------------------
It's been quite a while now since there were any changes to the file format,
but that's about to change, in a big way.
For example, Luke has submitted a patch with file format changes to make
lists (mostly) work, but he hasn't yet gotten any serious feedback from
anyone else. (I don't know whether anyone else plans to comment on it, but
it's definitely at or near the top of my list.)
Likewise, we know that empty field tags are going to be replaced with a
barrage of new container-style markup. Here again, there's a proposal on
the table which hasn't gotten any serious feedback yet.
Even worse, it's pretty clear to me that these two proposals will interact
in ways which probably affect the file format, too.
C. Which version of the file format are we documenting here?
-------------------------------------------------------------
It looks like this DTD probably includes Luke's proposed changes, but omits
a number of other features of the file format which do exist.
D. Any DTD which doesn't get used is probably wrong.
-----------------------------------------------------
The main use for DTDs is to determine whether an XML/SGML document is
"valid" or not. However, we do not and will not ever be using DTDs in this
way for the AbiWord file format. A valid AbiWord document is one that we
read. Period.
If there's ever a conflict between a DTD and our behavior, then the DTD is
wrong. That's not a characteristic people usually expect of DTDs. They
want it to be the other way around, but it's not.
bottom line
-----------
If we never publish a DTD for our file format, I wouldn't shed any tears.
It's not needed for XML compliance, and I think having one sets false
expectations among hard-core XML bigots.
However, I will grudgingly admit that a DTD would make a nice formal piece
of read-only documentation which helps describe (in a more formal sense) how
our file format works. In that vein, if people really really want to have
one, I won't get in the way, provided that:
- we wait until the file format *is* stable,
- we have someone committed to maintaining its accuracy, AND
- we clearly state that the DTD is descriptive, *not* normative
We are not at that point now, so my assertion is that publishing the DTD now
does far more more harm than good.
Paul,
designated curmudgeon
This archive was generated by hypermail 2b25 : Tue Feb 22 2000 - 18:32:09 CST