in reply to XML documentation formatting and transformations

XML is pretty amazing when it's paired with XSLT -- Firstly, read through the ORA XSLT reference guide. If you're pressed for time in the bookstore, go directly to chapter 9, the case study.
Secondly, realize that most of the modules on CPAN dealing with XML transformation are lacking (not XML parsing, mind, but transformation). Look here or here (windows) for adaptations of Gnome's XML and XSLT libraries.
They're incredibly flexible, and are so far, performed admirably regardless of what I through at them -- they allow for some of the more esoteric functions of the XSLT specification (allowing external processors to run over data, or certain namespaces, for instance), and I have yet to run into limitations.
If all you're looking for is a transformation from XML to HTML, a good style sheet will typically get you started. If you want to rearrange or reorder the way elements are displayed, use XSLT.
Also useful with XML transformation libraries is the idea of allowing users to develop their own XSL docs so that they can present data in a form useful to them -- doing this might involve running the transformation through CGI, and that might be quite expensive.
So to sum up, XSLT sounds like it's worth your time.

And regarding your example document : it seems like it'd be ripe for something similar to a cross-ref tag. For instance :

This returns the generated callback function that is a thunk to turn a WNDPROC or WNDPROC_2 signature into a call to @handle_message on this instance.

might have (e.g.) <XREF> tags around WNDPROC, WNDPROC_2 and @handle_message to provide links to other documents as appropriate.

update I meant "cascading stylesheet", to clarify.

Replies are listed 'Best First'.
Re: Re: XML documentation formatting and transformations (boo)
by John M. Dlugosz (Monsignor) on Nov 01, 2001 at 09:16 UTC
    Re my document and cross-ref: the @ symbol indicates that the following word is set in code-style, and also will automatically generate cross references. Any @-word that can't be matched to a cross-reference would generate a warning. I have in mind (ultimatly) that when the mouse passes over one that names a parameter, the parameter in the signatures is highlighted. It would be smart enough to automatically link to other members in the same class, quallified symbols, and other class names. Details of a mapping, if needed, could be specified in another element. Anything that's not automatic would be an element embedded in the text.

    Also, if the mouse passes over a reference that's not local, it can show details in the lower window or a popup, or expand. E.g. the view just shows "sMSG", but when you hover it tells you it's actually "class ratwin::message::sMSG".

    re "a good style sheet will typically get you started. If you want to rearrange or reorder the way elements are displayed, use XSLT."

    What is the difference between "a style sheet" and XSL(T)?

    As far as finding a XSLT implementation, Microsoft has one with OLE interface. A Perl-native one is probably superior, though.

[reply]
      Well, I cant contribute too much with regard to using XML with XSLT in perl, but I have used the two together just on the command line, using a package called sabalot, quite successfully.

      As for what you can do with XSLT, well quite a lot. For instance we were converting XML DB models into a perl object model. This involved converting XML into code, which required the use of conditional blocks, transformation, selective presentation etc. Not sure what a 'style sheet' is in XML, if its not XSLT, but XSLT has capabilities far beyond what CSS gives you in HTML. Bear in mind though that XSLT is a bit nasty in terms of syntax but thats why you use a WYSIWIG tool to write it...

      If you want to play around with a WYSIWIG XML/XSLT tool on a W32 platform then have a look at XML Stylus Studio its available free for trial. We found it usefull enough at work to buy a few dev seats worth. Other than that sablotron is a good open source command line etc version of the same thing.

      I'd be interested in how you get on with this, maybe a follow up post letting us know how you played it? Anyway, HTH

      Oops, last thought, I very seriously doubt that a Perl-Native XSLT implementation would be superior, my guess is it would be slow as hell. Use sablotron, but control it from perl. Sablotron has some new documentation on using it with Perl, I havent looked at it in detail but its here

      Yves / DeMerphq
      --
      Have you registered your Name Space?

[reply]
      A Perl-native XSLT processor does exists. Unfortunately it hasn't been fully compliant with XSLT 1.0 specs, and it is unacceptably slow. I recall someone said in perl-xml mailing list that it's even faster to spawn a Saxon process. I believe that XML::XSLT could be much better than it is now, since there are lots of very good XSLT processors written in Java, so I think it's more a choice of good algorithm and proper data structures rather than a language problem.

      I've run XSLTMark on my own, comparing the XSLT 1.0 compliance and performance of Saxon (Java), Sablotron, LibXSLT, and Xalan C++. Sablotron 0.70 - the latest version at this moment - fails on several tests, which indicates that it isn't fully XSLT 1.0 compliant, and the performance is not impressive. The rest of them - LibXSLT, Saxon, and Xalan - are fully compliant. And among these, LibXSLT is undoubtedly the speed demon. Xalan is the second.

      But if you're afraid that at some level of complexity you can't deal with XSLT alone (or it's too complicated to solve in XSLT, see Things XSLT Can't Do), you may try XML::Xalan, the perl binding to Xalan C++. It allows users to write an XSLT extension function in Perl. I know it lacks of several features, such as document validation, but currently it serves my need very well. Untested on Win32, though, just on Linux only.

[reply]
        Controlling easily from Perl and Perl extensions/callbacks whatever is what I meant by "Perl native". Sure, the whole thing's written in C with a XS binding, but the interface is Perl. As opposed to OLE, which is challenging at times and isn't designed with the Perl way of doing things. I was thinking of how much easier DBI is (in Perl syntax) than ODB.
[reply]

In Section Seekers of Perl Wisdom