Re: [xsl] New SourceForge Project: Doxsl - A Documentation Generator for XSLT

Subject: Re: [xsl] New SourceForge Project: Doxsl - A Documentation Generator for XSLT
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Thu, 03 Apr 2008 22:11:45 +0200
At 2008-04-03 14:04 -0600, Jim Earley wrote:
Thanks for the pointer - I will definitely take a look.  I really
appreciate the advice.

I just thought of another aspect of XSLStyle that may help: it enforces a number of "stylesheet writing rules". When the stylesheet writer slips up and violates any of these best-practice rules of writing an XSLT stylesheet, the report includes a section in the table of contents and a detailed list of all violations.


Perhaps you've heard Mike Kay remind readers of this list the importance of declaring the types of parameters ... based on his sage advice I added that as a writing rule and I believe it has helped me write better stylesheets.

I feel another important aspect of writing a reusable stylesheet library is to ensure that every globally named construct and mode uses a namespace-qualified name. This insulates a stylesheet library from the names used in any wrapper stylesheet. XSLStyle flags all places where the use of namespace qualification in a global name has not been explicitly allowed by the declaration of an exception.

Another area is documentation completeness ... if there is *any* top-level XSLT construct that is not documented, or any parameter of any template rule not documented, this is considered a violation of the stylesheet writing rules.

I now know when I deliver a stylesheet that when XSLStyle reports no violations of my stylesheet writing rules, it is probably a more rigorously-written and robust stylesheet than if I just winged it. I believe it has reduced the bugs in my stylesheets and shortened their development time. I also know that it has been completely documented. I use it as a gating factor in deciding to check in a stylesheet into my source code control system.

You have an opportunity in writing such a documentation environment to guide the stylesheet writer in their work.

One caveat though ... while managers love the idea of a completely documented stylesheet, many of the actual stylesheet writers have found it a chore ... they don't like being told by XSLStyle that their work is incomplete. I've seen some cheat by putting empty DITA and DocBook constructs into their stylesheets just so that XSLStyle doesn't complain. As with many things, to get the best benefit you have to embrace it and not cheat the system with shortcuts.

Good luck, Jim!

. . . . . . . . . . . . Ken


-- Upcoming: UBL Apr.22,24; genericode code lists Apr.23; Rome,Italy World-wide corporate, govt. & user group XML, XSL and UBL training RSS feeds: publicly-available developer resources and training G. Ken Holman mailto:gkholman@xxxxxxxxxxxxxxxxxxxx Crane Softwrights Ltd. http://www.CraneSoftwrights.com/s/ Box 266, Kars, Ontario CANADA K0A-2E0 +1(613)489-0999 (F:-0995) Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/s/bc Legal business disclaimers: http://www.CraneSoftwrights.com/legal

Current Thread