Re: Comments

[Bob DuCharme <bob@udico.com>]

Al B. Snell wrote:

> Quite a few schemas now have provision for comments, which can do stuff
> like import from XHTML or DocBook namespaces. This clearly allows for rich
> comments, unlike <!-- --> comments. Does this mean that <!-- --> comments
> should be discouraged

Features like the W3C schema's annotation element are clearly a step up from
using XML 1.0 (<!-- -->) comments in DTDs, because they'll make it possible
to throw together automated processes to create more useful documentation of
schemas, as with Java's javadoc.

> <!-- --> comments, like <?foo ?> PIs, seem to be one of those bits of XML
> that nobody ever uses. At least, I never see them in the coding examples
> around here. Oh yeah, and that <!NOTATION > thing is a bit of a pariah,
> too...

XML 1.0 comments work in both DTDs and documents, and commenting any kind of
code is always a Good Thing, and people rarely use it as much as they
should. I've seen programming books that encourage you to comment your code
and then don't comment their own code samples. XML 1.0 comments are for
whatever you want them to be for; for example, if I write something that
generates XML output, I usually start that output with an XML comment that
has a time stamp, the name of the generating program, etc. In an XML
document that I'm hand-editing, I'll have a comment that shows the last date
edited andmaybe a to-do list concerning the work I'm doing on it. It's also
a place to store version control information for use by a package like rcs.

Processing instructions and NOTATION declarations are a different story. XML
inherited both from SGML, where PIs were usually used as a way to store
information for some non-SGML application that was going to process the
document. Now that XML support is so ubiquitous and so easy to add to
applications that need it, this becomes less and less relevant.

NOTATION declarations were one of the steps that were necessary to refer to
non-SGML/XML data (e.g. binary files), and while more and alternatives are
showing up now (e.g. the W3C schemas' hexBinary and base64Binary data
types), when the XML spec was being in 1997, unparsed entities were the only
way to do this.

>does anybody use entities to refer to stuff in favour of <foo
> href="..." />, anyway? The latter seems much more convenient, since it
> doesn't require all definitions to be gathered inside the <!DOCTYPE >...

Yes, more convenient. The entities way is more work, but theoretically that
work buys you more data integrity, because the XML parser is required to
resolve the entity reference and make sure that the referenced file is
really there.

Bob DuCharme            www.snee.com/bob             <bob@
snee.com>      see http://www.snee.com/bob/xsltquickly for
info on upcoming "XSLT Quickly" from Manning Publications.