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(_at_)CraneSoftwrights(_dot_)com
Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers: http://www.CraneSoftwrights.com/legal
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--