Schnell mal ein kleines Diagramm, Kästchen mit Pfeilen, in den Text einfügen? Extradafür jetzt die Grafiksoftware hochfahren? Das Ditaa Plugin für Maven macht aus schnell im Text hingeworfenen ASCII-Zeichnungen Bilder, die im fertigen Dokument erscheinen.

ASCII Art wird heutzutage nicht mehr so schief angesehen, wie noch vor etlichen Jahren. Liegt es nur daran, dass das umstandslose Malen mit Buchstaben als agile Technik gilt, und damit im Trend liegt, oder ist ASCII Art einfach retro, so wie auch Tron? Beides findet bestimmt seine Fürsprecher.

Wie dem auch sei, Tatsache ist dass es mit der ditaa-Bibliothek von Stathis Sideris eine Kommandozeilen-Anwendung gibt, die auf die Generierung von Diagrammen aus ASCII-Zeichnungen spezialisiert ist. Zur Demonstration: aus einem Diagramm wie


 +---------+	    /-------\
 | {d}     |        |       |
 | ASCII-  | --*    | Bild  |
 |  Text   |   |    | (PNG) |
 | cBLU    |   *->  | cYEL  |
 +---------+        \-------/

wird eine Bilddatei (PNG) erstellt, die so aussieht:

Beispiel für ein via Ditaa generiertes Diagramm

Beispiel für ein via Ditaa generiertes Diagramm

An diesem Beispiel kann man sehen, was Ditaa am Besten kann: die beliebten „Kästchen mit Pfeilen-Diagramme“ malen. Man kann seine eigenen Formen malen oder vordefinierte Schablonen nutzen, mit oder ohne Farben etc etc. Die Details werden in der ditaa-Dokumentation erläutert. Es sind aber nicht viele, die Angelegenheit soll ja einfach bleiben.

Einfachheit ist das Motto. Sobald die Diagramme nämlich kompliziert werden, nimmt man besser spezialisierte Anwendungen zur Hand. Um schnell mal Zusammenhänge zu visualisieren, ist Ditaa aber gut geeignet. (Um diese Aussage auf ihren Wahrheitsgehalt zu prüfen, einfach mal die Webfassung ausprobieren.)

Warum nun ein Maven Plugin für Ditaa? Ganz einfach, um die Generierung von Ditaa-Grafiken in XML-basierten Herstellungsprozess von Dokumenten einzubinden. Das Plugin wurde so gestaltet, dass man es einfach in einen bestehenden oder neuen Maven-Prozess einbinden kann. Außer der Deklaration des Plugins in der Projektatei (pom.xml) sind keine besonderen Schritte nötig. Die Installation und Durchführung wird wie gewohnt von Maven erledigt.

Die Funktionsweise des Maven Ditaa Plugins ist denkbar einfach, es:

  • liest eine XML-Datei ein

  • sucht die durch ein Suchmuster identifizierten Elemente mit
    Ditaa-Inhalten

  • transfomiert die gefundenen Inhalte einzeln in PNG-Dateien, die im konfigurierten Ausgabeverzeichnis abgelegt werden

Die so erstellten Bilddateien können dann in späteren Phasen in das
Dokument inkludiert werden, etwa über XSLT.

Das Plugin einbinden

Das Plugin ist im Maven-Repositorium von Textmulch erhältlich, das sie in ihre Einstellungs- oder Projektdateien übernehmen müssen. Dieses Repositorium ist unter http://maven.textmulch.de/releases zu finden. Die Seite http://projekte.textmulch.de/maven-ditaa-plugin/ enthält die Dokumentation.

Die Einbindung des Plugins in einen Arbeitsablauf könnte so aussehen:

<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>
      ...

Das Plugin unterstützt derzeit nur ein Ziel, single, das eine
einzelne XML-Datei bearbeitet. Wenn keine Phase angegeben wurde, nimmt es die process-sources als Standard an. Möchte man mehrere Dateien bearbeiten oder mit verschiedenen Suchmustern arbeiten, können einfach mehrere execution Abschnitte hintereinander gestellt werden.

Das Plugin konfigurieren

Das Plugin wurde für die Nutzung mit XML-Dateien konzipiert. Schreibt man also seine Dokumente in einem Format wie zum Beispiel DocBook oder DITA kann man das Plugin nutzen. Für andere Zwecke sollte man eher das Original bemühen. In der Folge wird die Nutzung mit DocBook-Dokumenten erläutert.

