Overview  Package   Task  Deprecated 

Task XMLReleaseNotes

This task enables to use the XMLReleaseNotes framework via Ant...[Description]

Definition

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

Parameters

Attribute Description Required Default
abstract Enables to define an abstract for the generated main HTML page, that will be displayed at the top of the release notes.

This is an opportunity to provide some overall explanation about the release notes themselves.

This element supports HTML tags.
No empty, by default
banner Tells whether the generated HTML pages should present an advertising footer banner for the XRN framework.
If you want to promote the framework, you should consider letting this on.
No defaults to yes. When set to no, the XRN bottom banner is not displayed
checkValidity Indicates whether the XML input release notes should be tested against its XML schema.

This enables to check that your XRN release notes are compliant with the framework (and all the more that the file is well formed).

No defaults to no. When set to yes, the release notes files are being tested validated
cSS Defines the path of the CSS file to be used within the generated HTML pages. This offers the opportunity to customize the rendered release notes layout. Copy and paste the default CSS, then modify its CSS selectors in order to customize the HTML rendering.

This file will be copied at the root of the destination directory with the name stylesheet.css.

This CSS must conform to the default CSS style sheet format.
No the default XRN CSS style sheet (present under XMLReleaseNotes/XMLReleaseNotes.css) embedded in the jar will be used
debug For internal purpose only. Triggers the debug behavior.
This feature is not supposed to be used by persons not developing for the XRN framework, unless explicetly asked for.
No default to no. Set it to yes only provided you know what you are doing!
deploy A boolean attribute that indicates whether the task just needs to deploy the XRN main resources: for instance, the default CSS style sheet will be copied, as well as the XRN XMLReleaseNotes.xsd schema file.

This is a helper that extracts all the necessary resources from the jar file. The deployed resources will be copied into the destination directory.

When enabled, no other processing than deploying the XRN framework main resources will be performed.
No defaults to no. When set to yes, the task will only deploy the XRN framework resources
destination Defines the path of the directory where all generated stuff will be generated into. No . (i.e., the current Ant buildfile basedir directory)
hTML Defines the name (and not the path!) of the main rendered HTML page.

This is the HTML page to be opened in order to browse the rendered HTML release notes.

This attribute is ignored if the expanded-rendering feature is disabled.
No defaults to XMLReleaseNotes.html
implicitlyMigrate Indicates whether implicit XRN migration should be applied if necessary. This does not stop the process once the implicit migration has been applied.

When your XRN release notes files are outdated compared to the XRN version of the Ant XRN task that you are currently using, you can ask the task to first migrate (via the integrated migration feature) your release notes, and then only, continue the standard process.

No defaults to no. When set to yes implicit migration is performed
inlineCSS Tells whether the generated HTML pages should inline the CSS content or not.

When enabled, the CSS will be embedded in the generated HTML, so that HTML the release notes is stand-alone (the CSS style sheet will not be copied in the destination directory). This is especially handy when you do not want to make a reference to another file inside the generated HTML.

No defaults to no. When set to yes, the generated page will embed the CSS content
migrate Indicates that you want to perform a migration of the XRN input release notes files from their declared XRN framework version into the current XRN version. In that case, the release notes files must be writable, since they may be overwritten.

For every XRN release note file concerned, the task will attempt to perform the necessary migration from the version of the XRN declared via the ReleaseNotes/@version attribute, into the version of the present XRN task.

When enabled, the rest of the standard processing is not performed.
No defaults to no. When set to yes, if a migration is necessary, it is performed
processor Defines the Fully Qualified Name (FQN) of the XLST TransformerFactory class that will be used for all transformations.

This will set the Java system property javax.xml.transform.TransformerFactory with the implementation of interface javax.xml.transform.TransformerFactory.

No the default implementation found in the classpath. With the Sun JRE V1.4, it appears that this Java system property is not always defined. For instance, define this property with org.apache.xalan.processor.TransformerFactoryImpl, if you are using the Xalan V2 implementation.
singlePage Tells whether a single HTML page or multiple HTML pages should be generated for the component release notes.

