RE: Documenting xsl code.

Subject: RE: Documenting xsl code.
From: Thorbjørn Ravn Andersen <TRA@xxxxxxxx>
Date: Tue, 11 Jul 2000 16:18:33 +0200
> > I must say that I'm inclined to agree with Imran: I'd rather have a
> > stylesheet that it documented than a document with a stylesheet and
> > documentation in it.
> 
> Well as I commented earlier one of the problems with the "literate
> programming" approach is that most people seem to agree with you...

Unless you need to construct named code chunks and move them around (which was essential to the original literate programming implementations like TeX), you can still have the most of it by having a valid XSL file, which can be processed to produce verbose documentation. 

Modern tools do simply not go well with preprocessed code. 

> ... Note that this 
> "tangle" process
> might do more than simply copy lines, it could for example include the
> intereseting "loop compiler" that was posted yesterday. Thus the
> documented source may have "code" sections that have iterative loops,
> optional sections in one or more namespaces, and be 
> introduced in whatever
> order is desirable for understanding the program flow.

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. 

This is a fully valid approach, but it is moving away from the original intent which was to have self-documenting style sheets.


> > Another comment: I assume from looking at it that the 'doc' 
> namespace is
> > based on XHTML1.0?
> 
> Only to simplify conversion to HTML:-)
> Norm would I am sure use docbook based markup, and a fancier 
> converter.

The documentation language should not be restricted to any particular set of DTD.  This is -- of course -- depending on the style sheet creating the documentation.

-- 
  Thorbjørn Ravn Andersen   "...and...Tubular Bells!"


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


Current Thread