Documentation for DTDs (was HDML DTD)

In message <199706220008.RAA02703@boethius.eng.sun.com> Jon.Bosak@Eng.Sun.COM (Jon Bosak) writes:
[... message about HDML ...]
> (king@uplanet.com).  DO NOT SEND YOUR COMMENTS OR SUGGESTIONS ABOUT
> HDML TO THE W3C-SGML-WG LIST.

This is NOT a comment on HDML per se, but on the issue of 
documentation/behaviour, which I mentioned recently and which is exemplified
by this DTD:

[...]
> 
> <!ELEMENT ce		- O (#PCDATA)>
> <!ATTLIST ce
> 		value	CDATA #IMPLIED
>         task	NMTOKEN	go 
[...]

My concern is that CE has no associated semantics formally bound to it
in either machine- or human-readable form. So if I get an HDML document
I have no way of understanding it.  Comments are of marginal help because they
are not attached to any specific node in the DTD, and are usually not 
transmitted to the application.  General purpose tools such as JUMBO will 
get a parsed document, possibly also the DTD, but the best they can do is 
display a CE element as a 'CE icon'.  Personally I use tools like Earl Hood's 
excellent dtd2html to describe my DTDs, where each element has a file of the 
form ce.desc. The binding is relatively loose (i.e. I have to reprocess the 
*.html to extract anything that is further machine-readable.)

My personal view is that DTDs in XML ought to be supported in this way and
that this is at least as important as the other DTD things we have been 
discussing.  A simple way would be to have a PI for each ELEMENT such as:

<?XML-DTDDOC element="CE" url="hdmldoc.xml#ID(CE)">

which would point to a section of a file containing the documentation for this
DTD.

This is, of course, possible today but the blessing of the ERB would be 
helpful, epsecially if the reserved <?XML-* PI was to be used.  It also
implies a DTD for XML documentation (perhaps part of a more general DTD for
XML DTDs).  This would be extremely useful, because it means that generic
processors such as JUMBO could provide HELP for the user. Thus a 'CE?' icon
could display - in XML-compliant manner - the associated documentation for
the CE element.

An intimate way of binding this to the DTD (or subset) would be valuable.
DTDs written in XML would be a good way, but I gather this was discussed
before my time on the WG, and I accept the party line.  However a DTD for 
DTDs is perfectly allowable.

IMO the additiona of useful documentation to DTDs in a formal manner would be
the single most valuable thing that could be done to 'sell' the DTD concept
to the new users of XML.  A complex DTD, with or without PEs, with no 
machine-readable documentation is a turn-off.

	P.

-- 
Peter Murray-Rust, domestic net connection
Virtual School of Molecular Sciences
http://www.vsms.nottingham.ac.uk/

Received on Sunday, 22 June 1997 09:43:18 UTC