RE: Documenting xsl code.

Subject: RE: Documenting xsl code.
From: Thorbjørn Ravn Andersen <TRA@xxxxxxxx>
Date: Wed, 12 Jul 2000 10:55:35 +0200
> Thorbjørn Ravn Andersen wrote:
> >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.
> 
> Sure the documentation-producing stylesheet determines the 
> documentation
> that can be used, but it would be kinda nice if we could all 
> use the same
> documentation standard because (a) we'd only have to learn that one
> standard to understand other people's documentation and (b) 
> we could have
> lots of different stylesheets giving different formats to the same
> documentation without each person having to think up their own.  Plus,
> using namespaces, anyone can always build extensions on top 
> of what we use:

The only large DTD I know of suitable of this would be the DocBook DTD, (although Sebastian might be more inclined to suggest TEI), but since it was designed to do technical documentation it would be a reasonable suggestion seen from here.

The question is then, how would a document _describing_ a style sheet look like (in any DTD) and can we agree on a consensus?  If so, it should be a reasonable task to reverse engineer a XSLT document to produce it.

I would like to have at least:

*  Each user defined element is linked to its definition (possibly quite easy to do)
   This would allow for cross references to be built, and hypertext links.

*  Categorization of each element for easy syntax highlighting and pretty printing.
   This work may already have been done with the recent announcements.
   At least that each code snippet is presented in a fixed width font interspersed
   with comments.

I cannot come up with others right now.



> I'd view it not as a restriction but as a foundation.

You're most likely right.  Flexibility is crucial here.

-- 
  Thorbjørn Ravn Andersen   "...and...Tubular Bells!"


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


Current Thread