XSL Transform Self-Documentation
XML version
HTML version
PDF version
SVG version
Track: Late Breaking News, Case Studies, Core Technologies
Audience Level: High Level/Technical view
Time: Wednesday, November 16 14:00
Keywords: XSLT, Documentation, DTD, Namespaces, XML, Stylesheet, Content Conversion, MSXML
Abstract:
Documenting your own code is an important component in the long-term maintenance of any program. In this project we defined a format and developed a system to automatically self-document the data conversion process at PubMed Central. PubMed Central is a digital archive of full-text biomedical journals. It is developed and managed by NCBI (National Center for Biotechnology Information), a division of the National Library of Medicine.
The XSL stylesheets used at PubMed Central for data conversion present a particular challenge because documentation is needed not only for the reference of developers, but also for digital archivists to ensure that the conversion process conforms to accepted archiving standards. The choices that developers make in writing conversion filters need to be transparent and reviewable. To meet this need, we defined a format for inserting documentation into XSL stylesheets. The documentation had to be easy to maintain and needed to be capable of generating documentation for developers, archivists, and other stakeholders.
As developed, documentation can be inserted into stylesheets either as XML elements or as structured XML comments. The documentation system enables users to log journal- and publisher-specific comments, track revisions, impose a comment hierarchy, and specify the intended audience for each comment.
A set of stylesheets was also written that extracts the documentation and generates HTML for display. Because the system is based on XML and XSLT, it is easily extensible and platform independent—it also has the virtue that it can be used to document itself!
Copyright: ©2005
