Re: XSL - Documentation

Hello,

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