SAX: Comments (question 7 of 10)

[David Megginson]

Antony Blakey writes:

 > YES. Think of two tools you can't write without this: transformers and
 > javadoc-style documentation tools. Javadoc is a revolution in
 > documentation, not because it is particularly great in itself, but
 > because it lowers the barrier to documentation production. Also, I often
 > have to transform documents from authors, which then go back into the
 > authoring process. Achieving identity is a requirement in this case.

Thank you very much for your comments.  I'm not certain, however, that
either of these is a strong argument for SAX.

In the first case, SAX is designed to report not the physical
appearance of the document but its logical structure -- it does not
preserve internal entity references in data or attribute value
literals, it does not distinguish defaulted attribute values from
specified ones, it does not preserve the internal DTD subset,
etc. etc.  Even then, SAX will still be useful for doing identity
transforms for a wide range of applications (say, transforming a
document before formatting it), as long as the result of the
transformation does not have to become the master authoring document.

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 at microstar.com</email>
  </record>

you should use

  <record>
    <doc>Record for David Megginson</doc>
    <www>http://home.sprynet.com/sprynet/dmeggins/</www>
    <email>dmeggins at microstar.com</email>
  </record>


All the best,


David

-- 
David Megginson                 ak117 at freenet.carleton.ca
Microstar Software Ltd.         dmeggins at microstar.com
      http://home.sprynet.com/sprynet/dmeggins/

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)