Subject: Re: [xsl] XSL - Documentation|
From: Michael Schäfer <michael.schaefer@xxxxxxxxxxx>
Date: Wed, 13 May 2009 11:57:13 +0200
> At 2009-05-01 12:23 +0200, Stefan Krause wrote: >> Hello, >> >> I was looking for the most common way to document XSL-Stylesheets and >> found a lot of small solutions in the web, which belongs to one of these >> groups: >> >> 1) use of comments, similar to JavaDoc >> 2) use of an extension namespace >> 3) literate programming >>
> > I use XSLStyle that I first released publicly in 2004: > > http://www.CraneSoftwrights.com/resources/#xslstyle >
> >> 2) Is there a need (and a chance) for the xsl community to focus on one >> singe tool, may be to encourage the software vendors to implement >> support? > > I doubt it. Different strokes for different folks. I'm amazed to see > how little documentation there is in stylesheets I'm asked to work on. > > I hope this helps. > > . . . . . . . . Ken
This thread caught my interest because I've written numerous stylesheets and have been trying to document then properly but never got beyond using simple XML comments. Thanks so far for dealing with this topic.
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.
* There are other XML documents that require good documentation. Schemata are one example. XSD built-in documentation is rather minimalistic (no reproach meant, the WG surely had their reasons and other things to attend to). Another one are XML configuration files.
* Namespace-based comments clearly have their benefits, but some disadvantages as well. In a text editor, they do not set off from the XML "payload" as well as do simple comments and so blur to some extend the distinction between comments and the rest. In other words, they make the document less readable. Also, they are costlier in that an XML processor cannot treat them the same simple way it can treat XML comments. They make an XML document more complex by adding another namespace, and they need to be parsed. In XSL such comments can only appear as top level elements, otherwise they would be treated as literal output elements (this could be remedied if there existed a standard XML documentation namespace).
Simple XML comments can be discarded without risk by any XML processor that doesn't need to look at them, and they are unlikely to do any harm if they are retained.
I think, in practice you'll need a good XML IDE in order to work efficiently with 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.
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 requirements on XML documentation, including XSL, probably vary a lot. On the one hand, documenting should be a simple task and doable without using a full-fledged XML IDE. On the other, it should fit in with standards used in the area and not be unnecessarily restrictive. A general, extensible approach to XML documentation may be able to meet these requirements.
* A general approach to documenting XML would define an extensible model with a basic information set. Then one would define a variety of representations of that model like simple XML comments, DITA, DocBook, XHTML and so on, and rules for transforming one representation into another, and for extending the model.
* Like XSLStyle and others, an XML documentation framework could be implemented as a set of XSLT stylesheets and then could be used standalone as well as integrated in an XML IDE.
Nevertheless, I'm not planning to invent another wheel and will first take a close look at XSLStyle and it's companions.
G. Ken Holman schrieb: * Michael Schdfer Statistisches Bundesamt * Software-Entwicklung II C * XML, Werkzeuge, Standards Gustav-Stresemann-Ring 11 * D-65189 Wiesbaden * michael.schaefer@xxxxxxxxxxx http://www.destatis.de * http://www.statspez.de