Subject: Re: [xsl] XSL - Documentation|
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Fri, 01 May 2009 07:35:45 -0400
I was looking for the most common way to document XSL-Stylesheets and found a lot of small solutions in the web, which belongs to one of these groups:
1) use of comments, similar to JavaDoc 2) use of an extension namespace 3) literate programming
Since comments are restricted to pure text and literate programming is a little bit out of my scope, I ended up with the use of an extension namespace (XSLTdoc), which works fine for me.
There are several tools out in the wild, but as far as I can see there is no widely spread solution. For example, OxygenXML supports none of them.
So, here are my questions:
1) Which tool do you use to create stylesheet documentations? What are the pros and cons?
pros - enforces what I think are good stylesheet writing rules such as nameespace-qualified global names, types on all functions, global variables and parameters, documentation for every global construct and every parameter - uses either DocBook or DITA for embedded documentation, rather than dreaming up yet another documentation vocabulary; this allows very complete documentation (tables, graphics, etc.) in the stylesheet - documents every stylesheet fragment of the entire import tree just by formatting the top-most fragment - includes an alphabetized hyperlinked index of all named globals across the entire import tree
cons - some stylesheet writers resent having to document everything before checking in their modules to a source code control system (though I don't think that's a problem with the method, but a mindset for the stylesheet writer) - the resulting documentation doesn't (yet) look very flashy because I'm not a graphic artist ... this is being addressed soon because I have had the contributions of two users (who are members of this mail list) to help spiffy up the appearance of the generated documentation
2) Is there a need (and a chance) for the xsl community to focus on one singe tool, may be to encourage the software vendors to implement support?
-- XSLT/XSL-FO/XQuery hands-on training - Los Angeles, USA 2009-06-08 Crane Softwrights Ltd. http://www.CraneSoftwrights.com/s/ Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video Video lesson: http://www.youtube.com/watch?v=PrNjJCh7Ppg&fmt=18 Video overview: http://www.youtube.com/watch?v=VTiodiij6gE&fmt=18 G. Ken Holman mailto:gkholman@xxxxxxxxxxxxxxxxxxxx Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/s/bc Legal business disclaimers: http://www.CraneSoftwrights.com/legal