Processing XML documentation

Written by Mike James

Tuesday, 21 December 2010

Article Index
Processing XML documentation
XSL has loops
Documentation tools

Page 1 of 3

Processing XML documentation - it really is a good problem to solve using XSL. But if you really have to, there are tools such as Sandcastle that will do the entire job for you.

In the article C# auto documentation we looked at how it was easy to create documentation for classes, method, properties etc in XML.

The real question that remains unanswered is what to do with the XML that is generated?

When ever you are presented with some raw data with a regular format the overwhelming temptation is to start a new project and create a processing engine.

This is a very bad idea as it will only divert you from your real goal and soak up much more time than you could ever imagine. In general you should always resist the temptation to create programming tools to help you finish another project. Invariably what happens is that the programming tools become the main project and everything else is put on the back burner.

Even so it is very easy to create an XSL transformation from XML to HTML. The advantage of this is that it is easy and completely under your control. However you do need to heed the earlier warning as converting an XSL transformation into an entire web help system is much more complex than simply applying some formatting.

XSL

XSL is an eXtensible Style Sheet language and it can be used to transform XML documents into a wide range of other formats. A key component of XSL is XPath which is simply a way of picking out any node in an XML tree structure.

An XPath specification is a lot like a URL but you use the following elements:

Expression	Description
nodename	Selects all child nodes of the named node
/	Selects from the root node
//	Selects nodes in the document from the current node that match any subsequent selection no matter where they are
.	Selects the current node
..	Selects the parent of the current node
@	Selects attributes

So for example:

/doc/members

selects the all of the <members> tags within the <doc> tag and

doc/members/member/@name

selects all the name attributes of all the member tags nested in <doc><members> and so on.

You can also use predicates, always in square brackets, to select particular nodes. For example, [1] is the first match, [last] is the last. [@attrib] selects only nodes that have the attribute attrib and so on. You can also use wildcards as in * matches any node, @* matches any attribute and node() matches any node of any type.

For example:

doc/members/member[2]/@name

matches the name attribute of the second member tag.

XPath isn't difficult and you can almost pick it up as you go along. Check out its detailed syntax after you have seen some more examples.

The idea is that you can use XSL and XPath to create an HTML page by mixing HTML tags with information extracted from the XML file as specified by XPath expressions.

That is you pick out values and attributes specified by the XPATH statements that you want to format.

To see this in action generate an XML file from some XML comments. The file that is going to be used in this example is generated from the example in the article C# auto documentation.

The first thing to to is to add to the start the line:

<?xml-stylesheet type="text/xsl"
                       href="/XLS1.xsl"?>

This instructs any XSL capable XML processor to load the XSL file called XLS1.xsl and use it to transform the XML in the XML file before displaying it. Notice that you load the XML file into say FireFox, IE or Chrome to see that effect the XSL has.

Now all we need is a suitable XSL file.

For simplicity we are going use the XML file documenting MyMethod as described in C# auto documentation and build an XSL file to display the details of the method.

We need an XSL file that starts off in the standard way:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0" 
 xmlns:xsl="http://www.w3.org/1999/
                        XSL/Transform">
<xsl:template match="/">

Next we enter some basic HTML tags to get the page started:

<html>
<body>
 <h1>XSL formatted XML help</h1>
<hr/>

The first piece of information derived from the XML comments file is the assembly name which is done using an XSL XPath selector. In general our problem is writing XSL selectors which pick out just the information we need.

<h2>
Assembly name:
<xsl:value-of select="doc/assembly/name"/>
</h2>

The XPATH simply specifies the value of the <name> tag nested within <doc> and <assembly> i.e. the name of the assembly. The first part of the xsl tag i.e.

<xsl:value-of

specifies that when the node is located we want to use its value.

<ASIN:0596007647>

<ASIN:1451531168>

Prev - Next >>

Last Updated ( Tuesday, 21 December 2010 )