Re: [xsl] XSL - Documentation
Subject: Re: [xsl] XSL - Documentation|
From: Wendell Piez <wapiez@xxxxxxxxxxxxxxxx>
Date: Wed, 13 May 2009 17:31:18 -0400
At 01:21 PM 5/13/2009, ac wrote:
While a documentation namespace could easily support both attribute
and element documentation, and their processing, the documentation
nodes are still part of the document. How about using processing
instructions for stylesheet documentation?
This is the kind of out-of-the-blue idea I am ordinarily partial to,
but I can't say I see why this would give any real advantage.
Processing instructions are great for inline directives to particular
processes, but they're not well suited to storing information as such.
On the other hand, the suggestion does have the virtue of casting
into relief the relative advantages and disadvantages of the usual
ways of doing it, that is of using comments (however processed by
documentation engines) vs. using elements (and/or attributes).
The tradeoff there, it seems to me, is essentially one of how much is
demanded of the author, both in installing and maintaining the
infrastructure and in encoding and maintaining the documentation
itself, vs. the benefits of having the documentation downstream
(which are definite, but frequently unpredictable).
And the reason this is so hard is in the wide range (as has been
remarked more than once) of appropriate levels of documentation -- as
complicated by the fact that no automated system, however tightly
managed its validation, can actually guarantee that the right thing
is always done (or even ever done). It can only support it when it is
there, and performed properly according to the system's own expectations.
In that light, I find it somewhat paradoxical that stylesheet
authors, who are more than anyone should be conscious of how tagging
rules can be evaded or twisted by their users, should look to
automated processes to save us from ourselves, as opposed to simply
leveraging the technology we know, which most of us are doing all the
time in many ways not excluding this one.
I hope this isn't taken as throwing cold water on any particular
ideas. It's just that I think that a modest and incremental approach,
in which real value is returned for even a light or moderate
investment (in learning as well as in maintaining overhead), is more
likely to attract and keep happy users than a total solution.
And unless we expect this to be the kind of standard that is adopted
top-down, by the fiat of managers rather than the assent of users, we
would need our users to be happy.
Wendell Piez mailto:wapiez@xxxxxxxxxxxxxxxx
Mulberry Technologies, Inc. http://www.mulberrytech.com
17 West Jefferson Street Direct Phone: 301/315-9635
Suite 207 Phone: 301/315-9631
Rockville, MD 20850 Fax: 301/315-8285
Mulberry Technologies: A Consultancy Specializing in SGML and XML