Subject: Re: AbiWord DTD
From: Paul Rohr (paul@abisource.com)
Date: Fri Feb 25 2000 - 20:56:08 CST
Thanks for the reminders about how useful an *accurate* DTD can be as
documentation.
I'm certainly not opposed to documenting the file format. I'm just short on
time right now to do it myself, and I want to be sure that people know the
quality of any attempts at documenting it in any way (DTD or not).
If people prefer to do this in the form of a DTD instead of (or in addition
to) finishing Jeff's existing description in abi/docs, that's fine too.
So, here's a suggestion for how to resolve the debate:
1. Fix the DTD. I'm still short on time to review this, but from a quick
glance there seem to be a lot of bugs here still. For example, I'm pretty
sure the content model for paragraphs is busted. Also, the fact that P
PROPS is missing is a big giveaway.
2. Check it into the abi/docs portion of the tree (once it's been fixed).
This will help emphasize its status as (non-normative) documentation.
3. Make it self-documenting. For example, add comments to the top of the
DTD file itself which explain that it's intended to be descriptive, not
normative.
4. Add more comments. For example, the DTDs for HTML do a pretty nice job
of explaining what and how each group of attributes gets used.
bottom line
-----------
Since Sam's volunteered to maintain the puppy, I think we'll be fine as soon
as we get a more accurate one.
Paul,
ex-curmudgeon
This archive was generated by hypermail 2b25 : Fri Feb 25 2000 - 20:50:38 CST