Re: [xsl] XSL - Documentation

Subject: Re: [xsl] XSL - Documentation
From: Michael Schäfer <michael.schaefer@xxxxxxxxxxx>
Date: Wed, 13 May 2009 11:57:13 +0200
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 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

Current Thread