DDML Documentation Capabilities

[david at megginson.com]

First, congratulations to everyone on the publication of DDML as a W3C 
NOTE.

I've started reading through DDML (I looked at XSchema early on, but
haven't had time to follow the work), and I'd like to comment not on
the schema part, but on the documentation part.

I think that the DDML:Doc element, while useful, is insufficient for
documentation.  There is a certain structural hierarchy of
documentation that DTD designers and documentation people almost
invariably end up using:

1. The element type name
2. A full title
3. A short description
4. A long description

For example:

1. a
2. Anchor
3. The start and/or end point of a hyperlink.
4. The HTML <a> element allows users to... [blah blah blah]

DDML covers (1) with the 'Name' attribute, and (4) with the DDML:Doc
element, but it completely misses capturing the structure of (2) and
(3) in any standard way.  What we need to do is something like this:

<ElementDef Name="doc">
<Title>Document</Title>
<Desc>The root element of a document.</Desc>
<DDML:Doc>....</DDML:Doc>
<Model>
<Seq>
<Ref Element="front"/>
<Ref Element="body"/>
</Seq>
</Model>
</ElementDef>

You might even want to get fancy and allow <Title>, <Desc>, and
<DDML:Doc> to be repeated with different values for xml:lang.
Obviously, the information for (2) and (3) can be included in
<DDML:Doc>, but since it has no standard structure, it is difficult to
automatically generate menus, help-files, etc. for DTDs from a DDML
description.


All the best,


David

-- 
David Megginson                 david at megginson.com
           http://www.megginson.com/

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)