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-3 : Page 3


advertisement

Documentation Namespace

The stylesheet first needs to define the doc namespace by including the msxml:doc attribute on the stylesheet. To ensure that the doc namespace (along with the msxml namespace, used for some support functions) isn't also sent along to the output stream, add the exclude-result-prefixes attribute, which takes a list of all of the prefixes that you don't want to have end up in the final output.

The doc:summary block serves as the nexus for providing documentation information about the stylesheet. Strictly speaking, the doc:summary block is not necessary—the documentation.xsl function can provide a fairly exhaustive listing without the need to include the doc:summary header block—but it serves as a place to provide detailed user information, such as a description of what the stylesheet does, the filename of the stylesheet (which can't be retrieved explicitly from XSLT without using some external functions, so should generally be included internally), a title which clearly identifies the stylesheet, date information, and finally, a version number.



The version number is actually quite useful. One common problem that I encounter when working with XSLT is that I may have multiple versions of the same stylesheet. I can't necessarily rely on date alone to insure that I'm dealing with the most recent version. By incorporating a version stamp for the stylesheet (as opposed to the version of the XSLT, which is what the stylesheet xsl:version attribute is for) you can track revisions  and provide a consistent identifier that more complex document management systems can use to keep your code up to date.

As an aside, the doc:description element can contain either XHTML text or CDATA sections containing HTML. The doc:summary/doc:description element is the primary description for the document, and is intended to give the reader a clear picture of what the template does. When the description is present, it is possible to get syntactical information, but semantic meaning will be more difficult to ascertain. As such, you should use this element extensively as the primary user documentation into your code.

The doc:description element can also appear as an attribute to templates, parameters, variables and attribute sets.  These work in conjunction with the doc:public attribute, which defines whether or not a given element should be visible to the documentation.  In general, doc:public defaults to "yes" for named templates (templates with the name attribute), global parameters, and the parameters of named templates, and defaults to "no" for matched templates (templates with the match attribute), global variables, and internal variables.  Additionally, even if a local parameter is made public, if its containing template is private (i.e., doc:public="no") then it won't be displayed.

For example, the following named template, convert_text_to_xml, is explicitly made public, which makes its parameters public implicitly. Note that the variable lines.tf is implicitly private:

<xsl:template name="convert_text_to_xml" doc:description="This named template converts delimited fields into an XML node-tree." doc:public="yes"> <xsl:param name="parse_text" select="$parse_text" doc:description="See description for global parameter 'parse_text'"/> <xsl:param name="item_delimiter" select="$item_delimiter" doc:description="See description for global parameter 'item_delimiter'"/> <xsl:param name="line_delimiter" select="$line_delimiter" doc:description="See description for global parameter 'line_delimiter'"/> <xsl:variable name="lines.tf"> <!-- more code --> </xsl:template>



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