This chapter is from the book
This chapter is from the book
This chapter is from the book
Comments
A comment is text, inserted into the document tree, that is not part of the XML content itself. Comments are meaningful only to humans (when they are meaningful at all). They are typically used by the publisher of an XML document to help other developers extract the most meaning from the document.
Comments are most valuable during the software development phase. During normal XML data exchange they are disregarded.
While most editors preserve comments, not all software will. Browsers, such as IE5, usually preserve both the comment's text and its relationship to the hierarchy of the XML object, allowing comments to be carefully placed where the context is significant.
Flash Context
The Flash XML parser discards incoming comments. This is perfectly legitimate—comments are meant to be read not by applications but only by humans. They are not available to the ActionScript application except by using heroic measures (i.e., writing our own mini-parser).
In fact, older releases of Flash (5.0) cannot properly parse comments. When Flash reads in XML with comments, the entire object model is corrupted.
You are strongly urged to avoid comments in the XML that will feed into your Flash application until it has been tested thoroughly.
ActionScript cannot generate comments in the XML object it outputs. It would be possible to insert comments only "manually" by serializing the XML (generating an XML string from the XML object) and then using string operations to insert or concatenate the comment. This extreme effort should be warranted by some extreme requirement.
If it were necessary to preserve comments in and out of our ActionScript, we would be better off inventing a <COMMENT> element. This would be a normal XML element containing normal text data. It would pass through parsers and code generators in place and intact. It would be incumbent on us, of course, to code our applications to treat it appropriately, and indeed it could be treated quite intelligently.
Syntax
The comment is introduced by the string "<!--" and terminated by "-->". Between these can go any text except for two consecutive dashes (this restriction was introduced for compatibilty with legacy of SGML):
<!--This is commentary.-->
Rules
Each comment must have
the four-character string <!--
any text
the character triplet -->
It may have
the & and < characters, forbidden in character data.
It may not have
a pair of consecutive hyphens (--)
Examples of Comments
|
<!-- this is a message from me.--> |
Normal usage |
|
<phone>555-0308 <!--use dash--></phone> |
Comments can be inside an element. |
|
<town>Kolumbis<!--sic-->, Ohio</town> |
Comments can be inside a text string. (Note: This will cause Flash to incorrectly break the text node into two nodes.) |
|
<!DOCTYPE MyXML [<!--by Jesse-->]> |
Comments can even be inside a document declaration. |
Bad Examples
|
<town <!--or city--> >New York</town> |
Comments cannot be inside a tag. |
|
<!-- It's a--brief--message from me.--> |
Double dashes are disallowed. |
|
<!-- If grade is B+ or A---> |
A triple dash terminator is disallowed. |