Re: [xsl] XSL - Documentation

Subject: Re: [xsl] XSL - Documentation
From: ac <ac@xxxxxxxxxxxxx>
Date: Wed, 13 May 2009 13:21:25 -0400

While a documentation namespace could easily support both attribute and element documentation, and their processing, the documentation nodes are still part of the document. How about using processing instructions for stylesheet documentation?


On Wed, May 13 2009 15:28:05 +0100, davep@xxxxxxxxxxxxx wrote:
I can see where you're going Tony, but aren't you just re-inventing
Tangle and weave? With the added complexity of your perl munging?

More of an alternative than a re-invention, I think. To go back to the post that started this thread:

On Fri, May 01 2009 11:23:07 +0100, stf@xxxxxxxx wrote:
| 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

If you're using an XML editor, why not stick to XML for the
documentation. Seems simpler - and as Ken says, use as much (or
as little) docbook|Dita as you need.

But you may not know any DocBook or DITA. If you spend your working hours writing firstly Java code and secondly XSLT stylesheets to work on OpenTravel XML, what exposure do you have to either DocBook or DITA and what exposure do you have to structured comments?

And as Michael SchC$fer says:

On Wed, May 13 2009 10:57:13 +0100, michael.schaefer@xxxxxxxxxxx wrote:
]  * 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.

The key is surely the pre-pass to pull documentation out and
then merge it (as you've done) with a shell to produce the finished
documentation? I guess that's why I'm frowning at the comment lines :-)

I haven't done it for XSLT, nor did I write the GTK-Doc tools, though some of my XSLT comments do come out looking a lot like GTK-Doc or JavaDoc comments.

I started the day in the just-use-DocBook camp, then something dawned,
so I'm now favouring the idea of a simplified syntax into which you can
mix proper XML, and I seem to have stumbled into the position of
championing it though I'll freely admit it wasn't even my idea.


Tony Graham Tony.Graham@xxxxxxxxxxxxxxxxxxxxxx Director W3C XSL FO SG Invited Expert Menteith Consulting Ltd XML, XSL and XSLT consulting, programming and training Registered Office: 13 Kelly's Bay Beach, Skerries, Co. Dublin, Ireland Registered in Ireland - No. 428599 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- xmlroff XSL Formatter xslide Emacs mode Unicode: A Primer urn:isbn:0-7645-4625-2

Current Thread