Login | Register   
LinkedIn
Google+
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

Document Your XSLT-6 : Page 6


advertisement

The Documentation XSLT

The actual code for the documentation.xsl file is fairly complex, consisting of about 10 distinct templates over about 300 lines of code. However, it contains no external parameterizations, so you can apply the documentation.xsl file to any XSL document by including the xml-stylesheet directive (this applies only to IE5 and above). Note that you must have the MSXML3 parser installed-this will not work with the older MSXML2.5 version:

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


Note that the documentation.xsl file can even be applied to itself, and the file contains a <doc:summary> element for more detailed information. The named template displayPage does the primary work. This root node also invokes the displayPage template directly (you can apply displayPage as a named template by passing the <xsl:stylesheet> node as a node-set, as outlined in the documentation itself).

Stripping Documentation Information
Documented XSLT functions can get to be very large, and in a server environment this overhead can prove a barrier to scalability. Fortunately, the structure of the documentation namespace is such that it is very easy to remove from the stylesheet through another XSLT transformation. This one, stripDocumentation.xsl is another identity template that searches for any node in the doc: namespace and terminates it at that point, but otherwise copies all other nodes found into the output stream.

The result of the documentation stripper stylesheet should not be saved over the original documented stylesheet, unless you want to lose your documentation. Instead, you should think about keeping two versions of your stylesheets, a documented version that you update with the appropriate code and the stripped undocumented version that you deploy in your production version (and that's created from the documented version).

Summary
Part of the process of creating a cohesive framework for XSLT development lies in providing some level of documentation for the transformation stylesheets with which you're dealing. The techniques and stylesheets given here provide some basic examples of how XSLT can be both documented and deployed in a production environment, although certainly there is a lot more that can be done. The current documentation namespace is largely an ad hoc one. The next logical course would be to model a documentation namespace using the Resource Description Framework (RDF) schema, making it compliant with other XML specifications. Moreover, the documentation should be considered as part of a larger documentation management system that does such things as track revisions and versioning, manage imports and includes, and work in conjunction with XML data sources. Still, even without spending the time to create the full user documentation, the documentation.xsl stylesheet shows how you can easily query an XSLT document for all types of useful information.



Kurt Cagle is a writer and developer specializing in XML, XSLT and distributed Internet application technologies, and is author of Sybex's XML Developers' Handbook and coauthor of the upcoming Wrox Professional XSLT book. He lives in Olympia, Washington with his wife and two daughters, and welcomes any comments, questions or suggestions for articles. He can be reached at cagle@olywa.net
Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap
Thanks for your registration, follow us on our social networks to keep up-to-date