Asciidoc – Multilinguales Single-Source Publishing für Web und Print

Manchmal wird ein einzelnes Programm als Open-Source entwickelt und manchmal entwickeln sich ganze Cluster aus Open-Source-Programmen.

Mit Asciidoc ist definitiv letzteres passiert: Versioniertes multilinguales Single-Source Publishing für Web und Print ist auf open-source-Basis damit durchaus möglich und sogar praktikabel.

== Überschrift 1
* Liste
* Element 2
----
Codeblock
----

Das können durchaus mehrere Dateien pro Sprache sein, geht aber darum, zu versionieren, die Sprachen gesteuert übersetzen zu können und mit demselben Satz sprachspezifischer Quelldateien sowohl Online (HTML) als auch die jeweilige Printversion (PDF) zu generieren.

Zielgruppe ist dabei technische Dokumentation, wie APIs, Software- oder Entwicklerdokumentation die in verschiedenen Inhaltsmodulen (beispielsweise Anwendungen) für verschiedene gleichzeitig in der Versionsverwaltung weitergeführte Versionen.

Asciidoc ist dabei «nur» das zentrale Format, auf das sich alle geeinigt haben und das um zahlreiche Tools entwickelt haben: Mit Asciidoctor-PDF erstellt man aus einer Vorlage die «Printversion», Antora baut aus einer anderen Vorlage die HTML-Dateien. Antora ist dabei sehr gut in versionsverwaltungssysteme integriert – überhaupt bietet sich eine Versionsverwaltung wie Git an um die Inhalte zu versionieren, durch mehrere Autoren gleichzeitig zu bearbeiten, Versionen zusammenzuführen oder absichtlich abzweigende Versionen (Branches) zu erstellen oder herauszufinden was wer wann wie geändert hat.

Was wer wann wie spielt auch bei Übersetzungen eine Rolle: OmegaT ist ein ebenfalls kostenloses Open-Source-Programm das Übersezungen nicht nur ermöglicht, sondern dadurch vereinfacht, dass es nur die Sätze zur Übersetzung anziegt die sich in der Originalsprache überhaupt geändert haben. Solche auch als «Translation Memory» oder «Computer Aided Translation» (CAT) bezeichneten Programme werden unter anderem von der Europäischen Zentralbank oder (speziell OmegaT auch) bei der Europäischen Kommission oder benutzt um die Übersetzungsqualität manueller Übersetzungen zu erhöhen: Ein ganzes Team kann sich dabei auf einen «Stil» einigen, werden Übersetzer ausgetauscht ändert sich nicht die Tonalität. Dabei ist vollkommen unerheblich ob die Übersetzungen manuell oder durch Übersetzungssoftware erstellt wird. Den ausgewählten Absatz per DeepL übersetzen zu lassen ist in OmegaT nur ein Hotkey entfernt. OmegaT ist neben Asciidoc übrigens auch für ganz normale Office-Programme geeignet.

Man erkauft sich die Vorteile wie die Versionierbarkeit mit dem Nachteil, dass es sich nicht um What-You-See-is-What-You-get handelt. Zum Schreiben gibt es füe viele IDEs wie IntelliJ allerdings Plugins, die eine Vorschau immerhin neben dem Asciidoc «Quelltext» der Publikation anzeigen.

Beispielsweise aus Office ins Asciidoc-Format – oder anders herum – konvertiert man mit Pandoc.

Warum Asciidoc?

Andere Formate wie Markdown erlauben abweichende Interpretationen – beispielsweise kommt es auf den Markdown-Interpreter an wie Tildezeichen ~ verarbeitet werden. Außerdem hat Markdown weder die Funktionalität Inhaltsverzeichnisse, Bildunterschriften, «Admonitions» (beispielsweise eingerückte Hinweise), Indexeinträge (beispielsweise im Schlagwort- oder Literaturverzeichnis) oder Querverweise zu erstellen. Um Inhalte einzubetten kennt Asciidoc zudem den mächtigen Include-Befehl, der bei der PDF-Ausgabe hilfreich ist.

Wie kommt man mit diesem ganzen Konglomerat zurecht?

Alle diese Tools sind in bester Open-Source-Manier kostenfrei für Mac, Windows und Linux verfügbar.

Es gibt neben der Verzeichnisstruktur also auch eine Art Projektstruktur:

Dokumente sind Dateien, die in Verzeichnissen organisiert werden. Da alle Dokumente im «Print» in der Regel in ein Gesamtprojekt pro Sprache integriert sind und es erwähnten mächtigen Include-Befehl gibt mit dem das bewerkstelligt werden kann wird das _Verzeichnis_layout durch das HTML-CMS (bei uns Antora) bestimmt, die meisten publizistischen Anforderungen (wie Inhalts- Schlagwort- oder Literaturverzeichnis) stellt aber die PDF-Version.

