Re: New SourceForge Project: Doxsl - A Documentation

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