[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: documenting schemas/DTDs
>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@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1 To unsubscribe, mailto:majordomo@i... the following message; unsubscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|