xml-dev - RE: Documentation of DTDs

[Jim Gindling <jimg@digitalthink.com>]

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@Psychology.Nottingham.AC.UK] 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@microstar.com</email>
> >>   </record>
> >>
> >> you should use
> >>
> >>   <record>
> >>     <doc>Record for David Megginson</doc>
> >>     <www>http://home.sprynet.com/sprynet/dmeggins/</www>
> >>     <email>dmeggins@microstar.com</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@ic.ac.uk
> Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/
> To (un)subscribe, mailto:majordomo@ic.ac.uk the following message;
> (un)subscribe 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)


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/
To (un)subscribe, mailto:majordomo@ic.ac.uk the following message;
(un)subscribe 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)