Rendering

A good reason?

One of the purpose of the XRN framework is to deliver a neutral but structured way to describe release notes. This information is well structured for a computer, however it is not very easy to read for a standard human being.

Note:

Those release notes are even tedious to initialize since you need to do that in a textual way, via an advanced XML editor. This is why a GUI is urgently needed.

A second purpose is to be able to render this information under a format that can be exploited by various actors: humans, mostly. We're going to see how this is achieved by the framework.

Into HTML

One of the first things you think of when you consider transforming the pieces of information into a human readable format, is using HTML. Because this is universal format that just requires a browser to be read (are there so many computers without browsers ?).

This is the reason why XRN was designed from the beginning to use this format, and use the CSS technology via customizable style sheets, in order to enable you to change the layout. Because the documentation generated by the famous Javadoc tool is well spread and widely understood, this was an incentive to use the same kind of format in XRN. Also because XRN fits well this format.

This format is sure not the best fitted for that, but this deserves to be standardized and should make people comfortable with.

Other formats?

At the time of this writing, the XRN framework just supports generating release notes under the HTML format. Though, this does not mean that there are no other opportunities.

It is not that hard to render the release notes under other textual format, like plain text. Because the framework is not mature enough, we did not focus on that already. The open architecture of the framework lets you define other types of rendering, as we'll see.

But instead of using numerous renderings, this would maybe be wiser to consider XSL FO instead. This was kind of a mistake to render directly HTML. A better idea would have been to generate XSL FO, and then use various renderers. If the framework becomes widely used, this is something that will be kept in mind.

Via Ant

We've already used the Ant XRN task via the provided buidlfile. As you seen in the buildfile source code, in order to use this task in your Ant buildfile, you need (like any other Ant task plug-in) to follow the two steps:

• declare the task to Ant via the taskdef task, with the FQN of the actual Ant XRN task implementation class. Call it XMLReleaseNotes for instance: this will the name of the task that will be used in order to execute it later on.

  Note:

  Since this is submitted to change, look at the buildfile to see the right value.

• run this XMLReleaseNotes task by providing the right attributes and nested XML element.

Example:

This snippet can be pasted in your Ant buildfile

<taskdef
  classname="org.xrn.ant.XMLReleaseNotes"
  name="XMLReleaseNotes"
/>
<XMLReleaseNotes
...
>
  ...
</XMLReleaseNotes>
        					

Alternatively, you can use the following snippet (instead of the previous taskdef) in order to declare the XRN task (in that case, the XMLReleaseNotes and its synonym XRN tasks are defined):

<typedef resource="XMLReleaseNotes/org/xrn/ant/task.properties"/>

Coverage

The Ant XRN task purpose is twofold:

• wrap the complex XSLT machinery that enables to render the XML release notes into HTML,
• provide helper tools that enables to handle the cycle life of this file.

Important:

By now, this machinery has only been written in Java, on the Jakarta Ant framework, but this can be achieved in different ways, on different platform. This has not been achieved yet, but this is something that we have in mind, in other to break the frontiers of the Java technology.

Note:

Some Maven integration is already in progress, in order to deliver the framework for free to Maven users...

As the framework grows and provided the Java/Ant reveals to be a good choice, dedicated Ant XRN tasks will surely be developed.

The two-phases

The task operates on two different levels:

• the enrichment of the XRN release notes files,
• the rendering of the resulting XML release notes into HTML.

Note:

A graphical schema would be very helpful in order to provide an overview.

Enrichment

This process consists in using piped XSLT in order to modify the raw input XML release notes files sequentially. The main idea is that the framework enables you to define and use XSLT style sheets that transform each XRN compliant file into another XRN compliant format (thus, using XML format output). Moreover, as many XSLT can be used, and they are supposed to be piped, the result of the previous transformation being provided as an XML input of the following transformation.

Note:

XRN already proposes a bunch of built-in XSLT model plug-ins that meets most of the basic needs. We'll cover that later on.

This stage enables to exploit pieces of information coming from outer and heterogeneous systems, like VCS, bug trackers, needs expression systems, and inject them in the release notes.

Since the XRN framework is open and extensible, you can very easily create your own XSLT. Those XSLT may even enable to automate some information injection that meet your project specificities.

Rendering

The second phase is the rendering itself, which enables various types of actors to read the wealth of information the release notes now contain. Since this rendering can be easily filtered, it is dedicated to developers, project managers, even to the business teams. We'll see how to achieve this filtering later on.

You will not describe here the details of the XMLReleaseNotes Ant plug-in task, because this is supposed to be already documented via the generated-from-Java-souce-code HTML manual.

Important:

The Ant XRN task manual is accessible in that guide on the Ant XRN task manual, accessible from the home page.

Example