Re: Documenting xsl code.

Subject: Re: Documenting xsl code.
From: "Imran Rashid" <imranr@xxxxxxxxxxx>
Date: Tue, 11 Jul 2000 10:59:09 -0500
> The instant you move away from this, you do not have a XSLT-program 
> anymore, and you should call it something else, and that it may be rendered
> into a XSLT-program and documentation.

I think this really is the key point -- with that approach, I can't give
somebody the file and say "here, this is standard XSLT, any XSLT processor
will now what to do with it."  furthermore it'll be a real pain when trying
to tell newbie's how they should write XSLT.  "well, no, this isn't real
XSLT -- this is semi-XSLT that will be processed by XSLT to produce real
XSLT that will then process your source document."
    while that approach is fine for some one who is always using their
stylesheets internally, and they can be quite confident that anyone seeing
their stylesheets understands what they're doing, I don't think it works for
the general case.

> The documentation language should not be restricted to any particular set
> of DTD.

maybe not "restrict" to a DTD, but how about a "suggested" DTD??
what I'm trying to say is, I would really like it if this list could agree
on a semi-standard set of tags for documentation.  so that if somebody has
<param>
 <paramName>width</paramName>
 <paramValue>this parameter gets its value from the value of the img elem's
@width tag</paramValue>
</param>

other XSLT developers will understand my documentation. Furthemore, somebody
will be able to write a "doc-generating" stylesheet, that should work on any
stylesheet, and generate documentation in some way.  It will leave everyone
free to create the documentation using whatever stylesheet they like (eg.
maybe they only want to see the mode of templates).  however, having common
XML markup means that that your doc-generate.xsl works on my
complexTransform.xsl, so you can look at my code and get the comments *you*
want.

(I'm not really suggesting a syntax like that, just for illustration
purpose.)

not that we should really restrict others from using a different form of
documentation -- it just would be nice to have something semi-standard.  Not
super official, just commonly understood.

but like I said, I'll go with whatever the smarter people decide.

Imran


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list


Current Thread