Nightly thoughts

Friday, February 27, 2009

XSLStyle and oXygen

On almost every XSLT projects I worked on, I used Ken Holman's XSLStyleTM.
It enables one to document each stylesheet component (template,
function, variable, module, etc.) using an XML vocabulary (DocBook and DITA are supported out of the box.)
For instance, the following exerpt shows how to document a simple
named template with a parameter, assuming the vocabulary has been set
to DocBook:

<doc:template><para>Create a paragraph with a greetings message.</para><doc:paramname="who"><para>The name of the person to address the greetings to.</para></doc:param></doc:template><xsl:templatename="greetings"><xsl:paramname="who"as="xs:string"/><h:p><xsl:value-ofselect="concat('Hello, ', $who, '!')"/></h:p></xsl:template>

XSLStyleTM is a set of stylesheets to extract this
information and format it to an HTML page. Besides this formating
tasks, it also checks for best-practices (did you declare the type for
parameters?, etc.) I think this is a very important piece in the XSLT
writer's toolbox.

Seting a project up to use XSLStyle is as easy as adding a tranform
task using the XSLStyle's stylesheets to transform the project's
stylesheet to HTML pages. And of course to add documentation to the
stylesheets. All that is very easy, but you always have to remember
where to installed XSLStyle, check for the namespace URIs to use, and
the exact element names to use to document your code. Once again,
that's very easy, but repetitive and time-consuming.

I use oXygen more and more for
a few months. And I really enjoy it. It helps a lot automating
repetitive, time-consuming tasks: create a new stylesheet with the
right namespace URIs, code completion for known vocabularies, tansform
scenarii, etc. And for schemas, XQuery modules and WSDL definitions,
it provides actions to generate documentation, the same way XSLStyle
generates documentation for XSLT modules. Unfortunately, it does not
support XSLStyle yet. Actually, the scenario attached to almost all
of my stylesheets is the scenario using XSLStyle.

But having XSLStyle integrated within oXygen would bring several
advantages. It would always be installed alongside with oXygen. I am
a freelance consultant and move a lot between different companies,
using several computers, with different system administration
policies. Thanks to the per-person-license model of oXygen, and its
platform independence, I can take it with me everywhere, and be
quickly productive, without having to install separately a JRE, Saxon,
FOP, Xerces, DocBook environment, RELAX NG tools, Schematron
skeletons, Emacs with nXML and others modes, and even Cygwin to be
able to create shell scripts and Makefile to automate tasks. But I
still have to download XSLStyle separately, open one of its
stylesheets to copy and paste a documentation sample and the correct
namespace bindings. Of course, it would be time saving to have an
XSLStyle framework directly in oXygen.

Besides that point, oXygen could offer editing facilities for
stylesheet components documentation as well. When you want to
document a named template with several parameters, you have to create
the documentation structure as showed above, and create a
doc:param element for each parameter, with the correct
name. This could be automatically done with a specific action, to add
an empty documentation structure to a particular component or even to
each non-documented yet componnents in the stylesheet:

There would not have anymore the need to attach the stylesheet to an
XSLStyle scenario neither. When I work on a stylesheet, I like to
have its current scenario bound regarding what I am working on in
particular. Switching back and forth between this scenario and the
XSLStyle scenario does not really make sense. It would be more
productive to have a Tools > Generate Documentation > XSLT
Documentation... action as for the other file type, in my
humble opinion.

And finally, oXygen would even be able to report some
documentation errors directly in the editor pane, as wrong
names in documenting parameters.

I hope oXygen team will be intersted to add support for XSLStyle, as
this would be convenient, but also would spread XSLT writing best
practices advocated by XSLStyle. Anyway, thanks to the team for
listening to user requests, this is too rarely the case in other
companies, and of course to Ken for XSLStyle.