Vor einigen Monaten hörte ich die faszinierende Geschichte von Leon Theremin, dem Erfinder des berüchtigt unheimlichen Theremins. Der russische Erfinder führte ein bemerkenswertes Leben, zu dem es gehörte, in den 1930-er-Jahren nach Amerika durchzubrennen, um eine afroamerikanische Frau zu heiraten, und zu versuchen, Lenin wiederzubeleben. Ich fragte mich, ob es noch mehr solcher Geschichten über die Erfinder von Musikinstrumenten gibt, und begann, die Idee für ein Buch zusammenzutragen, das ich irgendwann Verlagen vorstellen möchte.

Das schien mir der perfekte Zeitpunkt und das perfekte Projekt zu sein, um adoc Studio auszuprobieren. Die App bringt mehrere Funktionen mit, die sich ideal für lange wissenschaftliche Texte eignen.

Versionierung und Entwürfe

Ich beginne mit dem Wesentlichen und erstelle sowie überarbeite Entwürfe, während Sie den Text prüfen und Feedback geben. Anders als andere Werkzeuge wie Microsoft Word oder Google Docs verfügt adoc Studio nicht über eine eingebaute Versionierung und folgt stattdessen einem Docs-as-Code-Ansatz. „Docs-as-Code“ bedeutet, dass eine Auszeichnungssprache in Klartext namens AsciiDoc und git verwendet werden, um Dokumentversionen zu erstellen und zu verwalten. Beide Techniken haben eine Lernkurve, doch wie viele neue Ideen und Prozesse zahlen sie sich aus.

Erst eine neue Stelle als Redakteur für ein Online-Entwicklerportal brachte mich zu Markdown. Dann führte mich die Arbeit an einem Buch zu AsciiDoc, und nach und nach eröffnete sich das Ökosystem der „Docs-as-Code“ um diese Formate.

Als ich erstmals von Werkzeugen wie Microsoft Word zu Klartext-Formaten wie Markdown und AsciiDoc sowie zur Versionsverwaltung mit git gezwungen wurde, leistete ich großen Widerstand. Ich mochte die grafische Symbolleiste und das Feintuning von Formatierungen und Stilen. Ich fand es angenehm, dass alles in einer Datei steckte und nahezu jeder eine Word-Datei öffnen konnte.

Doch ich lernte schnell, dass Docs-as-Code weitaus mehr Leistung und Flexibilität bietet, und inzwischen ist meine Haltung genau umgekehrt. Ich fühle mich wie ein unglücklicher Fisch an Land, wenn ich Microsoft Word oder Google Docs benutzen soll.

Verwendung von Klartext-Formaten

Im Fall von AsciiDoc hilft Ihnen adoc Studio, jede benötigte Syntax zu finden, indem Sie die ESC-Taste drücken und im Coach-Popup tippen. Das Docs-as-Code-Ökosystem, insbesondere AsciiDoc, legt Wert auf semantische Syntax, also „Markup“.

Statt beispielsweise Textstellen direkt als Inhaltsverzeichnis, Hinweisbox oder Fußnote zu formatieren, markieren Sie sie lediglich als solche und kümmern sich separat um das Layout. Eines meiner Hauptprobleme mit Werkzeugen wie Word war, dass ich zu viel Zeit damit verbrachte, mir Gedanken über das Aussehen des Textes statt über dessen Inhalt zu machen.

AsciiDoc selbst ist ein umfangreiches Thema. Wenn Sie damit noch nicht vertraut sind, beginnen Sie mit diesem Leitfaden; spezifische Syntax und Funktionen behandle ich im weiteren Verlauf dieses Beitrags.

Verwendung von Versionskontrolle

Wenn Sie nicht viel Geld für SharePoint ausgeben, wie oft haben Sie schon mehrere Kopien derselben Word-Datei vorgefunden, mit Namen wie „esoteric-instrument-DRAFT-1.docx“, „esoteric-instrument-FINAL.docx“, „esoteric-instrument-FINAL-FINAL.docx“ usw.?

Mit Tools wie Google Docs ist es etwas besser, aber selbst dort, ähnlich wie bei der Änderungsverfolgung in Word, verliert man sich schnell in einem Meer aus farbigen Linien und Kommentaren, in dem niemand mehr den Überblick hat.

Der Einsatz spezialisierter Versionierungstools wie git hat zweifellos eine Lernkurve, doch es gibt zahlreiche Ressourcen für den Einstieg in git. Und meiner Erfahrung nach erhält man, sobald man sich daran gewöhnt hat, ein Maß an Diskussion, Kontrolle und Zusammenarbeit, das kein anderer Workflow bietet.

Mit git können Sie kleine und große Änderungen nachverfolgen und mit anderen Geräten und Personen synchronisieren. Ein einzigartiger Aspekt von git ist, dass mehrere Personen an einer Kopie desselben Projekts arbeiten und ihre Änderungen zusammenführen können, wobei git den Vorgang größtenteils automatisiert.

