Sample Chapter: Beginning XML - Comments

(Page 4 of 7 )

Comments provide a way to insert into an XML document text that isn't really part of the document, but rather is intended for people who are reading the XML source itself.

Anyone who has used a programming language will be familiar with the idea of comments: you want to be able to annotate your code (or your XML), so that those coming after you will be able to figure out what you were doing. (And remember: the one who comes after you may be you! Code you wrote six months ago might be as foreign to you as code someone else wrote.)

Of course, comments may not be as relevant to XML as they are to programming languages; after all, this is just data, and it's self-describing to boot. But you never know when they're going to come in handy, and there are cases where comments can be very useful, even in data.

Comments start with the string <!-- and end with the string -->, as shown here:

<name nickname='Shiny John'>

<first>John</first>

<!--John lost his middle name in a fire-->

<middle></middle>

<last>Doe</last>

</name>

There are a couple of points that we need to note about comments. First, you can't have a comment inside a tag, so the following is illegal:

<middle></middle <!--John lost his middle name in a fire--> >

Second, you can't use the string -- inside a comment, so the following is also illegal:

<!--John lost his middle name -- in a fire-->

The XML specification states that an XML parser doesn't need to pass these comments on to the application, meaning that you should never count on being able to use the information inside a comment from your application.

HTML programmers have often used the trick of inserting scripting code in comments, to protect users with older browsers that didn't support the <SCRIPT> tag. That kind of trick can't be done in XML, since comments won't necessarily be available to the application. Therefore, if you have text that you need to get at later, put it in an element or an attribute!

Try It Out – Some Comments On Al's CD

Since we've only included a couple of the songs from this fine album in our document, perhaps we should inform others that this is the case. That way some kind soul may finish the job for us!

1. Open up your cd2.xml file, make the following changes, and save the modified XML file as cd3.xml:
   
   <CD serial='B6B41B'
   
   disc-length='36:55'>
   
   <artist>"Weird Al" Yankovic</artist>
   
   <title>Dare to be Stupid</title>
   
   <genre>parody</genre>
   
   <date-released>1990</date-released>
   
   <!--date-released is the date released to CD, not to record-->
   
   <song>
   
   <title>Like A Surgeon</title>
   
   <length>
   
   <minutes>3</minutes>
   
   <seconds>33</seconds>
   
   </length>
   
   <parody>
   
   <title>Like A Virgin</title>
   
   <artist>Madonna</artist>
   
   </parody>
   
   </song>
   
   <song>
   
   <title>Dare to be Stupid</title>
   
   <length>
   
   <minutes>3</minutes>
   
   <seconds>25</seconds>
   
   </length>
   
   <parody></parody>
   
   </song>
   
   <!--there are more songs on this CD, but I didn't have time to include
   
   them-->
   
   </CD>
   
   
2. View this in IE5:
   
   

How It Works

With the new comments, anyone who reads the source for our XML document will be able to see that there are actually more than two songs on "Dare To Be Stupid". Furthermore, they can see some information regarding the <date-released> element, which may help them in writing applications that work with this information.

In this example, the XML parser included with IE5 does pass comments up to the application, so IE5 has displayed our comments. But remember that a lot of the time, for all intents and purposes this information is only available to people reading the source file. The information in comments may or may not be passed up to our application, depending on which parser we're using. We can't count on it, unless we specifically choose a parser that does pass them through. This means that the application has no way to know whether or not the list of songs included here is comprehensive.

Try It Out – Making Sure Comments Get Seen

If we really need this information, we should add in some real markup to indicate it.

1. Modify cd3.xml like this, and save it as cd4.xml:
   
   <CD><!--our attributes used to be here-->
   
   <songs>11</songs>
   
   <!--the rest of our XML...-->
   
   <artist>"Weird Al" Yankovic</artist>
   
   <title>Dare to be Stupid</title>
   
   <genre>parody</genre>
   
   <date-released>1990</date-released>
   
   <song>
   
   <title>Like A Surgeon</title>
   
   <length>
   
   <minutes>3</minutes>
   
   <seconds>33</seconds>
   
   </length>
   
   <parody>
   
   <title>Like A Virgin</title>
   
   <artist>Madonna</artist>
   
   </parody>
   
   </song>
   
   <song>
   
   <title>Dare to be Stupid</title>
   
   <length>
   
   <minutes>3</minutes>
   
   <seconds>25</seconds>
   
   </length>
   
   <parody></parody>
   
   </song>
   
   </CD>
   
   
2. This XML is formatted like this in IE5:
   
   
   
   This way, the application could be coded such that if it only finds two <song> elements, but it finds a <songs> element which contains the text "11", it can deduce that there are 9 songs missing.

Next: Empty Elements >>
 

More XML Articles
More By Tim Pabst

Comments On: Sample Chapter: Beginning XML

>>> Be the FIRST to comment on this article!