Introduction to Annotated XML

When the XML 1.0 Specification was created, it contained lot of information where some of them were self-explanatory and some of the information was confusing.


To give explanation to the confusing terms you need to have a separate document that explained the confusing terms. Hence you would be having a main document which has links to the smaller documents that give you explanation of the complex terms. This type of main document with links to other small documents is called the annotated document. This type of annotated web page document can be created based on the Annotated XML Specification created by Tim Bray. To understand how a annotated XML document would look like you can see the page

The annotated XML specification addresses the problems created by confusing terms in the XML Specification. To create a annotated document you need two files. One which contains the source file and the other contains the annotations. In the link given above Tim Bray has used xml.xml and notes.xml, where xml.xml contains the XML specification and the notes.xml contains the annotations. A Java program which uses the Lark processor reads the .xml files and creates a target.html file and many other small html files that contain annotations. The target html file that is created contains the annotated XML specification. If you view the link given above you will understand how the annotated XML works.

In designing the annotations the XLink and XPointer technologies are used since they point to any arbitrary locations inside a document. There are two kinds of XLinks and the xml:link=”extended” is used in designing the annotations. The annotated spec contains a main linking element called x. The x element and its attributes are given here below:

<!DOCTYPE Annotations [
<!ELEMENT x (here|spec)+>
xml:link CDATA #FIXED "extended"
inline CDATA #FIXED "true"
content-role CDATA #FIXED "commentary"
content-title CDATA #FIXED "Annotation"
<x id="id-of-firstlink"> ... content of first link ... </x>
<x id="id-of-secondlink"> ... content of second link ... </x>

You could note that the x element contains one here element and many spec elements. The here element contains the text of the annotation and the spec element points to the location of the annotation in the XML spec. For more information on the here element and the spec element check the link

Once the xml document and the main xml document that contains the spec are ready a Java program that does the processing by using a Lark processor gives a html document that contains links to the annotated html documents. This would be the final output and the following are the steps involved in producing the target html file and the annotated html documents.

1. Parsing the annotations: using an instance of the Lark parser the program reads the annotations file. At the end of this step a variable points to the root of the annotations document tree.
2. Create a vector of XLinks in the document.
3. The XLink vector is traversed. The spec XPointers are traversed.
4. Create the main html file with images that hyperlink the annotations required.
5. Write the Annotations files: For each of the annotations found in the notes.xml we create a new annotation html file. The id attribute is used for the filename.
for (i = 0; i < notes.size(); i++)
if (notes.elementAt(i) instanceof Element)
child = (Element) notes.elementAt(i);
title = child.attributeValue("id");
out = new PrintStream(new FileOutputStream(
"notes/" + title + ".html"));
+ title + "</TITLE>");

The code snippet given above is used to iterate through the elements of the notes.xml file and create separate html files for annotations.

Thus creating an annotated specification will really add value to the reference materials on the web. Using XPointer will load all the document in the memory and excessive memory is required to process such documents.


FREE Subscription

Subscribe to our mailing list and receive new articles
through email. Keep yourself updated with latest
developments in the industry.


Note : We never rent, trade, or sell my email lists to
anyone. We assure that your privacy is respected
and protected.


FREE Subscription

Stay Current With the Latest Technology Developments Realted to XML. Signup for Our Newsletter and Receive New Articles Through Email.



Note : We never rent, trade, or sell our email lists to anyone. We assure that your privacy is respected and protected.



Add to My Yahoo!

Visit XML Training Material Guide Homepage



Copyright - © 2004 - 2017 - All Rights Reserved.