This is handy when you want your rendered release notes to be encompassed in a single HTML file.

Read this section for additional information.
No defaults to yes. When set to yes, only one HTML page is being generated for the release notes
useIcons
This feature is still at its early stages and is still experimental.
Indicates whether the generated HTML pages should contains icons or not.
No defaults to no
xML Defines the XRN-compliant file that describes the component release notes.

All operations will be performed on that release notes file.

See the fileset inner element.
No defaults to XMLReleaseNotes.xml, which means that the task will attempt to process this single release notes file

Parameters specified as nested elements

Element Description Required
fileSet As many occurrences of this element are allowed. Enables to define multiple XRN release notes files at the same time. In that case, the task will handle all the release notes files declared hereby. It is supposed that all provided files are XRN-compliant release notes file. If one is not, the task will fail.
When defined, the xml attribute is not taken into account.
This XML element is the Ant fileset feature. This same element is being used in the Ant copy task.
Read this section for additional information.
No
footer Only one occurrence of this element is allowed.
This element is ignored if the expanded-rendering feature is not enabled.
This footer will be displayed on multi-components HTML pages.
This element supports HTML tags.
No
header Only one occurrence of this element is allowed.
This element is ignored if the expanded-rendering feature is not enabled.
This header will be displayed on multi-components HTML pages.
This element supports HTML tags.
No
javaPlugin Only one occurrence of this element is allowed.
This is how you can provide your own plug-in when the XML transformations are over, and that the native HTML generation has also been performed.
If you want to present or add new views on the release notes data, this is your man. Just create a class that implements the org.xrn.plugin.Plugin interface, with a default public constructor. Put its byte code through this element by providing the classFQN attribute set to the class Fully Qualified Name. You have the opportunity to let this implementation out from the Ant lib directory, and indicates the classpath that enables to located and load the implementation. Yes, this class derives from the core native Path Ant feature.
If the element is not present, no Java plug-in will be executed.
No
layout Only one occurrence of this element is allowed. Defines the XSL transformation that renders into HTML the XML release notes input.

The idea is to provide an XSLT that extends the XMLReleaseNotes2HTML.xsl default rendering so as to take into account the new model information present in the input XML. This XSL will be given the same parameters as the default ones. This is part of the layout step.

Read this explanation in order to understand how to express the XSLT that should be used.

If not defined, the usual XSL transformation renderer is used.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.
No
mail Only one occurrence of this element is allowed. Enables to send an e-mail at the end of the XSL layout final transformation.

If not defined, no e-mail will be sent. Otherwise, use this usual mail built-in Ant task in order to define the e-mail inputs.

Read this some more explanation.
No
model As many occurrences of this element are allowed. Defines a additional XSL transformations to be applied on the XML input. The result of the transformation should be some XRN-compliant XML file. The XSL transformations will be applied in the same order as they are declared, from top to bottom.
Read this explanation in order to understand how to express the XSLT that should be used.

This enables to provide multiple XSLT that aggregate information coming from another XML sources. This is part of the enrichment step.

If not defined, no preliminary XSL transformation is performed on the XML input release notes files; the layout parameter is also ignored in this case.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.
No
pluginLayout Only one occurrence of this element is allowed. Defines the XSLT layout plugin that should be used when it comes to the rendering into HTML.

The idea is to provide an XSLT that extends the XRN2HTMLPlugin.xsl default rendering.

Read this explanation in order to understand how to express the XSLT that should be used.

This XSL will be given the same parameters as the default ones.

This element supports the XMLCatalog inner XML element, that acts as a URI resolver. Follow the previous link in order to understand what this is about.
No
title Only one occurrence of this element is allowed.
This element is ignored if the expanded-rendering feature is not enabled.
This title will be used on the HTML first page (the one that displays all components).

It enables to display extra personal information about the generated documentation.

This element supports HTML tags.
No
uRIResolverPath
This feature is only relevant when the XRN task jar file(s) lives outside from the Ant lib directory, and thus that you declared it via the typedef/taskdef task, with a properly defined classpath.
Indicates to Ant where the internal resources (.xsl, for the most) that are required at runtime are located. Those resources are present in the XRN Ant task jar file, so you only need to refer to this file.
Example:
 <URIResolverPath>
   <pathelement location="<the path to>/XMLReleaseNotes.jar"/>
 </URIResolverPath>
 
