Der WYSIWYG-Editor AsciidocFX vereinfacht und beschleunigt das Schreiben von Dokumentationen beachtlich.

Asciidoc und dessen Nachfolger Asciidoctor sind ausgereifte und ausgefeilte Formatierungssprachen, die das Erstellen von komplexen Dokumentationen erlauben, einschließlich Büchern, Webseiten, Manpages oder Ähnlichem. Da die Dokumente auf Klartextdateien basieren, genügt zum Schreiben normalerweise ein Texteditor.

Diese Arbeitsweise ist ausgesprochen beliebt und schnell, da sie erlaubt, alle schon früher einmal entwickelten Techniken beizubehalten, wie etwa den Einsatz von Makros im Editor, Snippets, Syntax-Highlighting und andere Komfortfunktionen. Der Nachteil liegt darin, dass es kein WYSIWYG gibt, was spätestens beim Überarbeiten und der Fehlerkorrektur die Arbeit mühsam macht.

Genau diese Bresche füllen Editoren wie AsciidocFX [1]. Zum einen erlauben sie ein einfaches Editieren der Dokumente, sind aber auch zum Schreiben längerer Passagen oft noch schnell genug. Ob sie wirklich den bewährten Texteditor verdrängen können, hängt von den Vorlieben des Autors und den Anforderungen des aktuellen Projekts ab.

Asciidoc basiert intern auf einer (X)HTML-Konstruktion, was AsciidocFX ausnutzt. Als Ausgabeformate unterstützt es derzeit neben verschiedenen HTML-Derivaten und darauf aufbauenden Formaten wie EPUB auch DocBook(45), LaTeX, Slidy, WordPress und Manpages. Bei Asciidoctor kommt durch spezielle Backends noch PDF hinzu.

Im Prinzip besteht AsciidocFX aus zwei Komponenten, einem relativ einfachen Texteditor und einem Browser, die es jeweils in einem Fenster nebeneinander anzeigt. Intern sind beide miteinander gekoppelt: Ein Mausklick in eines der Fenster bewegt automatisch den Inhalt des anderen an die entsprechende Position. Genau diese Funktion macht AsciidocFX so interessant: Sehen Sie einen (Tipp-)Fehler, lässt er sich direkt korrigieren. Ebenso ändern Sie ohne Umwege Formatierungen, Bilder und Tabellen oder Hyperlinks. Als ganz besonderes Feature unterstützt AsciidocFX das Erzeugen von Diagrammen und anderen Asciidoc-spezifischen Strukturen.

$ wget https://github.com/asciidocfx/AsciidocFX/releases/download/v1.7.3/AsciidocFX_Linux.tar.gz
$ sudo tar xzf AsciidocFX_Linux.tar.gz -C /opt
$ /opt/AsciidocFX/AsciidocFX

Überblick

Nach dem Start zeigt sich AsciidocFX schlicht (Abbildung 1). Voreingestellt zeigt es drei Bereiche: Ganz links wählen Sie über Reiter aus, welche grundlegenden Informationen zum aktuellen Projekt es anzeigen soll. Im Reiter Workdir wählen Sie einen Ordner als Arbeitsverzeichnis aus. Damit legen Sie das aktuelle Projekt fest. Alternativ zeigt Ihnen Outline die derzeitige Gliederung des aktuellen Projekts; unter Recent erhalten Sie eine Liste der zuletzt geöffneten Projekte. Bei Bedarf passen Sie die Breite dieses Fensterbereichs mit der Maus an. Ein Doppelklick auf den aktuellen Reiter schließt den Bereich und erweitert damit den Platz für die beiden anderen Teilbereiche.

Abbildung 1: AsciidocFX startet: Hinter der schlichten Oberfläche verstecken sich eine Vielzahl von Funktionen.

Über dem Workdir-Bereich befinden sich vier Schaltflächen zum Wechsel des Arbeitsverzeichnisses, für den Wechsel zum übergeordneten Ordner, zum erneuten Einlesen des aktuellen Verzeichnisses und zum Aufruf eines Menüs für verschiedene Funktionen. Das Ausklappmenü enthält zahlreiche nützliche Funktionen: Asciidoc Cheatsheet öffnet ein neues Textfenster mit einer automatisch geladenen Asciidoc-Referenzdatei. Sie zeigt viele typische Formatierungen sowohl im Quellcode als auch als HTML-Ausgabe.

