AA_mallard_maplerose_sxc_989129.jpg

© Maplerose, sxc.hu

Neue Ente im Teich

Dokumentationen mit Mallard schreiben

29.07.2011 Eine einfache Syntax und der modulare Aufbau machen Mallard zur idealen Grundlage, um Dokumentationen themenbasiert zu schreiben und anschließend zu einem kompletten Handbuch zusammenzufügen.

Wenn Sie eine grafische Software entwickeln, liegt es nahe, dem geneigten Benutzer für den Fall des Falles ein Handbuch zu spendieren. Das Schreiben von Hilfetexten fällt allerdings schnell lästig, denn das übliche Docbook-Format gilt – zurecht – als kompliziert und erfordert einen beträchtlichen Lernaufwand. Das Mallard-Format gleicht zwar vom logischen Aufbau her Docbook, kommt jedoch mit weitaus weniger Tags aus und vereinfacht die Syntax erheblich.

Das Mallard-Projekt [1] ist eng verknüpft mit dem Ziel, nicht nur dem Autor Vorteile zu bieten, sondern auch dem Leser. Das Design zwingt den Schreiber regelrecht dazu, themenbasiert zu arbeiten und nicht eine Reihe von Infos in einem statischen Text unterzubringen. Wenn Sie mehr darüber erfahren wollen, wie Mallard intern funktioniert, finden Sie online [2] weitere Informationen.

Der Einstieg

Listing 1 zeigt eine minimale Mallard-Datei. Dieser Index bildet die Wurzel, auf der alle anderen Seitendateien aufbauen. Die Kopfzeilen weisen darauf hin, dass es sich um eine Anleitung handelt (guide), stilistisch um eine Aufgabe (task) und organisatorisch um einen Index (index). Letzteres ist wichtig, damit die anderen Seiten den ihnen zugedachten Platz in der Dokumentation einnehmen. Die weiteren Zeilen geben Auskunft über den Autor und die Lizenz. Nach dem kurzen Vorspann geht es dann tatsächlich um diejenigen Texte, die Sie später sehen. Mit dem Tag <section> legen Sie einen Abschnitt fest, der durchaus leer sein darf, abgesehen von der Überschrift.

Listing 1

<page xmlns="http://projectmallard.org/1.0/"
      type="guide" style="task"
      id="index">
  <info>
    <title type="text">Beispieldokumentation</title>
    <credit type="author">
      <name>Max Mustermann</name><email>max@online.de</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title>Beispielanwendung</title>
  <section id="introduction">
   <title>Einführung</title>
  </section>
</page>

Der kleine Zusatz id="introduction" im öffnenden XML-Tag sorgt dafür, dass der Parser eine Seitendatei mit dieser Kennung genau hier und nirgends anders im Hauptdokument einfügt. Den Aufbau einer solchen Seitendatei sehen Sie in Listing 2.

Listing 2

<page xmlns="http://projectmallard.org/1.0/"
  type="guide"
  id="introduction">
  <info>
    <link type="guide" xref="index#introduction"/>
    <credit type="author">
      <name>Max Mustermann</name><email>max@online.de</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title>Was ist die <app>Beispielanwendung</app>?</title>
  <p>
    Die <app>Beispielanwendung</app> ist ein Programm
    mit vielen interessanten Funktionen.
  </p>
</page>

Die dritte Zeile in Listing 2 legt die Kennung fest, welche Sie durch die Angabe eines Links in Zeile 6 noch bestätigen. Weitere Themen und Unterthemen fügen Sie auf die gleiche Weise ein.

Aus den Listings geht schon die einfache Syntax von Mallard hervor. Wenn Sie – und sei es nur für den Anfang – keinen gesteigerten Wert auf ein ausgefeiltes Aussehen der Textelemente legen, fällt der Einstieg nicht allzu schwer. Später fügen Sie bei Bedarf innerhalb eines öffnenden XML-Tags noch Stilinformationen einfügen, die die weiteren Werkzeuge dann entsprechend verarbeiten.

Hier kommt Mallard dem Anwender ebenfalls entgegen: Anstatt verschiedene zu beschreibende Oberflächenelemente durch verschiedene Tags auszudrücken (wie <guilabel>, <guimenuitem> und <guibutton> in Docbook), genügt hier das kurze und bündige <gui>. In den öffnenden Tag fügen Sie bei Bedarf später beispielsweise mit style="button" die Information ein, dass es sich um einen Knopf in der Bedienoberfläche handelt.

Außerdem haben Sie die Möglichkeit, mit dem Tag <span Informationen einzubauen, die in der Anzeige später nicht erscheinen, sich aber in vielfältiger Weise für Anweisungen an diverse Verarbeitungswerkzeuge eignen. Darüber hinaus steht es Ihnen offen, Mallard durch Elemente aus externen Namensräumen nahezu unbegrenzt zu erweitern.

