Documentation of DTDs

[Eve L. Maler]

At 06:33 AM 1/15/98 -0500, Jeni Tennison wrote:
...
>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.
...

Documentation for DTDs isn't just a good idea, it's the law! :-)  That is,
at least in full SGML, a "DTD" is actually supposed to consist of both the
formal part (the markup declarations) and the documentation that explains
everything.

I believe that the best way to do integrated DTD documentation is to --
surprise! -- write an XML document that contains (and whose structure
reveals) information about both the formal and the informal parts of the
language being defined.  In other words, I would want an XML-based schema
language that provides hooks for places to put descriptions.

Several such DTD-for-DTDs-and-their-documentation have been written; the
XML-Data proposal is the latest public one.  It has some features for
embedded documentation/description, but it could be taken even further.

	Eve

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)