Re: xsl self-documentation - ideas

> Are there benefits in either ease of implementation or clarity 
> in either approach?

well it depends whether you want chalk or cheese, both are useful but
not at the same time.

If you have a 5MB file of data on dead people in Rome (to take a not
exactly mythical example) and a one page stylesheet that does something
with that data.

Then if you want to understand the stylesheet you want a "weave" style
documentation, a version of the stylesheet with expanded comments and
cross links, but with size basically a function of the size of the
stylesheet.

If however you understand (or thought you understood) the stylesheet but
want to know why gravestone 7001 got missed out, then what you might
need is a documented trace of what the run of the stylesheet on the
particular 5MB input file did, but note this is documenting the input
file as much, or perhaps more than, documenting the stylesheet.
The size of the result is (normally) going to be of the order of the
size of the input, thus MB in this case, often needed for debugging
but not much help as "documentation".

Not only are the methods different, the kind of documentation texts
that are being added need to be completely different, it is hard to see
any overlap between the two processes.

> Suggest the 'in-line' process is more useful when 'tracing',
> the 'weave' process when simply documenting the stylesheet
> 'statically'.

yes exactly.

As a well known TeX user, would you could, compare getting
documentation about (say) the longtable package from the documented
sources: latex longtable.dtx
to making an example file with some tables, and then running latex on
them with \tracingall. As a matter of fact I do the latter far more
often than I do the former (I wrote the documentation, I don't read it
so often:-) but it isn't anything I'd recommend as a pastime.

David


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