Re: [xsl] XSL - Documentation

["G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>]

At 2009-05-01 12:23 +0200, Stefan Krause wrote:
> 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?

I use XSLStyle that I first released publicly in 2004:

    http://www.CraneSoftwrights.com/resources/#xslstyle

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?

I doubt it.  Different strokes for different folks.  I'm amazed to 
see how little documentation there is in stylesheets I'm asked to work on.

I hope this helps.

. . . . . . . . Ken

--
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