das Linux Professional Institute zeigt in einem 90-minütigen Video unter andere, wie es mit Asciidoc, Git, Docker (in dem Asciidoctor-PDF läuft) und OmegaT umgeht. Das LPI nutzt Hugo als HTML-CMS, wir verwenden Antora.

Heise hat das ganze auch als Documentation-as-Code beschrieben.

Zu guter Letzt sei noch kurz auf die offizielle Asciidoctor-Dokumentation hingewiesen.

Referenzprojekte

Um die praktische Anwendung von Asciidoc und den damit verbundenen Tools zu veranschaulichen, möchten wir zwei Referenzprojekte vorstellen:

1. ZUGFeRD-Dokumentation

Auf zugferd.org verwenden wir Github in Kombination mit Antora. Dies ermöglicht eine öffentliche Beteiligung an der Dokumentation:

• «Jeder kann Inhaltsvorschläge machen, indem er auf den Edit this page» Link klickt.
• Über Github können Benutzer per Fork und Pull Request eigene Frequently Asked Questions (FAQs) einbringen.

Dieser Ansatz fördert die Community-Beteiligung und ermöglicht eine kontinuierliche Verbesserung der Dokumentation.

2. ZUGFeRD-Schulungsunterlagen

Für unsere Schulungen im Rahmen von learning.zugferd.org nutzen wir Gitlab in Verbindung mit Asciidoctor-PDF:

• Wir haben gemeinsam ein Skript erstellt, das Sie hier in der Vorschau sehen können.
• Dieses Setup ermöglicht es mehreren Trainern, gleichzeitig am Skript zu arbeiten.
• Wir nutzen Branches und Merge Requests für die Zusammenarbeit.
• Ähnlich wie beim LPI gibt es Branches für jeden Trainingskunden mit kundenspezifischen PDF-Themes, um beispielsweise das Kundenlogo im Skript zu integrieren.

Besonderheiten unseres Setups:

• Wir haben eine Art Unterprojekt für häufig benötigte Seiten, die wir als separates PDF exportieren.
• Das Gesamtdokument umfasst ein Inhaltsverzeichnis, ein Glossar, eine Art Kolophon und ein Stichwortverzeichnis.
• Die Bibliografie wird als Quellenverzeichnis („Referenz“) genutzt, um Aktualisierungen im Downloadpaket zu verfolgen.

Setup von Antora

Gesamtprojekt

Nach der Installation von Node https://nodejs.org/en/download/prebuilt-installer/current lässt sich Antora zwar problemfrei per NPM installieren, es gibt aber vier Dinge zu beachten

• erstens ist die default-Theme eher eine Muster- als eine Minimalvorlage, muss also kurz angepasst werden.
• zweitens ist Antora sozusagen „version aware“ und erfordert mindestens ein Git repo. Zur Versionierung der Theme und für das Hauptprojekt machen tatsächlich zwei weitere Repos Sinn. Allein um es möglichst einfach zeigen und zum ersten mal nachvollziehen zu können beschränken wir uns hier auf ein Repo, das per sicherem SSL ohne Authentifizierung zugreifbar ist. Private Repos gehen auch, zeigen wir aber erst unten.
• drittens wird unterschieden zwischen dem Hauptprojekt und den Modulen, von denen es mindestens eines geben muss.
• viertens zieht sich Antora selbst die Inhalte per git, Änderungen werden in der Regel also erst nach einem Commit&Push sicht- beziehungsweise brauchbar.

Wir legen für das Gesamtprojekt ein Verzeichnis namens docs-site und darin ein antora-playbook.yml an. Darin geben wir Projekttitel, die Startseite, die Inhaltsmodule und das Theme an.

site:
  title: Antora Demo
  start_page: demo1::index.en.adoc
content:
  sources:
  - url: https://<git server>/<git pfad>/<git projekt. bspw. antorademo>
    branches: HEAD

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Danach legen wir ein package.json auf der Kommandozeile an

node -e "fs.writeFileSync('package.json', '{}')" && npm i -D -E antora

und starten Antora versuchsweise:

npx antora -v

sollte jetzt Version 3.1 liefern (Stand August 2024).

Inhaltsmodul

Im Stammverzeichnis beschreiben wir das Inhaltsmodul und geben in antora.yml Name, Titel, Version, Startseite und die „Startseite“ der Navigation an.

name: demo1
title: Antora Demo Content Module
version: 1.0.0
start_page: index.en.adoc
asciidoc:
  attributes:
    source-language: asciidoc@
    table-caption: false
nav:
- modules/ROOT/nav.en.adoc