No
xSLTPath
This feature is only relevant when the XSLT implementation lives outside from the Ant lib directory.
Indicates to Ant where the XSLT implementation jar file(s) required at runtime are located.
No


Description

This task enables to use the XMLReleaseNotes framework via Ant.
If you need to use the XRN task, this is place of reference that exhaustively shows all features.

Version

This manual has been generated from the source code of XRN V0.19.2. This documentation is extracted from the source code, hence it should be up-to-date.

This manual just explains the Ant XRN task, but is not a documentation on the XRN framework. You will find such a documentation on the official web site of the XRN framework at http://xmlreleasenotes.free.fr.

A wrapper above XRN

The XMLReleaseNotes framework can also be used from the Ant world, thanks to this tiny wrapper task.

Declare the task

In order to use the Ant plug-in task, declare it via the

 <taskdef
   classname="org.xrn.ant.XMLReleaseNotes"
   name="XMLReleaseNotes"
 />
 
snippet. Later on, you will use the XMLReleaseNotes task.

Runtime requirements

There is a place where you will find this information back: XRN release notes, so you'd better to refer to them, in order to have fresh information. The "requirements" section of the XRN version that you are currently using should be self explanatory.

However, here are roughly the components you need at runtime in order it to work properly (at least by version 0.17.2 of the framework).

The two-phases

This task processes two steps:

  1. the enrichment operated on the XML XRN file via optional XSL transformations,
  2. the rendering of the resulting XML into HTML.
The detailed description of this feature is beyond this manual. However, let's see to what elements these two phases correspond to.

Enrichment

This first step is optional, and is handled by the inner model XML elements. You can define as many transformers that you want to.

Rendering

Two different types of rendering

The HTML renders pages can be generated by using two distinct modes, either compact or expanded.

Compact rendering

In that mode, only one HTML file is rendered per component release notes. This is a compact mode.

Expanded rendering

This mode renders the release notes in a very likely Javadoc way. This involves that a HTML page is rendered for every release of each component.

This feature is activated as soon as more one XRN file is provided to the task, or when the singlePage is disabled.

HTML supported

Some attributes or elements of the task support textual information mixed with HTML tags. Every time this is the case, the end-user is directed here.

XSLT resource

Some inner XML elements of the XRN task enable to refer to a XSLT style sheet file. When this is the case, you have the choice to use:

The attribute defined first takes precedence over the second one, in case when you define both.

Important

Here are some miscellaneous important matters.

XMLCatalog feature

This is a rather advanced feature, so, unless you use XSLT plug-in feature, you do not need to care about it.

This feature is used via in the following locations within the task:

Said shortly, the XMLCatalog nested XML element acts like a URI resolver, which is very handy when it comes to the numerous XSLT that occur at runtime.

In the previous XML blocks, you can add a single XMLCatalog inner XML element, so as to tell the XSLT transformations where to find resources according to their public ID. In that case, insert the following block:

 <xmlcatalog>
     <entity
       publicId="SomePublicID"
       location="its_actual_URI"
     />
    ...
 </xmlcatalog>
 
Use as many entity as you need.

This XMLCatalog feature has been developed in the Ant framework. This feature is also used in the Xslt/Style: do not hesitate to take a look in the previous hyperlinks, in order to understand its purpose and how it works. Moreover, there are lots of examples of usage there.

Mail feature

This task is also the official Ant Mail task, so that you can send eventually the release notes by mail. If the mail parameter is set to yes, then the generated release notes will be sent as text/html: define the traditional Ant Mail parameters, except the message, messagefile, messagemimetype, files and includefilenames.

The mail sent will contain the abstract as subject, and the content of the mail will be the generated release notes.

Example

 <XMLReleaseNotes
   xml="ReleaseNotes.xml"
 />
 
will render the HTML for the XML release notes file ReleaseNotes.xml.



Author

Edouard Mercier

Version

0.19.2