Subject: Re: AbiWord DTD
From: sam th (sam@bur-jud-118-039.rh.uchicago.edu)
Date: Sat Feb 26 2000 - 00:25:29 CST
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Fri, 25 Feb 2000, Paul Rohr wrote:
> 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.
Just because pain is so much fun, I think that I could probably also try
tackling the file format document. It doesn't seem that complicated, and
the changes have not been monumental. (that comes soon)
>
> 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.
I guess you are short on time. In the DTD, both on my website, and on the
AbiSource site, p has a props attribute. The DTD on my site
http://bur-jud-118-039.rh.uchicago.edu/abiword/
is the most current. As it's new, it will keep changing, and of course
the version I have will be ahead of what Bob can keep up on the official
page. I currently have two version, one as standard XML,
and one with some strange SGML constructs to make the W3C validator like
it. Use the standard one.
>
> 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.
>
Done.
> 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.
>
Will do.
> 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
>
sam th
sytobinh@uchicago.edu
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.1 (GNU/Linux)
Comment: For info see http://www.gnupg.org
iD8DBQE4t3Hat+kM0Mq9M/wRAvquAKCUYfva9TnDRcRSeUg+qg69o9d8zQCg3jpV
Sah1HNCN5EqroYWLarJvov0=
=BZ7T
-----END PGP SIGNATURE-----
This archive was generated by hypermail 2b25 : Sat Feb 26 2000 - 00:22:23 CST