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

RE: Documentation of DTDs

  • From: Jim Gindling <jimg@d...>
  • To: "xml-dev@i..." <xml-dev@i...>
  • Date: Fri, 16 Jan 1998 08:50:38 -0800

documentation methods
XMLers,

> - Is there a need for a standard on documentation for XML DTDs?

Definitely yes!  Having programmed in Java for over a year now, and having 
previously programmed in C++ for quite awhile, I can attest to the value of 
having a JavaDoc type mechanism, which is only possible by standardizing the 
documentation style.  It is easy to use, and reading through the JavaDoc output 
during design-reviews and the like makes life much easier than reading through 
the code itself.

> - If so, is the separate-documentation method better than the
> documentation-in-DTD method?

Although I am still an XML newbie, I strongly recommend using the 
documentation-in-DTD method, again based on my programming experience.  The 
closer the documentation is to thing being documented, the more likely it is to 
be up-to-date.  One of the nice features of Java (IMHO) is that there is no 
separate interface file.  In C++, classes are declared in header files, and 
defined in source files.  Since the declaration is not very 'close' to the 
definition, its comments are frequently out-of-date.  Even when the declaration 
and definition are in the same file, the further away the comments are from the 
code, the more likely they are to be out-of-date.  For example, class comments 
are more likely to be obsolete than method comments, which are more likely to 
be obsolete than code-fragment comments.

Thanks for your time!


Jim

On Thursday, January 15, 1998 3:33 AM, Jeni Tennison 
[SMTP:jft@P...] wrote:
> During the discussion on including comments in SAX, Antony Blakey wrote:
> >David Megginson wrote:
> >> In the second case, I think that it would be a very bad idea to
> >> implement a JavaDoc-type facility using XML comments.  JavaDoc has to
> >> use comments because it is not possible to extend Java syntax; XML
> >> allows you to define your own grammar, so the documentation can be
> >> part of the fundamental element structure.  For example, instead of
> >>
> >>   <!-- ** Record for David Megginson ** -->
> >>   <record>
> >>     <www>http://home.sprynet.com/sprynet/dmeggins/</www>
> >>     <email>dmeggins@m...</email>
> >>   </record>
> >>
> >> you should use
> >>
> >>   <record>
> >>     <doc>Record for David Megginson</doc>
> >>     <www>http://home.sprynet.com/sprynet/dmeggins/</www>
> >>     <email>dmeggins@m...</email>
> >>   </record>
> >
> >I agree, but your example implies that my comments were about the data,
> >rather than about the structure itself - I guess I should have pointed
> >out that I'm interested in comments in the DTD, so that the DTD can be
> >documented automatically. This is more like javadoc/idldoc. I'd love an
> >xmldoc tool. I'm guessing now that SAX doesn't give me DTD events.
>
> 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.
>
> javadoc [1] and dtd2html [2] utilise different methods of supplying
> documentation for their respective 'code'.  javadoc has the programmer
> write documentation within the code, whereas dtd2html has the DTD author
> write a separate file containing the documentation.  The problem with using
> the javadoc method is that it would add a lot of gumph to a DTD that the
> majority of applications (validators, viewers etc.) couldn't care less
> about.  The problem with the dtd2html method is that the documentation
> isn't immediately *there* for someone editing the DTD.  Of the two, I think
> the dtd2html method probably suits XML better (designed, as it is, for
> SGML, that isn't too surprising).  (BTW, before anyone asks, the reason
> dtd2html isn't what I have in mind is because of the
> application-accessibility of the documentation as described above.)
>
> So, the solution I'm (tentatively) suggesting is that XML DTDs point to XML
> documents which contain documentation on the DTD.  There are two parts to
> this, then: firstly, how does the DTD point to its documentation?
> Secondly, how is the documentation structured?
>
> Well, I *think* (and please forgive me if I'm wrong) the answer to the
> first part is to have a processing instruction within a DTD which points to
> the documentation.  Something like:
>
> <?XDEV:documentation SYSTEM "myml.dtddml" >
>
> [Should it just contain a (relative) URL?  Is there anything else it needs
> to contain?  Should its format be: <?XDEV:documentation url="myml.dtdml" >?]
>
> The DTD Documentation Markup Language (hence .dtddml ;) document referenced
> would probably borrow heavily from the format of the documentation for
> dtd2html and also from DTDs of DTDs or groves or whatever they're called -
> Peter MR, you've done one, haven't you?  I'm very willing and probably able
> to do such a DTD, but I thought I'd try to get people's opinions on this
> whole documentation business before doing so.
>
> So:
> - Is there a need for a standard on documentation for XML DTDs?
> - If so, is the separate-documentation method better than the
> documentation-in-DTD method?
> - If so, how should the documentation document be referenced from the DTD?
> Are there any ideas/suggestions/requirements for what the documentation
> should contain or what the documentation DTD should look like?
>
> Thanks for your comments in advance,
>
> Jeni
>
> [1] http://java.sun.com/products/jdk/1.1/docs/tooldocs/win32/javadoc.html
> [2] http://www.oac.uci.edu/indiv/ehood/perlSGML/doc/html/dtd2html.html
>
> Jenifer Tennison
> Department of Psychology, University of Nottingham
> University Park, Nottingham NG7 2RD, UK
> tel: +44 (0) 115 951 5151 x8352
> fax: +44 (0) 115 951 5324
> url: http://www.psychology.nottingham.ac.uk/staff/Jenifer.Tennison/
>
>
>
> 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...)


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...)


PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
 

Stylus Studio has published XML-DEV in RSS and ATOM formats, enabling users to easily subcribe to the list from their preferred news reader application.


Stylus Studio Sponsored Links are added links designed to provide related and additional information to the visitors of this website. they were not included by the author in the initial post. To view the content without the Sponsor Links please click here.

Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.