Re: Documenting xsl code.

Imran Rashid wrote:
>> Three files below.
>> 1. A 'self documented stylesheet' (doc.xsl)
>> 2. A stylesheet (doc-doc.xsl), which works on doc.xsl
>>     to extract the documentation in the doc namespace
>> 3. A stylesheet doc-logic.xsl, which works on the doc.xsl
>>    to extract the code.
>
>I completely defer to the decision of the gurus, but I prefered the approach
>using doc: extension elements and xsl:fallback in doc.xsl.

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.  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 also don't understand why the
'logic' namespace is required: what is the difference between the 'logic'
elements and standard 'xsl' elements?

Another comment: I assume from looking at it that the 'doc' namespace is
based on XHTML1.0?  I'd prefer to at least see use of 'doc:var' elements
than 'doc:i' to highlight the names of variables.  As far as I understand
it, a schema for documenting XSLT would be suitable whichever method
(pre-parsing the self-documented stylesheet or using extension elements)
was used, so this is a separate issue.  As long as it was compatible with
that schema, the (vast majority of) doc-doc.xsl stylesheet could be used on
both self-documented stylesheets and on stylesheets documented with
extension elements.  I don't think that basic HTML is going to give very
structured documentation, so I'd like to see something over and above HTML
being used (and have suggested the types of phrases that I'd like to mark
up in a previous post
[http://www.mulberrytech.com/xsl/xsl-list/archive/msg14276.html]).

Cheers,

Jeni

Dr Jeni Tennison
Epistemics Ltd, Strelley Hall, Nottingham, NG8 6PE
Telephone 0115 9061301 ? Fax 0115 9061304 ? Email
jeni.tennison@xxxxxxxxxxxxxxxx



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