[XSL-LIST Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Documenting xsl code.
> 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... > But perhaps we're missing something: Dave (or David > or Warren), can you fill us in on the rationale for taking this approach > rather than using extension elements? I think it is really a case of Dave P trying out various possiblities and us just commenting at times and throwing in the odd bit of code:-) > I also don't understand why the > 'logic' namespace is required: what is the difference between the 'logic' > elements and standard 'xsl' elements? Not sure why Dave called it "logic". But in general you could use a technique such as this to include many "optional" statements, the "code extraction" stylesheet discards some of the namespaces and moves elements in the namespaces corresponding to required options into the XSLT namespace in the runnable version. 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 code extraction stylesheet then is parameterised for which options you want to extract and it does whatever is needed to make a stylesheet. Of course whether or not such a process fits your needs is another matter. Certainly while sketching out initial drafts having the "documented source" be directly runnable (as in the extension element/fallback technique) has some advantages. > 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. > I don't think that basic HTML is going to give very > structured documentation, True. Possibilities are to have some completely new schema, or to use something existing like docbook, or to use the inline HTML markup but contained in some top level structural elements that correspond more closely to XSL code structure. So for an example a template-doc element (in some namespace) may have children a sequence of xhtml paragraphs, the documentation stylesheet could present these in a suitable way, making tables of contents, indexes of templates etc. > [http://www.mulberrytech.com/xsl/xsl-list/archive/msg14276.html]). Yes this is the XSLT specific documentation schema approach. How much of that is necessary depends in a way on how much syntactic analysis the documentation stylesheet does. For example You could introduce specific inline elements for describing the mode but if the documentaion stylesheet itself was checking the mode of each template, adding links to other uses of the same mode, indexing such uses etc, then perhaps the need to highlight the fact that it is in a special mode in the additional documentation text is reduced. Similarly if the stylesheet is automatically adding links between calls to a named template or variable references to the documentation at the point of definition, the kind of documentation that you need to write is somewhat different. David XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|