INTERLIS leicht gemacht #62 - Das Holzfällersteak auf dem Ilishorn
2026-05-03
Sich ein wenig über das INTERLIS Referenzhandbuch lustig machen, gehört praktisch zum guten Ton. Wenn man das macht, macht man es wahrscheinlich aus dem falschen Grund: Es ist ein Referenzhandbuch und kein Getting Started Manual oder ähnliches. Aber: es gibt ja noch das INTERLIS Benutzerhandbuch. Das fristet leider ein Schattendasein, obwohl es wirklich gut ist. Vielleicht geht es an der einen oder anderen Stelle bereits zu weit aber das macht es nicht schlecht. Es wurde nie auf INTERLIS 2.4 migriert und auch nie als Webseite publiziert, sondern es liegt nur als PDF-Datei vor. Um Zweiteres geht es in den nächsten paar Zeilen.
Wenn man nicht mindestens Zugriff auf die Worddatei hat und nur mit der PDF-Datei hantieren muss, wäre die Migration nicht sonderlich spassig. Bis jetzt. Ein halbwegs guter Prompt später, liegt die Zip-Datei mit dem extrahierten Text als .adoc-Dateien vor und die Bilder wurden auch gerade extrahiert. Klar braucht es noch ein wenig Nachbearbeitung, aber das hielt sich extrem in Grenzen. Es ist ein absolut erster Wurf und man könnte es noch verbessern. So z.B. könnten viele der Bilder direkt als PlantUML-Grafik codiert werden und nicht bloss als PNG-Bilddatei. Und natürlich eine Migration nach INTERLIS 2.4. Ein «Soft-Update» (also bloss im Header INTERLIS 2.4 schreiben) wäre mit nicht viel Folgeaufwand verbunden aber vielleicht sollte man das ganze Handbuch sowieso interaktiver gestalten. Ein paar Ideen, wie man das bewerkstelligen könnte, habe ich bereits. Aber das könnte natürlich z.B. auch geostandards.ch übernehmen.
Das Referenzhandbuch gibt es seit geraumer Zeit als Webseite. So weit, so gut. Aber wer um Herrgottswillen kommt auf die Idee, nur die Hälfte davon zu publizieren? Wenn ich was im Anhang nachschlagen will, muss ich trotzdem wieder das olle PDF öffnen. Also dann auch noch diesen Teil mit bisschen KI-Hilfe von PDF nach AsciiDoc migrieren.
Nach erfolgter Migration will man die AsciiDoc-Datei nicht nur roh vorliegen haben, sondern eine Webseite. Auf der Hand liegen im vorliegenden Fall Asciidoctor und Antora. Asciidoctor ist mir zu rudimentär und bei Antora fand ich den Ansatz sehr spannend aber dann trotzdem in einige Bereichen zu einschränkend. Spannend, weil die eigentliche Dokumentation in anderen Git-Repos nachgeführt werden kann und Antora beim Herstellen diese Repos herunterlädt, die HTML-Dateien erzeugt und eine Startseite erstellt, welche auf die vorhandenen Dokumentationen verlinkt. Andererseits ist Antora für meinen Geschmack auch ziemlich opinionated: Z.B. ist eine Single Page Webseite mit Kapitelnummern aus verschiedenen .adoc-Seiten ein Geknorze. Was macht man in einer solchen Situation? Man lässt was eigenes Schreiben, das seinen Anforderungen gerecht wird: https://github.com/edigonzales/thoth.
Das Rendering macht natürlich weiterhin Asciidoctor. Aber nicht als fertiges Werkzeug, sondern als Bibliothek. Die Konfiguration ist denkbar einfach: es braucht eine biblios.yml-Datei:
site:
title: INTERLIS-Dokumentation
url: https://docs.interlis.guru
logo: ililogo.png
default_language: de
output:
dir: ./site
clean: true
ui:
sidebar_toc_depth: 3
content_toc: off
content:
sources:
- id: refhb
display_name: INTERLIS Referenzhandbuch
url: https://codeberg.org/edigonzales/doc-interlis-refhb24.git
branches:
- name: main
display_version: v2.1.0
start_path: docs
start_page: refhb24_0_vorwort.adoc
default_version: main
render_mode: single_page
master_file: master.adoc
sidebar_toc_numbers: on
- id: userhb
display_name: INTERLIS Benutzerhandbuch
url: https://codeberg.org/edigonzales/doc-interlis-userhb.git
branches:
- name: main
display_version: v1.0.0
start_path: docs
start_page: master.adoc
default_version: main
render_mode: single_page
master_file: master.adoc
sidebar_toc_numbers: on
revnumber: true
- id: ili2db
display_name: ili2db
url: https://codeberg.org/edigonzales/doc-interlis-ili2db.git
branches:
- name: release/5.5.1
display_version: v5.5.1
- name: release/5.2.2
display_version: v5.2.2
start_path: docs
start_page: ili2db.adoc
default_version: release/5.5.1
render_mode: single_page
master_file: ili2db.adoc
sidebar_toc_numbers: onWie man in der Konfiguration erkennt, kann man verschiedene Branches rendern lassen und publizieren, was ich eine geniale Idee (von Antora) finde. Überall dort, wo wir unterschiedliche Softwareversionen parallel in Betrieb haben (z.B. ili2db, ilivalidator, GRETL) brauchen wir so einen Mechanismus. Das Herstellen der fertigen Webseite ist denkbar einfach:
java -jar thoth-biblios-0.0.1-SNAPSHOT-all.jar build \
--config ./biblios.ymlEs gibt auch einen serve-Mode. Dieser dient vor allem während des Schreibens einer Dokumentation damit man gleich das Resultat sieht.
java -jar thoth-biblios-0.0.1-SNAPSHOT-all.jar serve \
--config ./biblios.yml \
--port 8091 \
--use-local-working-treeMit der Option --use-local-working-tree wird der lokale Working Tree verwendet und man muss nicht immer ins Repo pushen. In diesem Fall muss aber in biblios.yml anstelle von url: https://codeberg.org/edigonzales/doc-interlis-userhb.git url: file:///Users/stefan/sources/doc-interlis-userhb verwendet werden.
Die Webseite braucht kein Server-Backend und kann z.B. auf Codeberg-Pages deployed werden. Die integrierte Suche wurde mit lunr umgesetzt.
Mit dem HTML-Resultat bin ich momentan zufrieden:
Thoth-Biblios kann aber auch ein PDF erstellen. Natürlich mit asciidoctor-pdf. Entsprechend stehen alle Möglichkeiten davon zu Verfügung und es sieht ganz ordentlich aus:
Sogar INTERLIS-Syntax-Highlighting funktioniert:
Und im Übermut habe ich mich noch an einen Word-Export gewagt. Hier kann man nicht nur auf Asciidoctor zählen, sondern es braucht noch weitere Bibliotheken (z.B. docx4j). Das Resultat ist noch nicht sehr gut (aka production ready) aber vieles funktioniert bereits:
Und ja, ich bin schon zufrieden, dass es überhaupt einen Codeblock hat… Beim Wordexport ist die Idee, dass man sowas wie eine Worddateivorlage mitliefern kann. So passt die erzeugte Datei zum CI/CD einer Organisation.
Links: