Cart
|
[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: XSL - Documentation
 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. Cheers, Wendell ====================================================================== 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 ====================================================================== 
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! 
Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|