Über die Option Sample Book erstellen Sie alle nötigen Dateien für ein umfangreiches Buchprojekt. book.adoc dient dabei als Manteldatei, die das gesamte Buch über import:: kapitelweise strukturiert aus externen Dateien lädt. bibliography.adoc zeigt, wie Sie Zitate oder Literaturverweise aufbauen und präsentieren. chapter-1.adoc und weitere derartige Dateien demonstrieren den Aufbau von Kapiteln anhand des Cheatsheets. In dedication.adoc finden Sie eine einfache Widmung, index.adoc baut ein Stichwortregister auf, glossary.adoc ein Glossar und colophon.adoc enthält ein Colophon (Informationen zum Aufbau des Buchs).

Bug Report, Community Forum und Gitter Chat dienen zur Kommunikation des Anwenders mit den Entwicklern beziehungsweise der Community. Die letzten beiden Menüpunkte Github page und Version 1.7.3 verweisen auf die vorliegende Programmversion.

Fensterbereiche

Der mittlere Fensterbereich stellt einen Texteditor zur Verfügung, der alle Standardfunktionen unterstützt, wie Kopieren, Ausschneiden, Einfügen und so weiter. Eine Werkzeugleiste darüber bietet die üblichen Funktionen zum Laden und Speichern der aktuellen Datei sowie für Formatierungen. Jedes neue Dokument zeigt AsciidocFX in einem separaten Reiter an. Mit [Strg]+[F] stoßen Sie eine Suche an. Wichtig sind auch die Zeilennummern, die an der linken Seite des Textfensters erscheinen, etwa um Fehlermeldungen zuzuordnen.

Rechts neben dem Textbereich befindet sich das Ausgabefenster von AsciidocFX. Es zeigt die HTML-Umsetzung des Codes im aktiven Textbereich. In der Werkzeugleiste oberhalb dieser Vorschau legen Sie über HTML, PDF, Ebook und Docbook die Backends fest, mit denen die Ausgabe erfolgen soll. Die Buttons dienen als Mini-Menü und bieten jeweils die Funktionen Save, Save as sowie gegebenenfalls weitere Optionen für das jeweilige Ausgabeformat. Browser startet einen externen Webbrowser und zeigt die aktuelle Datei darin an. Dazu muss der Browser Javascript unterstützen.

Rechts an diesem Bereich gibt es wieder eine Reihe von Reitern: Voreingestellt ist die Vorschau (Preview), über Settings ändern Sie die Einstellungen des Programms. Nicht nur damit, sondern auch in vielen anderen Aspekten erinnert AsciidocFX an Gummi, eine dynamische Entwicklungsumgebung für LaTeX [3].

Fehleranalyse

Drei wichtige Details finden sich noch am unteren Fensterrand: Terminal öffnet einen entsprechenden Bereich (Abbildung 2), in dem die Standard-Shell des Systems im aktuellen Arbeitsverzeichnis startet. Das erlaubt beispielsweise, fehlende Bilder oder andere Dateien zu suchen, umzubenennen oder ganz eigene Kommandos auszuführen. Am linken Rand des Terminals finden sich Buttons für zusätzliche Funktionen.

Abbildung 2: Eingebaut und nützlich: ein Terminal mit der Standard-Shell.

Speziell bei Problemen erweist sich der unter Log darstellbare Protokollbereich (Abbildung 3) als hilfreich, in dem AsciidocFX Programmausgaben (hauptsächlich für Entwickler nützlich) und Meldungen zum Kompilieren des aktuellen Dokuments (für den Anwender nützlich) anzeigt. Die Schalter über diesem Textfeld helfen, die Flut der Informationen einzugrenzen.

Abbildung 3: Das Log zeigt Informationen, Warnungen und mehr. Mit den Schaltflächen oberhalb des Fenster steuern Sie die Ausgaben oder durchsuchen sie gezielt.

Warnungen und Fehlermeldungen zur Übersetzung des Quelltexts kennzeichnet AsciidocFX am Zeilenanfang mit asciidoctor:, gefolgt von der Zeilennummer im Quelltext und dem Fehlercode. Das zeigt zum einen, dass AsciidocFX intern einen Asciidoctor-Interpreter verwendet und hilft zum anderen, die Fehlermeldungen richtig im Quelltext zuzuordnen.

Die neuesten Protokollinformationen erscheinen auch kurzzeitig in der Statuszeile des Programmfensters. Es empfiehlt sich daher ein regelmäßiger Blick auf das Textfeld rechts neben Terminal und Log.

Praxistest

