Hi all!
> 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.
So what's my conclusion?
* 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.
Michael
G. Ken Holman schrieb:
* Michael Schäfer Statistisches Bundesamt
* Software-Entwicklung II C
* XML, Werkzeuge, Standards Gustav-Stresemann-Ring 11
* D-65189 Wiesbaden
* michael(_dot_)schaefer(_at_)destatis(_dot_)de http://www.destatis.de
* http://www.statspez.de
--~------------------------------------------------------------------
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe(_at_)lists(_dot_)mulberrytech(_dot_)com>
--~--