Mit der Nutzung unserer Website erklären Sie sich damit einverstanden, dass wir Cookies verwenden. Mehr Informationen

| Zustimmen

Blog

Ein neues Handbuch in AsciiDoc

Teil 1

Deckblatt des Merlin Project Handbuchs

Wir optimieren Merlin Project permanent für eine einfachere Bedienung. Begonnen haben wir bereits vor einiger Zeit mit dem Startdialog und dem Aufräumen des Inspektors.

Mit der Version 8 hat nun die dynamische Hilfe Einzug gehalten: Einfach nur das ?-Symbol anklicken und schon erhalten Sie zu jedem Objekt, auf das Sie mit der Maus (oder beim iPad mit dem Finger) zeigen, einen erklärenden Hilfetext. Für Ihre eigenen Felder können Sie sogar eigene Hilfetexte anlegen.

Doch leider hängt unser Handbuch etwas hinterher. Aber keine Sorge, es gibt reichhaltige und aktuelle Dokumentation, wie:

Ein vollständiges Handbuch existiert zur Zeit nicht. Und genau das möchte ich jetzt ändern.

Das Projekt

Ich habe vor kurzem damit begonnen das Handbuch neu zu schreiben und ebendiese Referenz zu erstellen. Natürlich habe ich ein Projekt dafür aufgesetzt, das sich aber leider die verfügbare Zeit mit allen meinen anderen Projekten teilen muss.

Das Ziel

Neben dem offensichtlichen Ziel, eine aktuelle Dokumentation der Funktionen in Merlin Project in den wichtigsten Sprachen zu erstellen, habe ich mir noch ein paar weitere Unter- oder Teilziele gesetzt:

Das Zieldatum ist aber bei aller Planung vollkommen offen, da ich von Woche zu Woche eine unterschiedliche Arbeitsbelastung habe. So wäre ein gesetztes Datum als Ziel vollkommen unrealistisch.

Die Werkzeuge

Wir schreiben bei ProjectWizards alle Texte im Ascii-Format und checken diese spätestens am Ende des Tages in unser Git ein.

Ganz entgegen der aktuellen Mode, schreiben wir nicht in Markdown oder einem der Derivate bzw. Ergänzungen. Wir haben uns bereits vor sehr langer Zeit auf AsciiDoc und seit einigen Jahren auf das neue Asciidoctor, der Neuimplementierung von Dan Allen (via Twitter), fokussiert. Die Gründe für diese Entscheidung sind vor allem:

  • Variablen,
  • Verlinkung anderer Dateien,
  • Bedingte Texte und Formatierungen,
  • Tabellen, Diagramme und viele andere Inhalte,
  • Textausgabe in viele unterschiedliche Formate,
  • automatische Inhaltsverzeichnisse, wie auch Glossare, Index und Bibliographien
  • und vieles mehr …

Und bevor ich es vergesse, natürlich ist BBEdit bei mir immer noch als Editor #1 gesetzt.

AsciiDoc vs Asciidoctor

Kurz gesagt, Sie geben den AsciiDoc-Quelltext an Asciidoctor und erhalten ein Ergebnis, das Sie veröffentlichen können. Also ist:

  • AsciiDoc die Sprache
  • Asciidoctor der Prozessor

Wie schon Markdown, wurde AsciiDoc als Sprache entwickelt, um unaufdringlich und prägnant zu sein und um das Schreiben zu vereinfachen, ja sogar angenehmer zu machen. Aber AsciiDoc selbst ist kein Publikationsformat. Es ist eher eine Art Kurzschrift. An dieser Stelle kommt ein AsciiDoc-Prozessor ins Spiel.

Ein AsciiDoc-Prozessor, wie z.B. Asciidoctor, liest den AsciiDoc-Quelltext und konvertiert ihn in publizierfähige Formate wie HTML 5, eBook oder PDF. Das ganze wird natürlich mit gestalterischen Mitteln, wie Cascading Style Sheets (CSS), ergänzt.

Working out Loud (WOL)

Ganz im Gedanken von Working out Loud werde ich versuchen, regelmäßig von dieser Arbeit zu berichten. Dabei werde ich weniger Schwerpunkt darauf legen, wie viele Worte oder Sätze ich in der Woche schreiben konnte. Es geht mir viel mehr darum Hilfen sowie neue Erkenntnisse zu Asciidoc und Asciidoctor zu präsentieren.

Mit diesem Ansatz würdige ich natürlich auch die unermüdliche Arbeit von Dan Allen und will ihn unterstützen. Mindestens genauso viel ist dies ein Votum für Asciidoc im Projektmanagement.

Am nächsten Freitag geht es an dieser Stelle los.


Fortsetzung - Ein neues Handbuch in AsciiDoc, Teil 2

Geschrieben von Frank Blome am 08.10.2021 unter Interna
Tags: asciidoc asciidoctor handbuch-projekt wol

Merlin Project auf dem Mac und dem iPad

Ihre Ideen, unsere Magie – Projekte einfach verwirklichen!
Jetzt 30 Tage kostenlos testen.