Von AsciiDoc zum barrierefreien PDF/UA

#Simple Helfer

In unserer täglichen Praxis entstehen laufend umfangreiche Schriftstücke. Viele von ihnen sind technischer Natur: Dokumentationen, Spezifikationen, Recherche- und Analyseergebnisse, Test- und Audit-Berichte, Konzepte und Protokolle. Manche Dokumente entstehen parallel zu Programmierungen und landen zusammen mit irgendwelchem Quellcode in einem Software-Versionierungssystem, etwa in unserer Gitlab-Instanz oder im Bitbucket der Kundschaft.

In der Regel steckt wenig Expressionismus in solchen Dokumenten — die Palette an wirklich notwendigen Gestaltungsmöglichkeiten ist sehr überschaubar. Ein bisschen fett hier, eine Liste oder Tabelle dort, vielleicht mal ein Bild oder zwei. Eindeutig wichtiger ist da schon die saubere Struktur der Dokumente, und dass man möglichst wenig falsch machen kann. Kommen wir zum Punkt: Genau hier schlägt die Stunde von Markdown, dem supersimplen Textformat, in dem ich gerade diesen Blogartikel verfasse. Oder AsciiDoc, das ähnlich funktioniert, aber mehr Ausdrucksmöglichkeiten als Markdown hat. AsciiDoc hat sich bei uns im Team inzwischen zum Liebling für technische Dokumente entwickelt.

Manche unserer Schriftstücke sind allerdings für die Weitergabe nach draußen gedacht. Und da wird schnell klar, dass wir bis auf Weiteres kaum jemanden mit Markdown oder AsciiDoc kommen brauchen. Zur Verdeutlichung des Klientels, dass wir mit unseren Werken gelegentlich erreichen müssen, ein Beispiel, wie es sich letzte Woche ernsthaft zugetragen hat: Da erhielt ich eine E-Mail-Nachricht, mit einer PowerPoint-Präsentation im Anhang, darin ein Screenshot von einem im Browser geöffneten PDF (dem Corporate Design Guide, der uns seit Wochen hätte vorliegen sollen). Keine Pointe. Da wären wir wieder. Hello again, PDF!

#Formatting Objects

Wie bei Herrn Nielsen liegt meine erste ernsthafte Affäre mit PDF bereits 20 Jahre in der Vergangenheit. Damals hatte ich XSL-FO (Extensible Stylesheet Language – Formatting Objects) für mich entdeckt — einen XML-Dialekt zur Beschreibung grafisch gestalteter Dokumente, der sich unter anderem für die Produktion hochwertiger Druckerzeugnisse eignet. XSL-FO kann mit Hilfe geeigneter Umwandlungsprogramme, sogenannter Prozessoren, in verschiedene Formate übersetzt werden: In Reintext oder in PNG-Bilder, ins Rich Text Format oder in Hewlett-Packard's Printer Command Language (PCL), in SVG-Grafiken — oder eben auch in drucktaugliche PDF-Dokumente.

Natürlich war ich vor allem am Einsatz im Web-Kontext interessiert, etwa zur dynamischen Generierung von PDF-Produktdatenblättern im Hintergrund einer Website. XSL-FO war damals noch sehr jung, alle verfügbaren FO-Prozessoren hochexperimentell und durchweg in Java implementiert, weshalb ein Einsatz in den üblichen Hosting-Umgebungen quasi unmöglich war. Und hupsi: Kaum hatte ich mich versehen, schon steckten eineinhalb Jahre Entwicklungsarbeit in phop, meinem eigenen kleinen, PHP-basierten FO-Prozessor. Das muss etwa um 2002 herum gewesen sein, und immerhin hat phop eine Weile lang im bescheidenen Maß seinen Dienst hinter den Kulissen von ein paar kleinen Websites verrichtet, bevor ich das Projekt schließlich aufgab.

#Apache FOP

Der mitunter älteste, quelloffene und frei verfügbare FO-Prozessor ist der Apache FOP. Erstaunlicherweise hat seine Weiterentwicklung nach langem Stillstand in den letzten Jahren wieder etwas an Fahrt gewonnen. Begünstigt durch die Tatsache, dass wir in immer mehr Hosting-Umgebungen Java zur Verfügung hatten, konnten wir über die Jahre einige Lösungen auf Basis von XSL-FO und dem Apache FOP implementieren — so kommen beispielsweise die dynamisch generierten Fahrzeug-Exposés bei Fischer Automobile mit dieser Technik zustande.

