[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

RE: dtd documentation

• From: Vane Lashua <vlashua@R...>
• To: xml-dev@i...
• Date: Fri, 22 Oct 1999 13:43:07 -0400

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@m...]
Sent: Friday, October 22, 1999 11:44 AM
To: 'Martin Kuhn'; xml-dev@i...
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@i...
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN
981-02-3594-1
To unsubscribe, mailto:majordomo@i... the following message;
unsubscribe xml-dev
To subscribe to the digests, mailto:majordomo@i... the following
message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa@i...)

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/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:majordomo@i... the following message;
unsubscribe xml-dev
To subscribe to the digests, mailto:majordomo@i... the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa@i...)

• Prev by Date: RE: "Multiple" Namespaces? (but NOT for HTML)
• Next by Date: RE: "Multiple" Namespaces? (but NOT for HTML)
• Previous by thread: RE: dtd documentation
• Next by thread: Expat for SUN SOLARIS
• Index(es):
  • Date
  • Thread