Mitarbeitende können zudem Projektvarianten erstellen und unabhängig daran arbeiten, diese Versionen später zusammenführen oder vollständig neue Zweige pflegen. Bei einem Buchprojekt könnten Sie so verschiedene Ansätze ausprobieren und entscheiden, welcher am besten funktioniert. Oder eine Lektorin könnte eine Version übernehmen, darin Änderungen vornehmen und Ihnen diese vorschlagen.

Synchronisieren zwischen Ihren eigenen Geräten

Für alle, die iCloud nutzen, lassen sich adoc-Studio-Dokumente auch zwischen Macs und iPads synchronisieren. So können Sie unterwegs weiter schreiben und finden die Änderungen später vor, oder Sie teilen sie per iCloud mit Mitwirkenden.

Terminologie und Bibliografie

Recherche in einer Bibliografie zusammenführen

Jedes seriöse Fach- oder Sachbuch muss seine Quellen angeben. Mit adoc Studio können Sie einen standardisierten Bibliografie-Abschnitt des Buches mit Ihren Einträgen anlegen und dann während des Schreibens über eine Autovervollständigung darauf verweisen und verlinken. Ändern Sie einen Eintrag in der Bibliografie, aktualisiert sich der verknüpfte Text entsprechend.

Um eine Bibliografie zu erstellen, öffnen Sie den Coach mit ESC und wählen „Bibliography“, dann füllen Sie die Angaben zur Quelle aus. Beim ersten Mal legt adoc Studio den Abschnitt „Bibliografie“ im Dokument an. Nachdem eine Quelle angelegt ist, können Sie sie beim Erstellen eines Links aus der Link-Autovervollständigung auswählen.

Fachspezifische Terminologie

Fast jedes Fachgebiet hat seinen eigenen Jargon und spezielle Begriffe, die Standardwörterbücher des Systems oder der Anwendung nicht kennen, sodass man sich durch eine Flut roter Unterstreichungen kämpfen muss.

Um das zu lösen, sollten Sie benutzerdefinierte Begriffe projektspezifisch hinterlegen können, denn ein ungewöhnliches Wort kann in einem Kontext korrekt sein, in einem anderen nicht. In adoc Studio können Sie solche Wörter entweder dem systemweiten Wörterbuch hinzufügen (ein Vorteil einer echten macOS- und iOS-App) oder ein Wörterbuch für das Projekt anlegen und sie dort eintragen. Dieses Wörterbuch ist eine weitere Datei im Projekt, die Sie teilen und per Versionskontrolle verwalten können, sodass auch Ihre Mitwirkenden nicht in roten Linien versinken.

Benutzerdefinierte Callouts

Viele technische Inhalte – seien es Dokumentationen, Blog-Beiträge oder Bücher – enthalten Textabschnitte, die hervorgehoben werden sollen. Technisch heißen sie Admonitions, gebräuchliche Bezeichnungen sind auch „Callouts“ oder „Pop-outs“. In der Regel folgen sie einem der folgenden Formate:

  • HINWEIS
  • TIPP
  • WICHTIG
  • VORSICHT
  • WARNUNG

Für dieses Buch möchte ich einen speziellen Callout, der darauf hinweist, wo der Leser eine Hörprobe findet – eine gute Gelegenheit, die Unterstützung von Icon-Sets in adoc Studio auszuprobieren, in diesem Fall Apples SF Symbols.

Fügen Sie zunächst die folgenden Attribute am Anfang des Dokuments ein; durch Drücken der ESC-Taste öffnet sich erneut der Coach, der alle Attribute per Autovervollständigung anbietet:

:icons: font
:icon-set: apple

Diese beiden Attribute aktivieren Schrift-Icons und legen das zu verwendende Set fest.

Jetzt erstelle ich eine Admonition und verwende ein Icon für den Titel:

