Re: Documenting xsl code.

Subject: Re: Documenting xsl code.
From: David Carlisle <davidc@xxxxxxxxx>
Date: Tue, 11 Jul 2000 12:17:32 GMT
> 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


Current Thread