Release-notes plugin

Parent: DITA-OT Plugins

org.doctales.release-notes is a plugin for the DITA-OT that extends the org.dita.pdf2 plugin to automatically create release-notes lists or tables from the DITA 1.3 release-management domain elements. If you have a question, go to the questions section and ask the DOCTALES team. If you have found a bug or want to request a feature, please raise an issue.

To learn more about the release-management domain, read the official DITA 1.3 release management domain feature article.


You can directly install the plugin to the DITA-OT by calling the dita command with the --install parameter and point it to the that contains the latest changes checked in on the master branch on the GitHub repository.

dita --install

Using the Plugin

Add a <booklist type="change-historylist"/> element as a child of a <booklists> element on your <bookmap>, for example:

        <booklist type="change-historylist"/>

Add <change-list> elements to your DITA Maps and DITA Topics to reflect your changes. It is mandatory, that you use the <change-completed> elements to clarify, when a change has been made. This date is needed to calculate, whether the change has been made before or after a specific book release date.

        <change-person>John Smythe</change-person>
            <change-request-system>BugTracker Pro</change-request-system>
        <change-summary>Description of new foo feature added.</change-summary>
        <data>New feature addition for v3, originally relating from a UI change request that came in from a customer</data>

You need to specify the creation and revision dates of the book in a <critdates> element on your <bookmap>.

    <created date="2015-01-01"/>
    <revised modified="2015-02-01"/>
    <revised modified="2015-03-01"/>
    <revised modified="2016-04-01"/>

Publish a pdf2 based PDF. You can optionally set the property to table to publish the changes in a table format, for example:

dita --input your.ditamap --format pdf

Using the Plugin with custom pdf2 based Plugins

If you like to use this plugin with custom pdf2 based plugins that use a shell XSL file which is passed to the DITA-OT by using the args.xsl.pdf extension point, you need to add some additional <xsl:import> statements to make this plugin work correctly.

This is, for example, the case, when you have generated your plugin using the dita-generator.

At the top of your shell XSL add:

<xsl:import href="plugin:org.dita.pdf2:xsl/fo/topic2fo.xsl"/>

At the bottom of your shell XSL add:

<xsl:import href="plugin:org.doctales.release-notes:xsl/fo/root-processing.xsl"/>
<xsl:import href="plugin:org.doctales.release-notes:cfg/fo/attrs/release-notes.xsl"/>
<xsl:import href="plugin:org.doctales.release-notes:xsl/fo/release-notes.xsl"/>

Because you now have added a hard dependency to org.doctales.release-notes, you should explicitely name it so by adding the following <require> element to your plugin.xml:

<require plugin="org.doctales.release-notes"/>

Sample Files

You can test the plugin with this simple project. Please investigate the elements <change-historylist>, **<critdates>** and <booklist> in the bookmap and the topic.

  1. Extract the ZIP archive.

  2. Publish using the dita command.

    dita --input release-notes.ditamap --format pdf2