.icon:speaker.wave.2[link=https://en.wikipedia.org/wiki/File:Epro_theremin_middle_bach.ogg]

[NOTE]

Hören Sie eine Probe auf Wikipedia.

Bildhandhabung und benutzerdefiniertes CSS

Ich halte mich für wortgewandt, doch – um eine abgedroschene Phrase zu verwenden – manchmal sagt ein Bild mehr als tausend Worte, und ein Foto, das jemanden beim Spielen eines dieser exotischen Instrumente zeigt, würde den Text lebendig machen.

Bilder gibt es in allen Formen und Größen, und da man AsciiDoc zum Export in verschiedene Druck- und Online-Formate nutzen kann, sollte man darauf achten, sie in einer geeigneten Größe und einem passenden Format auszugeben.

Erstelle ich beispielsweise eine eBook-Version des Buches – ein Exportziel, das adoc Studio zwar nicht direkt unterstützt, das aber im Wesentlichen HTML ist –, möchte ich Bilder in niedriger Auflösung verwenden. Für eine Druckversion würde ich hingegen hochauflösende Bilder einsetzen.

Außerdem enthält das Buch einige Formeln. Betrachten wir zum Beispiel diese Darstellung der Oszillatoren in einem Theremin:

Für den Druck muss diese Formel als Bild gerendert werden; für HTML dagegen per JavaScript. Da die meisten eBook-Reader kein JavaScript unterstützen, ist es besser, die Formel als skalierbares Bild auszugeben, damit sie sich mit der Schriftgröße des Nutzers mitvergrößert.

All das lässt sich mit zwei Dokumentattributen, etwas Logik und bedingter Formatierung lösen.

Zuerst füge ich die folgende Logik am Anfang meines Dokuments ein – wieder per ESC über den Coach verfügbar –, die die maximale Bildauflösung auf 100 dpi setzt und Formeln als SVG rendert:

ifdef::ebook[]

:ads-max-image-resolution: 100dpi

:ads-static-stem:

endif::[]

Um diese verschiedenen Attribute anzuwenden, übergebe ich beim Export eine Variable namens „ebook“, und adoc Studio wendet diese Einstellungen dann an.

Es gibt zwei Möglichkeiten, die Variable beim Export festzulegen.

Die erste führt über das Menü Datei > Exportieren, Abschnitt Attributes, wo Sie denselben Attributnamen und-wert setzen.

Als Nächstes möchte ich einige Formatierungen für die eBook-Version ändern: Die Überschriften sollen zentriert sein. In Wirklichkeit wäre das komplexer, doch für dieses Beispiel genügt es.

Dazu öffnen Sie den Menüpunkt adoc Studio > Settings und wählen den Reiter „Product Styles“.

Rechtsklicken Sie den Stil „Classic“ und wählen „Duplicate“, benennen Sie den neuen Stil „eBook“.

Mit dem neuen Stil ausgewählt, erneut rechtsklicken und „Edit in“ wählen. Verwenden Sie Ihren bevorzugten Texteditor; andernfalls nehmen Sie „TextEdit“.

Was Sie hier sehen, ist ein Cascading Style Sheet (CSS). Wenn Sie aus der Word-Welt kommen, denken Sie an das Styles-Fenster. Dort definieren Sie, wie Seitenelemente aussehen, und verwalten diese Definitionen zentral. Auch das ist ein weites Feld, das sich zu erkunden lohnt. Fürs Erste fügen Sie jedoch Folgendes ganz unten in die Datei ein und speichern sie.

/ Stile für eBooks /

h1,
h2,
h3,
h4 {
    text-align: center;
    font-weight: bolder;
}

Damit werden alle Überschriften zentriert und fett dargestellt. Beim Export oder in der Vorschau in adoc Studio können Sie den gewünschten Stil auswählen. Stellen Sie also in der rechten Werkzeugleiste Folgendes ein:

  • Für den Druck: Format auf „PDF“ und Style auf „Classic“.
  • Für eBooks: Format auf „HTML“ und Style auf „eBook“.

Wenn Sie zwischen diesen Optionen wechseln, aktualisiert adoc Studio die Vorschau sofort.

Viel cooler, besonders für Fans von Kommandozeilen und Automatisierungs-Tools wie mich, ist der neue Kommandozeilenbefehl von adoc Studio, adocstudio. Damit kann ich alles in zwei Befehlen zusammenfassen.
Chris Ward

Für den Druck:

adocstudio export documents --format pdf --style Classic --project Esoteric\ instruments.adocproject  --document Document.adoc ..

Für eBooks:

adocstudio export documents --format html --style eBook --attribute format=eBook --project Esoteric\ instruments.adocproject  --document Document.adoc ..

Automatisierung

Schön und gut – aber warum ist ein Kommandozeilenbefehl zum Exportieren von Dateien so nützlich? Weil er Automatisierung ermöglicht.

Sie können zum Beispiel git hooks einsetzen – kleine Skripte, die an verschiedenen Stellen des zuvor erwähnten Versionskontrollzyklus laufen –, um vor dem Push nach GitHub automatisch einen PDF- oder HTML-Export zu erzeugen. So lässt sich das Ergebnis leichter prüfen.

Oder Sie nutzen auf macOS Automatisierungs-Tools wie Apple Shortcuts, BetterTouchTool und Keyboard Maestro; durch die Verfügbarkeit eines Kommandozeilenbefehls ergeben sich unzählige Möglichkeiten. Noch besser: Version 3 von adoc Studio unterstützt jetzt Apple Shortcuts! Hier ist ein Screenshot der entsprechenden Shortcuts-Variante.

Zusammenfassung

Das war’s! Wer von Microsoft- oder Google-basierten Werkzeugen kommt, wird sich von diesem Beitrag vielleicht mit neuen Konzepten und Syntax bombardiert fühlen, doch hoffentlich hat er auch gezeigt, dass der Umstieg auf Klartext-Formate sowie die zugehörigen Toolchains und Prozesse langfristig große Vorteile bringt. Werkzeuge wie adoc Studio überbrücken die Kluft zwischen Ökosystemen, indem sie grafische Unterstützung für diese mächtigen Tools bieten.

Autor: Chris Ward
Technischer Autor,
Schriftsteller und
Medienmacher für
Unternehmen jeder Größe.