The Ditaa Plugin is used to generate graphics files from ASCII diagrams contained in XML files. Its main purpose is to help authors working with XML documentation formats like DocBook to include simple diagrams in their documents without having to use graphics software.
This plugin is a simple wrapper around the ditaa ("DIagrams Through Ascii Art") utility created by Stathis Sideris. See http://ditaa.sourceforge.net/ for information about the syntax and the meanings of parameters.
The Ditaa Plugin currently includes version 0.9 of ditaa.
A simple example for a ditaa diagram block in a XML document would look like this:
...
<mediaobject xml:id="a1" role="preprocess">
<textobject>
<literallayout class="monospaced" language="ditaa">
+----------+ +---------+
| | | |
| Text | ------> | Bild |
| | | |
+----------+ +---------+
</literallayout>
</textobject>
</mediaobject>
...Processing this example with a configuration like
...
<plugin>
<groupId>de.textmulch</groupId>
<artifactId>maven-ditaa-plugin</artifactId>
<executions>
<execution>
<id>ditaa single</id>
<phase>generate-sources</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<xmlFile>src/main/xml/ditaa-test1.xml</xmlFile>
<xpathSelector>//db:literallayout[@language='ditaa']</xpathSelector>
<namespaces>
<db>http://docbook.org/ns/docbook</db>
</namespaces>
<outputDir>media</outputDir>
<roundCorners>true</roundCorners>
</configuration>
</execution>
</executions>
</plugin>
... would result in a PNG file like
The Ditaa Plugin makes no assumption about the kind of documention format used, DocBook, TEI, whatever. The basic requirements are:
It is assumed that all ditaa diagrams in the source file can be selected with one XPath expression, which must be configured in the configuration element xpathSelector. If the source document uses namespaces these must be declared, too.
For example: DocBook 5.0 uses the default namespace http://docbook.org/ns/docbook. To select an element in a DocBook file this namespace must e delared like
<namespaces>
<db>http://docbook.org/ns/docbook</db>
</namespaces>The abbreviation of the namespace, in this case db, can then be used in the XPath expression to select all DocBook 5 literallayout elements in the source file with attribute language='ditaa'.
<xpathSelector>//db:literallayout[@language='ditaa']</xpathSelector>
All selected diagrams will be stored as PNG files in the directory specified by the configuration element outputDir. The name of the file will be the ID of the XML element with the diagram content. If that element has no ID the plugin will search through the parent elements until it finds one. If no ID can be obtained the plugin will signal an error.
Example:
...
<mediaobject xml:id="a1" role="preprocess">
<textobject>
<literallayout class="monospaced" language="ditaa">
+----------+ +---------+
| | | |
| Text | ------> | Bild |
| | | |
+----------+ +---------+
</literallayout>
...Here the element with the diagram content doesn't contain an ID, so the plugin iterates through the parent elements until it finds the mediaobject element with ID a1. The diagram will therefore be stored as a1.png.
The file names can be modified by specifying pre- or suffixes. See the goal description for more.
The ditaa page lists several parameters. Most of them can be specified in the configuration. See the goal description for more.
