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

LinuxCommunity kaufen

Einzelne Ausgabe
 
Abonnements
 

Ähnliche Artikel

Kommentare

Infos zur Publikation

LU 11/2014: VIDEOS BEARBEITEN

Digitale Ausgabe: Preis € 4,95
(inkl. 19% MwSt.)

Mit der Zeitschrift LinuxUser sind Sie als Power-User, Shell-Guru oder Administrator im kleinen Unternehmen monatlich auf dem aktuelle Stand in Sachen Linux und Open Source.

Sie sind sich nicht sicher, ob die Themen Ihnen liegen? Im Probeabo erhalten Sie drei Ausgaben zum reduzierten Preis. Einzelhefte, Abonnements sowie digitale Ausgaben erwerben Sie ganz einfach in unserem Online-Shop.

NEU: DIGITALE AUSGABEN FÜR TABLET & SMARTPHONE

HINWEIS ZU PAYPAL: Die Zahlung ist auch ohne eigenes Paypal-Konto ganz einfach per Kreditkarte oder Lastschrift möglich!       

Tipp der Woche

Schnell Multi-Boot-Medien mit MultiCD erstellen
Schnell Multi-Boot-Medien mit MultiCD erstellen
Tim Schürmann, 24.06.2014 12:40, 0 Kommentare

Wer mehrere nützliche Live-Systeme auf eine DVD brennen möchte, kommt mit den Startmedienerstellern der Distributionen nicht besonders weit: Diese ...

Aktuelle Fragen

Artikelsuche
Erwin Ruitenberg, 09.10.2014 07:51, 1 Antworten
Ich habe seit einige Jahre ein Dugisub LinuxUser. Dann weiß ich das irgendwann ein bestimmtes Art...
Windows 8 startet nur mit externer Festplatte
Anne La, 10.09.2014 17:25, 4 Antworten
Hallo Leute, also, ich bin auf folgendes Problem gestoßen: Ich habe Ubuntu 14.04 auf meiner...
Videoüberwachung mit Zoneminder
Heinz Becker, 10.08.2014 17:57, 0 Antworten
Hallo, ich habe den ZONEMINDER erfolgreich installiert. Das Bild erscheint jedoch nicht,...
internes Wlan und USB-Wlan-Srick
Gerhard Blobner, 04.08.2014 15:20, 2 Antworten
Hallo Linux-Forum: ich bin ein neuer Linux-User (ca. 25 Jahre Windows) und bin von WIN 8 auf Mint...
Server antwortet mit falschem Namen
oin notna, 21.07.2014 19:13, 1 Antworten
Hallo liebe Community, Ich habe mit Apache einen Server aufgesetzt. Soweit, so gut. Im Heimnet...