Re: [xsl] XSL - Documentation

Subject: Re: [xsl] XSL - Documentation
From: ac <ac@xxxxxxxxxxxxx>
Date: Wed, 13 May 2009 18:40:03 -0400
Hi Wendell,

Thanks for your feedback.

In a way, I like the idea of a documentation namespace as it is flexible and ... formal. It allows attaching documentation almost anywhere, while keeping it relatively easy to process, it is just more XML. I am not sure that I like the idea of having to strip it off of a stylesheet every time that I need to deliver a stylesheet or even just for testing (e.g. with/without the markup of the selected namespace).

PIs may not be as flexible and formal, but can still be used (e.g. they can even embed markup, ex: multilevel documentation, references), in fact, using PIs with embedded markup can add (default) auto-stripping of the stylesheet documentation, to a documentation namespace approach.

Also, isn't embedded stylesheet documentation, a form of 'processing instruction' anyway?

Comments are useful for many things, including for commenting out stylesheet sections that may also contain documentation, but comments can not be nested, which should rule them out, for stylesheet documentation.

There is no doubt in my mind that something formal (e.g. standard) is required to enable proper documentation, documentation processing tools, and documentation sharing (e.g. information is useless if it cannot be shared).


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.      
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

Current Thread