Re: [xsl] documenting xsl stylesheets

Subject: Re: [xsl] documenting xsl stylesheets
From: Paul Tremblay <phthenry@xxxxxxxxxxxxx>
Date: Mon, 9 Feb 2004 12:47:37 -0500
On Mon, Feb 09, 2004 at 09:32:41AM +0100, Kielen, Agnes wrote:
> Hi,
> Take a look at Please let me know what you think of it.

Thanks. This is what I was looking for, but I did have one concern. You
state that "All documentation-elements are at the top-level, so no
fallback is necessary."

I didn't realize that you had to include the documentation-elements at
the top level. But I just used an example where the
documentation-element was not at the top level, and of course, the
documentation element got copied to the target document. 

That means that using documentation-elements imposes a limitation on
what you can document. Often times you need to include documentation
that is not at the top level.

But your stylesheets do provide a good way to document the overall
contents of an xslt stylesheet.

I notice that when I use the xslt stylesheet "docToHtml.xsl", I get an
html document that contains one long line. Is this stylesheet just meant
as an example of what one could create in html?

The other stylesheet "createDocumentation.xsl" produces a very nicely
structured XML document with a lot of useful information. 

How exactly do you use this information? Say you are publishing a
stylesheet. Do you include two copies of each stylesheet, one that is
documented and one that is stripped of this documentation, and do you
tell the uses to see the documented stylehseet for documentation? 

Or, do process your documented stylesheet first with
"createDocumentation.xsl" and then with "createProduction.xsl'. In that
way, you create a stripped down xslt stylesheet, and another XML file
that contains the documentation to that xslt stylesheet. Is this XML
file self-explanatory for other xsl authors, or do you further process
the XML documenation to create an HTML page?

I hope no one thinks this post is off topic. I believe that documenting
scrips essential to making them useful to others. So I think discussing 
Anges technique imortant.

Thanks for this tool, Agnes!



*Paul Tremblay         *

 XSL-List info and archive:

Current Thread