dtd documentation

[Vane Lashua]

1. The Earl Hood program is very consistent and widely used. You do maintain
an external file for comments.

2. In XML the ability to embed comments (with -- ... -- in dtd declarations
)  was not included (as in SGML) but you can devised enterprise-standard
ways of embedding the documentation by using

a. plain old comments ( <!-- ... --> ) between declarations

b. or CDATA sections

c. or processing instructions

d. or an entity set

e. or a small set of documentation elements defined at the head of the dtd
and used in the remainder.

None of which is standards-based.
Vane


-----Original Message-----
From: DuCharme, Robert [mailto:DuCharmR at moodys.com]
Sent: Friday, October 22, 1999 11:44 AM
To: 'Martin Kuhn'; xml-dev at ic.ac.uk
Subject: RE: dtd documentation


>I am interested in a tool to document dtd-files. 
>It should have the same functionality as javadoc for java-files or
>doc++ for c++. Where can I get such a tool ?

It's currently a bit ironic that XML doesn't offer built-in markup for
description of its structures the way Java does (the "@" fielded values that
javadoc looks for) since markup to automate documentation generation is part
of the point of XML and especially its parent SGML. The W3C Schema Working
Group has formally stated that fixing this is one of their goals, although
they hadn't addressed it yet in the September Schema Working Draft (see
http://www.w3.org/TR/xmlschema-1/#doc).

That being said, check out the dtd2html script that is part of Earl Hood's
perlSGML utilities at http://www.oac.uci.edu/indiv/ehood/perlSGML.html. It
generates a series of HTML files to document the relationships within a DTD,
and in my quick tests it works fine for XML as well as SGML. It also has its
own notation for adding DTD comments that will show up in the generated
documentation. 

(perlSGML also offers a very handy dtddiff program. I used it to generate
the xml-dev posting showing the differences between the May and September
drafts of Part 1 of the Schema Working Draft. See
http://www.lists.ic.ac.uk/hypermail/xml-dev/xml-dev-Sep-1999/1241.html for
some sample dtddiff output.)

Bob DuCharme       www.snee.com/bob       <bob@  
snee.com>  see www.snee.com/bob/xmlann for "XML:
The Annotated Specification" from Prentice Hall.

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/ and on CD-ROM/ISBN
981-02-3594-1
To unsubscribe, mailto:majordomo at ic.ac.uk the following message;
unsubscribe 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)

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/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:majordomo at ic.ac.uk the following message;
unsubscribe 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)