Tuesday, April 11, 2006

Changelog

Carsten suggests that the changelog should be in XML. So, in the spirit of avoiding the work I have to do to pass my degree, I hacked up a little XML changelog, with some XSL to turn it into HTML. The tarball is here. Untar it, and then run either
xsltproc changelog.xsl changelog.xml > changelog.html

for changes by app, or
xsltproc changelog-by-type.xsl changelog.xml > changelog.html

for changes by type.

It's just a proof-of-concept, so there are no doubt plenty of ways to improve it, but it's quite an elegant solution, and in purely technical terms, is probably the Right Way(TM) to do it (ie, XML changelog with XSL to convert it to HTML). However, the amaroK guys (I'm told) have a ruby script that produces HTML from a simpler, ad hoc changelog file format. Though lacking the technical elegance of the XML solution (he says, without having seen said ruby script), it might turn out to be the better option, since a simpler file format might mean more people adding to the file, and therefore a better changelog. Plus, I don't know ruby, so no one can ask me to maintain it :-).

Oh, and since I mentioned XSL, does anyone know of some kind of "templating" system for it, so I could write (say)
if condition {
...
}

instead of the fairly unpleasant
<xsl:if test="condition"> 
...
</xsl:if>

or the far, far worse way of sending parameters (arguments) to templates (functions). The basic ideas of XSL (templates, applying them with apply-templates) are really nice, but why oh why did they have to make it an XML variant? It's just nasty to look at, and seems like a particularly egregious case of "when all you have is a hammer...". OK, rant is over; we now return to your scheduled programming (and lots of comments telling me that I misused "egregious").

6 Comments:

At 8:54 AM, Blogger randomice said...

Beside the fact that I had to create a blog (and not only a simple account) within blogger.com just to submit a comment to your post the comment comes here...

If your condition is a XPath expression you could setup a template selecting the last expression part and call it with a mode. Then enter in your apply-templates tag the expression and the mode tag. If your expression doesn't result in a node you could select a node (".") and write the expression into the node-condition.

randomice

 
At 10:21 AM, Blogger Philip Rodrigues said...

Thanks for the suggestion. I didn't really explain myself very well though. I was thinking of something much more general, that would allow me to write XSL files that would look like a "program", rather than an XML file (simply because it would look nicer, and hopefully would be easier to read). So basically, some kind of "program"->XSL script. Maybe no one else thinks XSL looks ugly, so no one has implemented something like this. I might look into whether it's possible one day.

 
At 10:22 AM, Blogger Philip Rodrigues said...

Oh, and a little searching around suggests that XQuery does something similar - it has "program-like" syntax, and can do transformations, although it uses different models to XSL. Something else to look into when I have time.

 
At 3:11 PM, Blogger Thomas Zander said...

Using XML is great; but naturally having XML is not really a plus for writability unless you actually write a (small) GUI application that allows devs to add/maintain their changelog.

Otherwise you can just as well write the php, don't you think so?

 
At 4:35 PM, Blogger randomice said...

if you are using cvs as version control you could use the integrated comment system (and a GUI of your choice) and http://freshmeat.net/projects/cvs2cl.pl/ as a generator for a human readabe changelog file.

 
At 9:31 PM, Blogger Philip Rodrigues said...

Thomas: yes, I think you're probably right that ease of writability (so that developers will *use* it) is more important than technical elegance. Pity, though - I quite like my XSL :-).

randomice: KDE's using SVN now, instead of CVS, but I suppose that similar tools exist for SVN. I guess Carsten has looked at some of them, since he's doing most of the changelog work at the moment.

 

Post a Comment

<< Home