Subject: Re: [xsl] XSL - Documentation|
From: Michael Schäfer <michael.schaefer@xxxxxxxxxxx>
Date: Thu, 14 May 2009 20:53:52 +0200
Interestingly I saw the choice of DITA and DocBook as introducing simplicity because in both cases I use off-the-shelf stylesheets (included in the package) that render these vocabularies to HTML. No need to write one's own documentation vocabulary and then stylesheets for that vocabulary.
Another argument for simplicity in writing and reading may be that comments are not always intended to be processed or to appear in some document apart from the code, but just for being read in place.
And I have a number of customers' stylesheets documented with lists, graphics, tables, program listings and other constructs that are all sitting there ready to use in the off-the-shelf vocabularies.
Given the case, the requirements are there and one can use DocBook etc. to its full potential. The question is, how often is that the case? In my experience - which surely doesn't compare to yours - not so often.
So I just asked myself if there was a need for a simple solution. This and my experience as a Java developer lead me to thinking that using XML comments with Java-style tags and the option to mix in XML markup was not such a bad idea. GTK-doc seems to be quite close to what I had in mind (Thanks to Tony Graham for mentioning it ;)).
The problem presents itself differently if you look beyond XSL and at documenting XML in general. XSL processors are prepared to deal with non-XSL elements and do safely ignore them if they appear at the top level. Using element-based comments may cause validation problems with other XML documents types. If you have no way of altering the schema or controlling the validation process in order to avoid this, you are stuck with XML comments anyway. XML comments are part of the XML syntax and therefore work everywhere you use a decent XML processor. That's why I think they are good for modest and common documentation purposes.
BTW: ac remarked that XML comments should be ruled out because they couldn't be nested. If there was a standard XML documentation namespace it might just provide an element for commenting things out that would not conflict with inner XML comments, and one could use both in combination. In XSL one can already achieve this at the top level by wrapping such a section in any non-XSL element.
But you may find value in learning the basics of these two vocabularies, but you can do a lot knowing only that DocBook <para> and DITA <p> allow you to document every aspect of the stylesheet with paragraphs of prose.
I will sure look at least at DocBook. If there is away to add some semantics to <para> (like a class attribute), I will probably be totally happy with it.
Anyway, thanks to you and the rest for your comments, I've learnt a lot, and of course I'm pleased that some of you found that my idea was not so bad at all.