Re: XSL - Documentation
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.
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.
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.
. . . . . . . . . . . . . Ken
-- 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
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