Cart
[Home] [By Thread] [By Date] [Recent Entries]
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@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...)
|