Die Tatsache, dass Sie für jedes Thema und üblicherweise auch jedes Unterthema eine eigene Page-Datei anlegen müssen, verwirrt eingefleischte Docbook-Anwender zunächst: Die sind eine einzige große Datei gewohnt, die nur die Lizenzdeklaration extern vorhält, wenn überhaupt. Das Auftrennen hat jedoch einige Vorteile: Geben Sie den einzelnen Dateien aussagekräftige Namen, finden Sie später viel leichter eine Stelle, an der Sie eventuell etwas ändern, streichen oder hinzufügen wollen.

Außerdem erleichtert das Verknüpfen das Einbinden externer Dateien, selbst wenn diese von Drittanbietern stammen. Schreiben beispielsweise die Entwickler eines separat für ein Programm angebotenen Plugins einen Hilfetext und referenzieren diesen sauber als Teil der Hauptdokumentation, erscheint das externe Thema darin tatsächlich als integraler Teil, ohne dass Sie dafür nur ein einziges Zeichen im Handbuch ändern müssten. Sollte das Plugin andererseits nicht installiert sein, gibt es auf diese Weise die entsprechende Hilfeseite nicht, und der Leser des Handbuchs sucht nicht vergebens nach Funktionen, die es gar nicht gibt.

Als Autor legt Ihnen das Format nicht mehr Steine in den Weg als andere Markup-Sprachen. Einen auf die Sprache zugeschnittenen WYSIWYG-Editor suchen Sie zwar vergeblich, aber der Gnome-Standardeditor Gedit (Abbildung 1) kennt das Format als solches und natürlich dessen Eigenheiten. Ein Textschnipsel-Plugin für Gedit gibt Ihnen Tags vor und bietet schließende Tags an, wenn die öffnenden bereits vorhanden sind.

Abbildung 1

Abbildung 1: Gedit kennt Mallard schon seit Langem.

Auch der Editor Emacs erkennt die Syntax und zeigt diese korrekt an. Weiß Ihr Lieblingseditor mit Mallard nichts anzufangen, stellen Sie alternativ das Syntax-Highlighting für allgemeines XML ein. Das reicht im Grunde aus, um im Dschungel der Tags nicht die Übersicht zu verlieren.

Am Fließband

Der Quelltext alleine macht jedoch noch kein Handbuch: Sie müssen ihn erst weiterverarbeiten. Hier kassiert Mallard einen Minuspunkt gegenüber seinem heimlichen Vorbild Docbook. Außer der direkten Anzeige im Gnome-Hilfebrowser Yelp und dem HTML-Export, wobei ersterer intern auf letzterem beruht, versteht sich kaum ein Anzeigeprogramm auf Mallard.

Wenn Sie schon einmal mit Dblatex ein Docbook-Dokument in ein professionell gesetztes PDF-Dokument umgewandelt haben, enttäuscht Sie Mallard vielleicht. Zwar gibt es einen entsprechenden Konverter [3], doch die Arbeit daran kommt kaum voran. Nach dem derzeitigem Stand der Dinge hat er gewissermaßen nur eine Alibifunktion. Das ist allerdings dem Design geschuldet, das das Erstellen eines ansprechenden Druckbilds erschwert.

Bei Bedarf die Texte mittels Po-Dateien übersetzen zu können, ist in Mallard natürlich Ehrensache. Das bekannte Werkzeug Xml2po versteht sich darauf, allerdings nicht sonderlich gut. Ersatz ist aber in Sicht: Das neue ITS Tool [4] aus dem Gnome-Fundus erlaubt es nun, automatische Kommentare für die Übersetzer einzuarbeiten und nicht zum Übersetzen gedachte, feste Elemente in den Po-Dateien auszublenden.

Der Vorgänger war dabei nicht allzu wählerisch und platzierte alles in der Po-Datei – ungeachtet dessen, ob es sich um Programmcode, Befehle oder um tatsächlich zu übersetzende Inhalte handelte. Das neue Verfahren senkt die Fehlerquote in den anderssprachigen Versionen, was dem nicht eben guten Ruf von Handbüchern zugute kommt.

Gnome baut um

Noch vor nicht allzu langer Zeit war Docbook bei Gnome das Maß aller Dinge, wenn es um das Schreiben von Handbüchern ging. Doch mit Mallard änderte sich das grundlegend, wobei nicht nur die vereinfachte Syntax den Ausschlag gab. Das Aussehen der Dokumente sollte nicht mehr die Form einer Dissertation haben, sondern ein Wiki-ähnliches Layout, um das Suchen nach den gewünschten Informationen zu erleichtern. Zu den Pionieren gehörte das Chat-Programm Empathy, dessen Handbuch schon in Gnome 2.28 im Herbst 2009 im Mallard-Format vorlag (Abbildung 2).

Abbildung 2

Abbildung 2: Mit dem Empathy-Handbuch betrat Gnome 2.28 neues Terrain in Sachen Mallard.