Für deutsch würde man entsprechend index.de.adoc und nav.de.adoc verwenden. Dann legen wir die Verzeichnisse modules\ROOT\pages und modules\ROOT\images\media an. In der Navigation verwenden wir jetzt unseren ersten Adoc-Befehl, einen Querverweis:

In modules/ROOT/nav.en.adoc

* xref:index.en.adoc[Main page]

und in modules/ROOT/pages/index.en.adoc können wir inhaltlich loslegen.

Die HTML-Version erzeugt man dann im Projektverzeichnis (docs-site) mit einem npx antora –fetch antora-playbook.yml

Die HTML-Ausgabe wird erstellt in \docs-site\build\site

Theme

Das Problem beim Default Themen liegt im Kopfbereich: Products und Services klappen auf, verlinken mit Product A bis C beziehungsweise Service A-C aber – ebenso wie der Download-Link – lediglich auf die aktuelle Seite.

Das Theme muss also angepasst werden. Zum Glück kann das „antora-ui-default“-Theme relativ einfach geklont und mit gulp gebaut werden:

git clone https://gitlab.com/antora/antora-ui-default.git
cd antora-ui-default
npm install
npx gulp bundle

Das in build befindliche ui-bundle.zip lädt man auf einen Webserver, der im Intra-oder internet angesprochen werden kann und aktualisiert die Projekteinstellungen antora-playbook.yml.

Jetzt kann man src/partials/header-content.hbs, ein Handlebar Template, bearbeiten, die Produkt und Services entfernen und den Downloadlink anpassen.

PDF

Für Asciidoctor-PDF installiert man sich zunächst die Programmiersprache Ruby (die „RIDK“ Runtime brauchen Sie nicht), und holt sich über deren Dependency Management gem die Kommandozeile von Asciidoctor-PDF:

gem install asciidoctor-pdf

Jetzt baut man sich eine Datei, beispielsweise pdf.en.adoc, die per Include-Makro alle Kapitel hintereinander listet, in unserem Fall ist das erst eines, index.en.adoc.

= Antora Demo
:doctype: book
:toc:

= Test
:toc:

*This*
is a test

NOTE: It is really just a test

== With a headline

a link:https://www.google.com[Link],
a

----
Block
----

a `monospace`, a image

image::media/1547254971.svg[]

(whose file has to be saved in the images directory next to pages),
a list

* with a first
* and a second item
and a table

[width="100%",cols="1,1"]
|===
|*Version* |*Date*
|1.0 |2019-03-05
|2.0 |2020-02-13
|2.1 |2021-10-30
|===




[bibliography]
== Referenz
* [[[Antora]]] https://antora.org




[index]
== Index

Das Problem ist jetzt, dass Asciidoctor vom Antora-Verzeichnislayout noch nichts wissen kann und Bilder im aktuellen Verzeichnis suchen würde. Im Stammverzeichnis kann man sich daher mit mklink /j media modules\ROOT\images\media einen Hardlink anleggen.

Danach erzeugt man mit

asciidoctor-pdf pdf.en.adoc

ein pdf.en.pdf.

PDF-Theme

Die Optik des PDFs kann jetzt angepasst werden indem beispielsweise eine leicht abweichende Textfarbe vorgegeben und ein Bild fürs Deckblatt sowie ein Logo für den Fußbereich jeder Seite verwendet wird. Dazu speichert man folgendes in einer theme.yml

extends: default base: font-color: #101010 title-page: background-image: big-background.png footer: background-image: small footer logo

Und ruft Asciidoctor fortan mit passendem Parameter auf:

asciidoctor-pdf .\pdf.en.adoc --theme .\theme.yml

Private Repos

Im Unternehmenseinsatz ist es nicht unüblich die Dokumentation in einem Git im Intranet abzulegen, dessen SSL-Schlüssel oft nicht über die üblichen Kanäle zertifiziert werden kann.

In dem Fall kann man sich mit System-Umgebungsvariablen behelfen, auf der Kommandozeile setzbar mit set.

# in cmd.exe
set NODE_TLS_REJECT_UNAUTHORIZED=0
# oder in der powershell
$env:NODE_TLS_REJECT_UNAUTHORIZED=0

Möchte man sich gegen den privaten Gitlab-Server auch authentifizieren können kann man in seinem Home-Verzeichnis ein .git-credentials anlegen

https://<nutzername>:<password>@<git server>/<git pfad>/<git projekt. bspw. antorademo>

Runner

Apropos Gitlab: Um die HTML- und PDF bei pushes automatisch zu erstellen gibt es ein docker-asciidoctor Image.

Das erwähnte LPI Video zeigt in dem Zusammenhang auch etwas dockeriges. Da Docker aber unter Windows im kommerziellen Einsatz kostenpflichtig ist und wegen des Overheads kann man mit folgender gitlab-ci.yml auch die NPM- beziehungsweise Ruby-Versionen laufen lassen.

