xml-dev - Documentation of DTDs

[Jeni Tennison <jft@Psychology.Nottingham.AC.UK>]

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)