[XSL-LIST Mailing List Archive Home]
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