Manche fragen vielleicht: Was können XSL-FO und Apache FOP, das die bekannten freien PHP-Bibliotheken wie FPDF und TCPDF nicht können? Die Antwort ist simpel, aber ein echter Game Changer: Mit den genannten Bibliotheken muss jeder Block, jede Zeile einzeln positioniert und dimensioniert werden. Es ist Aufgabe des erzeugenden Programms, die Einhaltung von Begrenzungen sicherzustellen und etwa bei Bedarf neue Seiten anzulegen. Die Erzeugung umfangreicher und komplexer Dokumente und Layouts kann schnell zum unüberschaubaren Albtraum werden. Anders beim FO-Prozessor: Er übernimmt vollautomatisch den Textfluss, wie man es von Office-Programmen her kennt, passt Inhalte in Begrenzungen ein, sorgt für Umbrüche und Spaltigkeit, Seitenzahlen und Fußnoten. Statt Positionen und Dimensionen definieren Formate und Regeln, wie der Prozessor Inhalte anordnet und gestaltet. Kurzum: Formatting Objects sind die weitaus intelligentere, fortschrittlichere und skalierbarere Technik.

#DocBook

Doch zurück zum eigentlichen Thema. Wenn AsciiDoc das Format ist, in dem wir gerne schreiben, und PDF das Format, in dem unsere Kundschaft gerne liest, wie kommen wir dann möglichst einfach vom einen zum anderen Format? Und: Wie können wir dabei am besten auch unseren Anspruch verwirklichen, möglichst konsequent barrierefrei zu kommunizieren?

Der erste Teil der Antwort heißt DocBook: Ein weiterer XML-Dialekt, der speziell für die Auszeichnung von — nicht nur, aber vor allem — technischen Texten, Artikeln und Büchern entwickelt wurde. Passenderweise kann das offizielle Kommandozeilen-Programm asciidoc das AsciiDoc-Format direkt in DocBook (Version 4.5) übersetzen.

Die restliche Strecke erledigen schließlich die ebenfalls frei verfügbaren DocBook XSLT 1.0 Stylesheets: Mit ihnen lassen sich DocBook-Dokumente direkt in XSL-FO übersetzen — und hier schließt sich der Kreis, denn zwischen XSL-FO und PDF liegen dank Apache FOP ja bekanntermaßen nur noch ein paar Sekunden …

#PDF/UA

Für alle diejenigen, denen das zu kompliziert war, hier nochmal in ganz, ganz einfach:

#Alles fügt sich

Es gibt also tatsächlich eine funktionierende Umwandlungskette, mit der man aus AsciiDoc-Texten reproduzierbar barrierefreie PDF-Dokumente erzeugen kann — zumindest, wenn man ein bisschen nachhilft:

• Das asciidoc-Programm verliert standardmäßig unterwegs die Dokumentbeschreibung und ein paar andere Merkmale, die im PDF nützlich sind.
• Die DocBook XSLT-Stylesheets übernehmen oder erzeugen von Haus aus nicht alle Merkmale, die für ein barrierefreies PDF/UA notwendig sind.
• Die Unterstützung des PDF/UA-Standard im Apache FOP wurde in den letzten Jahren zwar stark verbessert, aber im Detail ist noch Luft nach oben. Wenigstens barrierefreie Fußnoten würden wir schon gerne nutzen …

Das ist aber alles halb so wild, wenn man sich zu helfen weiß: asciidoc kann mit einer Konfigurationsergänzung hingebogen werden, die XSLT-Stylesheets unterstützen ohnehin individuelle Anpassungen über ein Customization Layer, und auch der Java-Quellcode des Apache FOP lässt sich patchen. Wer ein klares Ziel vor Augen hat, der lässt sich eben nicht aufhalten. ;)

#adoc2pdfua

Schlussendlich sind am skizzierten Workflow doch einige individuell angepasste Programme und Konfigurationen beteiligt. Von den Anwendungen sind manche schon unter Linux nicht ganz einfach in Betrieb zu nehmen. Dabei arbeiten wir doch überwiegend unter Windows und würden auch und vor allem dort gerne barrierefreie PDFs erzeugen, möglichst ohne aufwendige Installations- und Wartungsorgien. Was tut also der geneigte Nerd in solchen Situationen? Richtig: Er fällt nach vorne, packt alles in ein Docker-Image namens adoc2pdfua, installiert sich benutzerdefinierte Kontextmenüeinträge und konvertiert drauf los. Wie das in der Praxis aussieht, zeigt das folgende Video.