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(_at_)cranesoftwrights(_dot_)com> 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(_at_)CraneSoftwrights(_dot_)com
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
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail:
<mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--