[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

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
xsl code program
> > 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

PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.