Subject: Re: [xsl] XSL - Documentation|
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Wed, 13 May 2009 08:09:56 -0400
I've given this subject some thoughts I'd like to share. They centre on two central aspects: a possible requirement for a general approach to standardising XML documentation and simple XML comments vs. structured, namespace-based comments. ... * XSLStyle supports DITA and DocBook. I have practically no experience with these document types, but from the little I know I'd say that in the vast majority of cases they go far beyond the requirements for documenting XSLT, XSD and so on.
When generating documentation from an XSL document, one gets most of the information by analysing the code, so in a comment one would add maybe some descriptive text, change and state information and a hyperlink here and there, or an image. The same probably applies to XSD.
So I think that allowing the full set of DITA and DocBook features for use in comments may introduce unnecessary complexity.
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.
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.
If one looks at Wiki text formatting like it's supported in Trac, one can do impressively much with little effort and complexity, including tables, images and hyperlinks, and the learning curve is flat. If more was needed, one could mix in XML islands as one does with HTML in Java comments.
The modular design of the stylesheets should allow anyone to plug in their own documentation vocabulary in place of DITA or DocBook. You are welcome to find or devise your own XML model for documentation and integrate it into XSLStyle. The design should allow you to do this without touching the XSLStyle fragments as I believe those fragments have zero dependencies on either DITA or DocBook.
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.
Forgive my delay (because of OASIS deadlines in two committees) in incorporating stylistic layers in between XSLStyle and either DocBook or DITA that have been requested by two active users. These changes will give a much flashier presentation of the content that looks far more visually attractive than just using the off-the-shelf stylesheets. Again, as I said above, both any new vocabulary and its stylesheets should be able to be incorporated with zero changes to the base XSLStyle stylesheet fragments. I hope it won't be long before my committee work abates.
-- XSLT/XSL-FO/XQuery hands-on training - Los Angeles, USA 2009-06-08 Crane Softwrights Ltd. http://www.CraneSoftwrights.com/s/ Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video Video lesson: http://www.youtube.com/watch?v=PrNjJCh7Ppg&fmt=18 Video overview: http://www.youtube.com/watch?v=VTiodiij6gE&fmt=18 G. Ken Holman mailto:gkholman@xxxxxxxxxxxxxxxxxxxx Male Cancer Awareness Nov'07 http://www.CraneSoftwrights.com/s/bc Legal business disclaimers: http://www.CraneSoftwrights.com/legal