Re: [xsl] XSL - Documentation

Subject: Re: [xsl] XSL - Documentation
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Fri, 01 May 2009 07:35:45 -0400
At 2009-05-01 12:23 +0200, Stefan Krause wrote:

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

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:

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.
Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video
Video lesson:
Video overview:
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Male Cancer Awareness Nov'07
Legal business disclaimers:

Current Thread