Läuft der Gitlab Runner unter Systemrechten ist das Home-Verzeichnis für die `.git-credentials` mitunter %WinDir%\system32\config\systemprofil

variables:
  ANTORA_CACHE_DIR: .cache/antora
  NODE_OPTIONS: --max-old-space-size=4096
before_script:
pages:
  stage: deploy
  interruptible: true
  tags:
    - pc14
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  cache:
    paths:
      - .cache
  script:
    - cd docs-site
    - npm ci
    - npx antora --fetch antora-playbook.yml
    - cd ..
    - asciidoctor-pdf .\pdf.en.adoc --theme .\theme.yml
    - Copy-Item  -ErrorAction Continue ./pdf.en.pdf -Destination ./docs-site/build/site
    - cd docs-site
    - Remove-Item -Recurse -ErrorAction Continue -Force D:\www\antora\sites\
    - mkdir D:\www\antora\sites\
    - Copy-Item -Recurse -ErrorAction Continue -Force ./build/site -Destination D:\www\antora\sites\

  artifacts:
    paths:
      - docs-site/build

Natürlich installiert man dafür einen Runner und lässt ihn als Dienst laufen. In diesem Beispiel ist er außerdem so konfiguriert, dass er auf das Tag pc14 hört. Auch der Runner muss selbstverständlich mit den https-Gegebenheiten des Gitlab-Servers zurecht kommen.

Versionen

Die Versionsnummer ist im Inhaltsmodul vermerkt.

Und dieses wird im unter anderem mit Angabe des Branches angegeben. Da Sie die Versionsnummer in einem anderen Branch in der Regel nicht mehr ändern werden, steht hier praktischerweise immer die korrekte Nummer drin.

Für unversioniert kann man auch ~ angeben, true bedeutet, dass der branchname angezeigt werden soll. Man kann eine Versionsnummer auch aus Namenskonventionen der Branches berechnen lassen.

Suchmaschine

Es gibt eine offline-Javascript-Suchmaschine, deren Index automatisch bei site-generierung mit erstellt wird.

In der Projektdatei kann sie einfach wie folgt mit eingebunden werden:

antora:
extensions:
- require: '@antora/lunr-extension'

Pandoc

Zum Import und Export gibt es zusätzlich beispielsweise Pandoc.

Aus MS Word ist der Asciidoc-Export vergleichsweise einfach

pandoc another.docx -f docx -t asciidoc --wrap=none --markdown-headings=atx  --extract-media=images -o another.en.adoc

Um von Asciidoc nach Word zu exportieren legt man einen Docbook-Export als Zwischenschritt ein:

asciidoctor --backend docbook pdf.en.adoc --out-file pdf.en.docbook
pandoc --from docbook --to docx --output pdf.en.docx  --highlight-style espresso .\pdf.en.docbook

Wie PDF-Themes kann man sich auch Word-Vorlagedateien konfigurieren, dann sähe ein Export in etwa so aus:

pandoc -o my-custom-styles.docx \
--print-default-data-file reference.docx

Inhalte

Die Startseite des Inhaltsmoduls verändert man in der antora.yml und die des Gesamtprojekts in der antora-playbook.yml unter Angabe von <Modulname>::<Seitendateiname>.

Neue adoc-Seiten legt man in modules/ROOT/pages an (Sprachkürzel im Dateinamen nicht vergessen!), bringt sie in die Navigation durch einen entsprechenden xref-Eintrag mit Seitentitel und in die PDF-Datei durch ein Include in der pdf.en.adoc.

Als typische Print-Features steht indexterm2: für Indizes zur Verfügung, ein Glossar ist of nur eine Liste und Bibliographien lassen sich fast ausschließlich über Eckige und Spitze Klammern realisieren.

Über den Autor

Jochen Stärk ist Open-Source-Fan, Maintainer und Diplom-Wirtschaftsinformatiker mit einer kleinen Firma in Frankfurt am Main. Seine berufliche Laufbahn führte ihn von der Webentwicklung zur Arbeit an elektronischen Rechnungen.

Jochens Erfahrungen mit mehrsprachiger Dokumentation und sein pragmatischer Ansatz beim Print-Publishing machen ihn zu einem idealen Anwender und Fürsprecher für Asciidoc und die damit verbundenen Tools. Seine Perspektive als «Gelegenheitsdokumentator» bietet wertvolle Einblicke in die praktische Anwendung von Single-Source-Publishing-Lösungen für technische Dokumentation.

Was denkst du dazu?

yeah!

0

wooow

1

what?

0

meh.

0

hahaha

0