Die zu analysierende Datei wird im Abschnitt configuration
angegeben, als Parameter xmlFile:

...
 </goals>
   <configuration>
     <xmlFile>src/main/xml/mein-dokument.xml</xmlFile>
...

Als nächstes muss ein Suchmuster für die zu verarbeitenden Ditaa-Inhalte deklariert werden. Da XML-Dokumentenschemata gleichförmig aufgebaut sind, sollte eines im Normalfall reichen. Als Beispiel gehen wir davon aus, dass unsere Kästchen-mit-Pfeilen in einer DocBook-Datei folgendermaßen definiert wurden:

...
 <mediaobject xml:id="a1" role="preprocess">
   <textobject>
     <literallayout class="monospaced" language="ditaa">
 +----------+          +---------+
 |          |          |         |
 |  Text    | ------>  |  Bild   |
 |          |          |         |
 +----------+          +---------+
     </literallayout>
  </textobject>
 </mediaobject>
 ...

mediaobject Elemente enthalten bei DocBook ein oder mehrere Ausführungen desselben Inhalts. Man kann dort zum Beispiel Bilddateien in verschiedenen Formaten angeben, beispielsweise eine PNG-Datei für die Webfassung eines Dokuments und eine SVG-Datei für die Druckfassung. Als letzte Rettung kann man auch eine Textfassung angeben, die dann zum Einsatz kommt, wenn Bilder nicht angezeigt werden können.

Im Falle des obigen Beispiels habe ich die Textfassung (textobject) für die Ablage der ASCII-Grafik genutzt. Um die Grafik für die Transformation zu kennzeichnen, habe ich einfach das Attribut language=“ditaa“ verwendet. Sollten noch andere textobject Elemente vorhanden sein, die dieses Attribut nicht haben, so werden sie nicht transformiert.

Um die Transformation zu bewerkstelligen, definiert man folgendes
Suchmuster im Konfigurationsabschnitt:

...
</goals>
   <configuration>
      <xmlFile>src/main/xml/mein-dokument.xml</xmlFile>
       <xpathSelector>//db:literallayout[@language='ditaa']</xpathSelector>
       <namespaces>
          <db>http://docbook.org/ns/docbook</db>
       </namespaces>
...

Das Suchmuster ist ein XPath-Ausdruck. Da DocBook 5 mit einem Namensraum versehen ist, muss dieser ebenfalls definiert werden. Normalerweise reicht dabei der Namensraum des Zieldokuments. Nur in Fällen, in denen mehrere Schemata gemischt werden, zum Beispiel DocBook mit MathML, könnte es nötig sein, mehrere Namensräume anzugeben.

Mit dieser Deklaration wüsste das Plugin also, welche Datei zu durchsuchen ist, und wie zu transformierenden Blöcke zu finden sind. Bleibt die Frage, wohin mit den generierten Bilddateien? Das Verzeichnis dafür wird im Element outputDir definiert.

 ...
 </goals>
    <configuration>
      <xmlFile>src/main/xml/mein-dokument.xml</xmlFile>
      <xpathSelector>//db:literallayout[@language='ditaa']</xpathSelector>
      <namespaces>
          <db>http://docbook.org/ns/docbook</db>
      </namespaces>
      <outputDir>media</outputDir>
    </configuration>
...

Dabei handelt es sich um einen Verzeichnisnamen. Dieses Verzeichnis
wird von Maven unterhalb von target/generated-resources angelegt.

Damit wäre die benötigte Konfiguration beendet. Alle anderen Parameter sind optional. Nach einem Maven-Durchlauf würde man im Verzeichnis target/generated-resources/media eine Datei mit dem Namen a1.png vorfinden. Woher kommt der Name? Das Plugin benennt die Dateien nach der XML-ID (xml:id) des Elementes in dem das ASCII-Diagramm enthalten war, oder einem seiner Eltern-Elemente. Findet es keine
XML-ID, wird eine Fehlermeldung erzeugt.

Der Name der generierten Datei kann insofern geändert werden, als das man Prä- und Suffixe angeben kann. Diese und alle anderen Parameter sind in der Dokumentation aufgeführt.