Good title, eh?
But really, it seems like a lot of interesting buzz words were thrown together to create a leet-looking tagline and yes, that is my original intention.
On the other hand I really had to do with all those buzz words, simply because I was too lazy to start up Doxygen… You see, Torque GameBuilder(or short TGB) didn’t use to have very good documentation or rather the function and class reference was always at least a little bit obsolete, so when I needed a good and fast-loading reference, I preferred my self-created .chm file over GarageGames’ pdf reference - which was also awkward to navigate in. TGB has console functions that output all console functions and classes in doxygen-friendly C++-parser compatible data and you can feed that to doxygen and create a nice reference from it, so that is pretty simple job and gives you a very useful custom reference nevertheless.
But as it comes I’m now using Torsion (a nice little IDE for TorqueScript) and it has its own way of extracting the symbol information from TGB and storing it in an .exports file, which is nothing else but a renamed .xml file. XML stands for Extended Mark-up Language and is the generic big brother of HTML, if you haven’t heard of it.
Knowing this and being in dire need of a new reference file, I thought “Heck, I’m too lazy to take the 10 minutes and 5 relatively-easy steps to create my usual doxygen documentation for the new release - no, I’m somehow going to use the XML data to create my documentation! And although I don’t know anything about XML in general or any tools for working with it, it certainly will be a lot more entertaining, time-saving and fun than the doxygen way!”.
Well, sometimes I’m as dumb as you can get - but not this time! Yes, it drained all my resources for half a day and yes, eventually I started up doxygen and did it the usual way, but… - ok, lets rephrase that: Although I haven’t been able to use it productively after all, I’ve learnt a lot and it certainly will help me some other time in my life. *puh*
As I’m owning Visual Studio .NET, I was convinced that it would offer some way to edit XML data and represent it in a human-readable way. I’ve used Torsion’s exports xml from a free TGB game (you can download it from www.garagegames.com) called Marble Tactices and here is a little excerpt:
<class>
<name>ActionMap</name>
<base>SimObject</base>
<method>
<name>bind</name>
<args> device, action, [modifier spec, mod...], command </args>
</method>This isn’t exactly readable and after opening it in VS.NET I spend a long time trying to figure out how to control its representation. After approximately half an hour I stumbled over the XML stylesheet language or more correctly: XML stylesheet language transformations (XSLT).
Here’s the same excerpt from above after it has been transformed by one of my XSLT files (or rather by msxsl with one of my XSLT files specified as stylesheet):
ActionMap SimObject
Methods
- bind( device, action, [modifier spec, mod…], command )
XSLT is an XML-based format that can be used to describe the conversion from one XML dataset to another. HTML or rather so-called well-formed HTML(HTML that adheres to the XML standard) can thus be seen as the output dataset and consequently you can use XSLT to describe the conversion process that transforms the content of a certain type of XML files into concise and human-readable data (human-readable as in “pleasant to the reader’s eye”).
Microsoft’s help is very neat and I only took me half an hour to have the first basic version working and it probably took longer to learn HTML and CSS (knowledge which I haven’t actually used for my final PoC) than to understand XSLT as concept thanks to very good examples and good documentation. Talking about documentation, if you need to learn HTML, XML, CSS or any other web-related standard, W3C is the best place to find specifications and help.
Well, maybe it’s just me but it’s a lot easier to learn something new comprehensively if you read the specs rather than some whacky tutorials for beginners that you can find on the net everywhere…
Anyway, XSLT is great, great and again great like a lot of things that have to do with XML since they are very easy to use. XML really seems like a good way to go, since there are many nice generic tools available for it and one doesn’t have to reinvent the wheel all the time.
If you find time to look at my XSLT “code” and the output it’s capable to create, you’ll realize what a time-safer it could become, if XML becomes more widely used (in games programming).
Writing all 3 XSLT PoCs/tests took me a bit over half a day and finding, learning and getting mktree to work properly took one third of that time, so you see that XSLT really has got a nice learning-curve. For those who don’t know mktree, it is a free javascript library that you can use the create tree structures in your HTML/DHTML files.
You can find and download my Torsion exports -> HTML XSLT example (3 proofs of concept) here. BTW Everything else of importance is explained in the readme.txt.
Enjoy and stay tuned,
Andreas Kirsch