Hinter der Fassade gab es zudem eine auf den ersten Blick eher unscheinbare Modifikation: Neu zu schreibende Dokumentationen sollen fortan unter einer Creative-Commons-Lizenz stehen statt wie bis dahin unter der GFDL. Das erleichtert das Weiterverbreiten der Texte, da sich beispielsweise auch die Dokumentationsteams von Fedora und Ubuntu für diese Lizenzen entschieden haben. Somit steht und dem Austausch und dem gegenseitigen Einbinden von Dokumenten nichts im Weg.

Das Ändern der Lizenz setzt außerdem voraus, dass alle bisherigen Autoren dieser zustimmen müssen, falls das Projekt bestehende Inhalte weiterverwenden will. In vielen Fällen ist dies mit vertretbarem Aufwand nicht möglich. Aber so stellen die Maintainer eben sicher, dass veraltete Inhalte gar nicht erst einfließen. Ganz nebenbei erzwingen Sie eine themenbasierte Gliederung.

Derzeit liegen allein auf den offiziellen Gnome-Servern bereits 36 Handbücher im neuen Format vor, Tendenz steigend. Externe Projekte wie Déjà Dup [5] und SimpleScan [6] haben Mallard ebenfalls adaptiert. Ab Gnome 3.2 spielt es für das Einbinden externer Hilfeseiten sogar keine Rolle mehr, unter welchem Installationspräfix Hauptprogramm und Plugin installiert sind. Eine in ~/.local installierte Seite gibt der Hilfebrowser dann ebenso korrekt aus wie eine, Die sich in /usr befindet. Das ermöglicht es, ein Plugin ohne die Rechte des Systemverwalters im Home-Verzeichnis zu installieren – komplett mit korrekt integrierter Hilfeseite.

Insgesamt betrachtet, fungiert Gnome durchaus als Motor hinter Mallard, wenngleich Mallard kein reines Gnome-Projekt ist, sondern einen universellen Anspruch hat.

Ausblick

Aufgrund der genannten Einschränkung vermag Mallard auf lange Sicht Docbook nicht zu ersetzen, sondern bestenfalls zu ergänzen. Die Entwickler folgen zwar recht zeitnah den Rufen der Benutzer, wenn es um neue Features geht, aber das Einsatzgebiet beschränkt sich wohl auch weiterhin auf das Darstellen am Bildschirm. Ob es jemals einen brauchbaren LaTeX/PDF-Export gibt, steht in den Sternen. Um technische Dokumente für die Druckausgabe zu schreiben, kommen Sie um Docbook kaum herum – es sei denn, Sie nutzen ohnehin schon LaTeX. Geht es aber um themenbasierte Benutzerhandbücher, die dem Leser zudem noch per Definition ein vertrautes Wiki-Layout bieten, ist Mallard erste Wahl.

Um die Zukunft des Projekts braucht sich zudem niemand Sorgen zu machen. Die Entwickler sind sehr aktiv: Kaum haben Sie ein neues Feature implementiert, nehmen Sie schon das nächste schon in Angriff. Zur Zeit arbeiten sie intensiv an Glossaren [7], also an der Möglichkeit, Begriffe im Text hervorzuheben und automatisch mit einer Begriffserklärung zu verknüpfen. Interessant ist die Tatsache, dass dies auf die Initiative eines kommerziellen Benutzers zurückgeht – das zeugt von der inzwischen recht breiten Akzeptanz des Formats.

Bleibt zu hoffen, dass Mallard in naher Zukunft auch in andere Projekte so einfließt, dass es sich zu mehr entwickelt als als nur einer Machbarkeitsstudie. Das Desktop-Projekt XFCE ist hier bereits auf dem richtigen Weg [8]. Zwar gibt es derzeit nur für die XFCE-Leiste und das Terminal Mallard-Handbücher, und die Dateien werden direkt ohne Umweg über einen Hilfebrowser in HTML bereitgestellt – aber der Grundgedanke der themenbasierten Hilfe bleibt davon unberührt. 

Glossar

WYSIWYG

"What You See Is What You Get". Bezeichnet einen Editor, der genau das anzeigt, was später in der Bildschirm- oder Druckausgabe zu sehen ist.

Infos

[1] Mallard-Projekt: http://projectmallard.org

[2] Deutsches Mallard-Handbuch: http://mariobl.fedorapeople.org/Mallard/

[3] Transformation nach LaTeX: http://gitorious.org/+projectmallard/projectmallard/mal2latex

[4] ITS Tool: http://itstool.org

[5] Déjà Dup: http://launchpad.net/deja-dup/

[6] SimpleScan: http://launchpad.net/simple-scan

[7] Shaun McCance zu Glossaren: http://blogs.gnome.org/shaunm/2011/07/07/mallard-glossaries/

[8] Mallard für XFCE: http://wiki.xfce.org/documentation

Tip a friend    Druckansicht beenden Bookmark and Share
Kommentare