[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] RE: Re: xsl/xslt coding standard
What about just using custom attributes rather than comment elements? It means your documentation is not arbitrarily structured, but it can at least have a structure that matches the stylesheet itself, without interfering too much with the output tree. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:doc="doc:documentation" xsl:exclude-resultset-prefixes="doc" doc:comment="This stylesheet handles blah elements" > <xsl:template match="blah" doc:comment="Handles each blah"> <xsl:param name="blah-type" doc:comment="the type of blah handled" /> <xsl:for-each select="blah-child[@type="$blah-type]" doc:comment="for each child of the selected type" > etc... An XSLT processor should be happy to ignore these comments (isn't that right?) while a simple XSLT could turn these comments into a nice "pretty-printed" stylesheet. Outside of a template, elements are unproblematic, and as Jeni suggested they should probably use html elements (like in JavaDoc) for occasions where more structure is needed. I don't think there's a need for full-on "DocBook" structure for commenting parameters, variables, templates etc, because mostly these comments could be added as @doc:comment attributes to the XSLT elements themselves. <doc:comment> <p>See also:</p> <ul> <li><a href="blah blah blah">Blah blah blah</a></li> <li><a href="something else">Something else</a></li> </ul> </doc:comment> Con XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|