[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: Documentation of DTDs
XMLers, > - Is there a need for a standard on documentation for XML DTDs? Definitely yes! Having programmed in Java for over a year now, and having previously programmed in C++ for quite awhile, I can attest to the value of having a JavaDoc type mechanism, which is only possible by standardizing the documentation style. It is easy to use, and reading through the JavaDoc output during design-reviews and the like makes life much easier than reading through the code itself. > - If so, is the separate-documentation method better than the > documentation-in-DTD method? Although I am still an XML newbie, I strongly recommend using the documentation-in-DTD method, again based on my programming experience. The closer the documentation is to thing being documented, the more likely it is to be up-to-date. One of the nice features of Java (IMHO) is that there is no separate interface file. In C++, classes are declared in header files, and defined in source files. Since the declaration is not very 'close' to the definition, its comments are frequently out-of-date. Even when the declaration and definition are in the same file, the further away the comments are from the code, the more likely they are to be out-of-date. For example, class comments are more likely to be obsolete than method comments, which are more likely to be obsolete than code-fragment comments. Thanks for your time! Jim On Thursday, January 15, 1998 3:33 AM, Jeni Tennison [SMTP:jft@P...] wrote: > During the discussion on including comments in SAX, Antony Blakey wrote: > >David Megginson wrote: > >> In the second case, I think that it would be a very bad idea to > >> implement a JavaDoc-type facility using XML comments. JavaDoc has to > >> use comments because it is not possible to extend Java syntax; XML > >> allows you to define your own grammar, so the documentation can be > >> part of the fundamental element structure. For example, instead of > >> > >> <!-- ** Record for David Megginson ** --> > >> <record> > >> <www>http://home.sprynet.com/sprynet/dmeggins/</www> > >> <email>dmeggins@m...</email> > >> </record> > >> > >> you should use > >> > >> <record> > >> <doc>Record for David Megginson</doc> > >> <www>http://home.sprynet.com/sprynet/dmeggins/</www> > >> <email>dmeggins@m...</email> > >> </record> > > > >I agree, but your example implies that my comments were about the data, > >rather than about the structure itself - I guess I should have pointed > >out that I'm interested in comments in the DTD, so that the DTD can be > >documented automatically. This is more like javadoc/idldoc. I'd love an > >xmldoc tool. I'm guessing now that SAX doesn't give me DTD events. > > I was thinking about this last night. If there is going to be a means to > have documentation within DTDs (and I think there should be), it would be a > very good idea to decide on a standard format for that documentation, so > that both authors of DTDs and XML application programmers can use it. > > I can see two good reasons for having documentation within a DTD. The > first is for automatic generation of documentation (as XML documents, > obviously) in a similar way to javadoc, as mentioned by Antony Blakey. The > second is for automatic dialog or pop-up help generation in XML editors. > The first need could be satisfied by authors of DTDs writing separate > documentation for them: the second need could not. Note also that the > second need means that the documentation should be well structured and > available online in such a way that an application receiving a DTD can get > its documentation too - this means that tools which do a one-off generation > of documentation wouldn't cut it. > > javadoc [1] and dtd2html [2] utilise different methods of supplying > documentation for their respective 'code'. javadoc has the programmer > write documentation within the code, whereas dtd2html has the DTD author > write a separate file containing the documentation. The problem with using > the javadoc method is that it would add a lot of gumph to a DTD that the > majority of applications (validators, viewers etc.) couldn't care less > about. The problem with the dtd2html method is that the documentation > isn't immediately *there* for someone editing the DTD. Of the two, I think > the dtd2html method probably suits XML better (designed, as it is, for > SGML, that isn't too surprising). (BTW, before anyone asks, the reason > dtd2html isn't what I have in mind is because of the > application-accessibility of the documentation as described above.) > > So, the solution I'm (tentatively) suggesting is that XML DTDs point to XML > documents which contain documentation on the DTD. There are two parts to > this, then: firstly, how does the DTD point to its documentation? > Secondly, how is the documentation structured? > > Well, I *think* (and please forgive me if I'm wrong) the answer to the > first part is to have a processing instruction within a DTD which points to > the documentation. Something like: > > <?XDEV:documentation SYSTEM "myml.dtddml" > > > [Should it just contain a (relative) URL? Is there anything else it needs > to contain? Should its format be: <?XDEV:documentation url="myml.dtdml" >?] > > The DTD Documentation Markup Language (hence .dtddml ;) document referenced > would probably borrow heavily from the format of the documentation for > dtd2html and also from DTDs of DTDs or groves or whatever they're called - > Peter MR, you've done one, haven't you? I'm very willing and probably able > to do such a DTD, but I thought I'd try to get people's opinions on this > whole documentation business before doing so. > > So: > - Is there a need for a standard on documentation for XML DTDs? > - If so, is the separate-documentation method better than the > documentation-in-DTD method? > - If so, how should the documentation document be referenced from the DTD? > Are there any ideas/suggestions/requirements for what the documentation > should contain or what the documentation DTD should look like? > > Thanks for your comments in advance, > > Jeni > > [1] http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javadoc.html > [2] http://www.oac.uci.edu/indiv/ehood/perlSGML/doc/html/dtd2html.html > > Jenifer Tennison > Department of Psychology, University of Nottingham > University Park, Nottingham NG7 2RD, UK > tel: +44 (0) 115 951 5151 x8352 > fax: +44 (0) 115 951 5324 > url: http://www.psychology.nottingham.ac.uk/staff/Jenifer.Tennison/ > > > > 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/ > To (un)subscribe, mailto:majordomo@i... the following message; > (un)subscribe xml-dev > To subscribe to the digests, mailto:majordomo@i... the following message; > subscribe xml-dev-digest > List coordinator, Henry Rzepa (mailto:rzepa@i...) 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/ To (un)subscribe, mailto:majordomo@i... the following message; (un)subscribe 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
|