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/