RE: Documenting xsl code.

["Pawson, David" <DPawson at rnib dot org dot uk>]

Jeni T.
>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?

More to say that the xsl prefix is optional than anything else.




>
>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.

Fine. It was easy to do it straight to HTML for display.
As Norm has shown, its equally easy to provide XYZ DTD output,
he chose docbook. I know Warren wants both HTML and latex output
for documentation, so his will again be selectable via a command line
parameter.


  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

<aside> I found getting my head round even this level of introspection
sufficient. Sounds like you want to take it one step further, as does Norm,
and go the whole hog. Equally Warren could output to a standard
documentation
DTD (docbook is probably ideal), then reprocess to provide \tex HTML etc as
needed. 
 HTML makes it easier to see what is needed, though with an xml output,
there would be no need, at this stage, for the complexities of David C's
routines near the end of the doc-doc file.
</aside>

Regards, DaveP


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