Subject: Re: [xsl] New SourceForge Project: Doxsl - A Documentation Generator for XSLT From: "Jim Earley" <xml.jim@xxxxxxxxx> Date: Thu, 3 Apr 2008 14:29:02 -0600 |
Hi Ken, Thanks - I have some aspects of this built in, but I do like the concept of enabling best practices (and notifying developers when they violate these)! I think this might be a useful enhancement. I certainly do appreciate the advice and will keep you posted as to the progress of this project. Cheers, Jim On Thu, Apr 3, 2008 at 2:11 PM, G. Ken Holman <gkholman@xxxxxxxxxxxxxxxxxxxx> wrote: > 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 |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: [xsl] New SourceForge Project: , G. Ken Holman | Thread | RE: [xsl] New SourceForge Project: , Michael Kay |
[xsl] Re: [XSL] xi:include coded in, Alain | Date | [xsl] changing from no namespace to, Jim_Albright |
Month |