Beim Start von AsciidocFX öffnet das Programm ein neues Textfenster mit dem Titel new. Ein solches neues Textfenster erzeugen Sie bei Bedarf auch manuell über [Strg]+[N]. In der Werkzeugleiste direkt oberhalb des Textfensters finden sich, wie bereits erwähnt, viele nützliche Funktionen für das Schreiben der Texte. Neben den üblichen Formatierungsfunktionen gibt es dort auch Schalter für komplexere Aufgaben (siehe Tabelle “Funktionen”). Um sie anzuzeigen, klicken Sie auf den Schalter mit dem Pfeil nach unten (Hilfstext More…).

Damit geht das Schreiben auch für weniger erfahrene Anwender recht zügig von der Hand. An normalen Textformatierungen unterstützt AsciidocFX neben Fettung und Kursivierung das Unter- und Durchstreichen von Textpassagen. Dafür schreiben die entsprechenden Buttons in der Werkzeugleiste den erforderlichen Code in der Form [Option]##Text## in das Dokument. Ohne die Angabe einer Option verwendet AsciidocFX die voreingestellte Hervorhebung (Abbildung 4).

Abbildung 4: Textformatierungen lassen sich mit den Werkzeugschaltleisten oder manuell vornehmen.

Überschriften unterschiedlicher Ebenen erzeugen Sie durch einen Mausklick auf H in der Werkzeugleiste. Das rechts daneben angezeigte Kettensymbol dient zum Einfügen von Hyperlinks. Dabei unterstützt AsciidocFX (Abbildung 4) drei Varianten. Daneben kann es auch mit mehreren Arten von Listen umgehen. Für Spiegelstrichlisten und nummerierte Aufzählungen gibt es eigene Schalter, weitere Typen wie Checklisten und benannte Listen lassen sich direkt im Quelltext eingeben.

Tabellengenerator

Für Tabellen bietet AsciidocFX einen Tabellengenerator (Abbildung 5). Neben dem Titel der Tabelle kann man abgesetzte Kopf- und Fußzeilen definieren sowie eine Spaltenbreite vorgeben. Ebenfalls als Vorgabe lässt sich ein Wert (Initial Value) für alle Tabellenfelder angeben. Spalten- und Zeilenzahl müssen Sie bei diesem Dialog vorab festlegen; bei Bedarf passen Sie den Umfang der Tabelle später im Quelltext an.

Abbildung 5: Beim Erstellen einfacher Tabellen hilft der Tabellengenerator.

Ebenso einfach lassen sich Abbildungen einbauen. Ein Mausklick auf den entsprechenden Button fügt den Code image::images/image.png[] in den Quelltext ein. Weitere Optionen wie etwa width=[...] oder den richtigen Dateinamen müssen Sie dann weiter von Hand bearbeiten.

Insgesamt setzt AsciidocFX in vielen Situationen auf Tastenkürzel, die das Editieren im Vergleich zu den Buttons in der Werkzeugleiste ganz wesentlich beschleunigen. Die Tabelle “Tastenkürzel” zeigt eine Zusammenfassung der wichtigsten Shortcuts. Daneben lässt sich bei gehaltenem [Strg] mit dem Mausrad die Schriftgröße im Editorfenster einstellen. Zusätzlich gibt es noch ein Kontextmenü mit wichtigen Funktionen (Abbildung 6). So wandelt Index selection etwa den ausgewählten Text in einen Eintrag für das Stichwortregister um.

Abbildung 6: Im Kontextmenü des Texteditors finden sich zusätzliche nützliche Funktionen.

Die Verwendung des eingebauten Asciidoctor-Interpreters erlaubt auch eine direkte Ausgabe von PDF-Dateien. Das erfolgt bei Asciidoctor direkt, ohne das Zwischenschalten von Dblatex, wie es bei Asciidoc der Fall ist. Daher geht das Umwandeln wesentlich schneller vonstatten als mittels A2x (Asciidoc), lässt sich jedoch auch weniger präzise steuern.

Erfordern etwa druckreife Ergebnisse noch ein Feintuning bei der Ausgabe, bietet AsciidocFX den Export in eine DocBook-Datei an. Alternativ verwenden Sie in einem Terminal asciidoctor-latex, um echten LaTeX-Code zu erzeugen.

Fazit

AsciidocFX eignet sich bestens für das schnelle Editieren bereits vorhandener Asciidoc-Texte, etwa um Fehler zu beheben oder schnell etwas auszuprobieren. Dabei spielt WYSIWYG seine Stärken voll aus. Ob ambitionierte Vielschreiber auf ihre gut konfigurierten und damit an die spezifischen Ansprüche angepassten Texteditor vollständig gegen AsciidocFX eintauschen, hängt von den persönlichen Vorlieben und Anforderungen ab.