Ein neues Handbuch in AsciiDoc

Teil 2

Dieses ist der zweite Teil meines Projektberichts für das neue Merlin Project-Handbuch. Ich werde jeden Freitag versuchen ein mehr oder weniger kurzes Update zum Projekt zu geben.

Das Projekt

Bevor wir uns auf AsciiDoc stürzen, hier ein schneller Blick auf mein Projekt.

Das Git repository wurde aufgesetzt
Die Zeilen sind definiert und wurden zum Teil auch hier aufgeführt.
Die Vorraussetzungen sind soweit bekannt.
Eine erste Gliederung ist erstellt und wird jetzt peu-à-peu verfeinert.
Als Bilder werde ich zunächst nur schnelle Bildschirmfotos verwenden, und die dann bei Bedarf neu erstellen.
Ein Wochentag zum Schreiben ist festgelegt.

Gerade der letzte Punkt war eine echte Herausforderung für mich, denn irgendwie muss ich mir die Zeit zum Schreiben freischaufeln. Wenn ich einfach nur jede verfügbare Minute nehme, werde ich wohl nie fertig. Ich brauche einen festen Zeitblock und genau den habe ich mir geschaffen. Ab sofort ist der Mittwoch mein Handbuch-Schreibtag. Mal schauen, wie lange das funktioniert …

Natürlich gibt es ein Kanban-Board. Sorry für die englische Sprache – interne Dokumentation wird bei uns sehr viel in englisch gemacht.

AsciiDoc Tipps

Dateien aufteilen

Ich erstelle das Handbuch nicht in einer Datei, sondern bevorzuge eine kapitelweise Aufteilung. Außerdem lagere ich die Variablen und Attribute meines Handbuchs in eine eigene Datei aus, damit ich die Dateien auch einzeln bauen oder im Browser ansehen und alle Variablen und Attribute nutzen kann. Diese Datei heißt bei mir üblicherweise Attributes und damit ich sie immer schnell finde bekommt sie einen "_" und steht so in der Dateiliste immer am Anfang.

ifndef::_attributes[]
include::_attributes.de.adoc[]
endif::[]

Hier frage ich ab, ob die Variable _attributes schon gesetzt ist.
Falls nein, wird die Datei inkludiert.

So stelle ich sicher, dass die Attribute-Datei nicht mehrmals geladen wird, da ja jede Datei mit diesen Zeilen beginnt.

Mein Rapid turnaround

Ich schreibe zwar zur Zeit noch alleine am Handbuch, trotzdem gehen alle Texte und Medien ins Git. Das hießt, mein morgendlicher Schreibstart beginnt im Terminal, oder – je nachdem was ich gerade zur Hand habe – dem BBEdit Unix Worksheet, mit einem beherzten git pull. Dann öffne ich die BBEdit-Projektdatei (die im Repository natürlich enthalten ist) und sehe alle enthaltenen Dateien in der linken Liste.

Den Bildschirm habe ich in etwa hälftig aufgeteilt: Links schreibe ich und rechts habe ich Chrome offen. In das Browser-Fenster ziehe ich einfach das Proxi-Icon der bearbeiteten Datei. Dank der Erweiterung Asciidoctor.js wird mit jedem Sichern in BBEdit der Browser aktualisiert.