xml-dev - RE: documenting schemas/DTDs

["DuCharme, Robert" <DuCharmR@moodys.com>]

>Even a schema spec that allowed very rich documentation in each
>declaration would be at best the equivalent of JavaDoc, and that's not
>good enough.  

Not good enough, but a big positive step nevertheless. Javadoc may not do
that much, but who uses a new Java package without ever looking at the
javadoc-generated documentation?

When I write quick and dirty Java code for my own use, I don't bother with
the javadoc @ fields. When I write code for regular use or for others to
see, I feel guilty if I don't fill in those blanks. It's a long way from
literate programming, but it's better than nothing. While simple dedicated
element types in XSDL would not address the basic problems discussed in this
thread, they too would be better than nothing. 

I understand the benefits of disallowing comments inside of attribute
declarations in the transition from SGML to XML, but I really miss the
ability to put a short comment right next to each attribute so that others
looking at the DTD didn't have to wonder whether an explanation of the
attribute list was before the whole list, after the whole list, or omitted.
What made this useful was not the location of the comment but the explicit
relationship that didn't leave the human reader (or automated process)
wondering where to look for a description of a particular attribute.

Years ago, Earl Hood (with dtd2html) and Microstar (with the read-only
version of Near and Far) provided people with free tools that made it easier
to more quickly understand the information stored in a multi-page DTD. These
tools did a lot just by examining the parent/child/sibling relationships
encoded in DTDs, and they could have done more if they knew where to look
for explicit information about each declaration. Come to think of it, they
both provided their own hacks for storing this information; it would be
great if such programs had a standard place to look and didn't have to
resort to hacks. 

Of course, a properly documented system needs more than this, but more would
be a lot harder, and this much would be very useful. 

Bob DuCharme          www.snee.com/bob           <bob@  
snee.com>  "The elements be kind to thee, and make thy
spirits all of comfort!" Anthony and Cleopatra, III ii

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev@ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:majordomo@ic.ac.uk the following message;
unsubscribe xml-dev
To subscribe to the digests, mailto:majordomo@ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa@ic.ac.uk)