Kolumne

Hitchhiker’s Guide to Docs as Code: PDF-Output

Gernot Starke, Ralf D. Müller

© S&S Media

In Folge 3 unserer Kolumne hatten wir die Generierung von PDFs aus AsciiDoc bereits kurz angerissen. In dieser Folge gehen wir auf ein paar Details ein, mit denen Sie die Klippen bei der Erstellung von PDFs gezielt umschiffen können (und davon gibts leider noch einige …).
 
 

Listing 1 zeigt den für das PDF relevanten Teil des Build-Skripts. Über tasks.withType(AsciidoctorTask) definieren Sie Standardeinstellungen für alle weiteren AsciidoctorTasks, also alles, was für das Erstellen von beispielsweise HTML genauso gilt wie für PDF.

In dem generatePDF-Block definieren Sie anschließend Einstellungen, die nur für die Erzeugung von PDFs gelten (z. B. pdf-stylesdir), aber auch Einstellungen, die von den anderen AsciidocTasks abweichen. Hierzu gehört der Pfad, in dem die von PlantUML generierten Grafiken abgelegt werden.

import org.asciidoctor.gradle.AsciidoctorTask

plugins {
  id "org.asciidoctor.convert" version "1.5.3"
  id "com.github.ben-manes.versions" version "0.17.0"
}

apply plugin: 'groovy'

asciidoctorj { version = '1.5.4' }

dependencies {
  asciidoctor 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.15'
  asciidoctor 'org.asciidoctor:asciidoctorj-diagram:1.5.4.1'
}

tasks.withType(AsciidoctorTask) { docTask ->
  sourceDir = new File ("$projectDir/src/docs")
  sources {
    include 'master.adoc'
  }
  attributes (
    'source-highlighter': 'coderay',
    toc: 'left',
    icons: 'font',
    sectlink: true,
    sectanchors: true,
    numbered: true
  )
  // good to see what the build is doing...
  logDocuments = true

  requires = ['asciidoctor-diagram']

}

task generatePDF (
  type: AsciidoctorTask,
  group: 'docToolchain',
  description: 'use pdf as asciidoc backend') {

  attributes (
    'pdf-style': 'custom',
    'pdf-stylesdir': 'config/pdfTheme',
    plantUMLDir: buildDir.canonicalPath+'/asciidoc/pdf/images/plantUML/'
  )
  backends = ['pdf']
}

Kreatives Zusammenspiel

Als aufmerksamer Leser unserer Kolumne wissen Sie, dass wir bislang keinen Pfad zu den von PlantUML erzeugten Grafiken angeben mussten. Asciidoctor weiß bei der Generierung des HTML-Outputs, wo diese Grafiken liegen. Auch die aktuelle Betaversion der asciidoctor-pdf Library weiß, wo sie die Grafiken erwartet. Leider entspricht das momentan nicht der Location, wo die asciidoctor-diagram Library sie hinlegt.

Dieses Problem lösen Sie ganz einfach, indem Sie bei der Definition der Diagramme den absoluten Pfad zu den Grafikdateien mitgeben. Und die Definition des absoluten Pfads geschieht ganz einfach durch den Aufruf canonicalPath, was in Groovy die Kurzform von getCanonicalPath() ist (siehe Ende Listing 1). Definieren Sie nun Ihr PlantUML-Diagramm wie folgt:

[plantuml, {plantUMLDir}test2, png]
----
a->b
----

So zwingen Sie die Diagram und PDF Library auf das gleiche Verzeichnis. In einem analogen generateHTML-Task setzen Sie die Property plantUMLDir einfach auf einen Leerstring und Sie erhalten für die HTML-Ausgabe das gewohnte Verhalten.

Auch bei den Versionen der unterschiedlichen Libraries sollten Sie auf das Zusammenspiel achten. Die in Listing 1 verwendeten Versionen sind nicht die ganz aktuellen, aber sie spielen stabil zusammen. Die Verlockung ist groß, die eine oder andere Version zu aktualisieren, kann aber langes Debuggen nach sich ziehen. Wir übernehmen keine Gewähr für andere Stände.

Mit Themes zum richtigen Stil

Was dem HTML das CSS-Stylesheet ist, ist dem Asciidoctor-PDF das Theme. Am Ende von Listing 1 sehen Sie, wie über die Properties

'pdf-style': 'custom',
'pdf-stylesdir': 'config/pdfTheme',

das zum sourceDir relative Verzeichnis des gewünschten Themes und der Name angegeben werden. In diesem Beispiel definieren wir also das Theme mit dem Namen /src/docs/config/pdfTheme/custom-theme.yml.

Wenn Sie alle Features von Asciidoctor wie Admonitions, Aufzählungen und Call-outs verwenden wollen, dann empfehlen wir, bei den Standardschriftarten zu bleiben. Nur zu leicht definiert man eine Schrift, die nicht die Unicodezeichen für das entsprechende Feature enthält – und die Fehlersuche wird zur abendfüllenden Beschäftigung.

PDF-Spezifika

Ansonsten ist ein PDF-Theme eine flexible und im Asciidoctor Theming Guide gut dokumentierte Angelegenheit . Wichtig sind hierbei genau die Spezifika, die Sie nur bei einem seitenorientierten Format wie PDF – im Gegensatz zu HTML – benötigen.

So können Sie sehr flexibel unterschiedliche Kopf- und Fußzeilen für gerade und ungerade Seiten definieren, und auch eine einfache Titelseite geht leicht von der Hand: Einfach eine Überschrift der Ebene 0 mit nur einem vorangestellten = definieren.

Seitenumbrüche fügen Sie durch die Zeichenfolge <<<< ein. Sie werden für PDFs wie auch für DocBook und Word berücksichtigt. Aber auch in HTML werden sie unsichtbar eingebaut und kommen dort beim Druck des HTML-Dokuments zum Vorschein.

Auch Links verhalten sich bezüglich der Darstellung im PDF etwas anders als im HTML, denn in einem gedruckten PDF lässt sich schlecht auf einen Link klicken. Dieses Verhalten müssen Sie zuerst in Ihrem Dokument durch Setzen des Attributs :show-link-uri: in Ihrem Dokument aktivieren. Dieses Attribut scheint sich nicht auf die HTML-Ausgabe auszuwirken, sodass Sie hier keine Unterscheidung treffen müssen. In Ihren PDF-Dokumenten erscheint jetzt hinter jedem Link zusätzlich der URL in eckigen Klammern.

Grafiken

An dieser Stelle möchten wir Ihnen noch einen ganz kurzen Tipp zu Grafiken mitgeben. Das PDF-Format ist prädestiniert für Vektorgrafiken und somit für PlantUML-Diagramme im SVG-Format. Wenn Sie jedoch planen, Ihre Dokumentation in verschiedenen Formaten zu publizieren, verwenden Sie besser das Portable Network Graphics Format, kurz PNG. Das wird in allen Ausgabeformaten wie HTML, Word, PDF und Confluence korrekt dargestellt.

Fazit

Sie sind nun in der Lage, Ihre Dokumentation auch als PDF zu generieren. Damit werden auch Anforderungen zum Druck und der Archivierung Ihrer Dokumentation erfüllt. Ein ausführbares Beispiel finden Sie wieder in unserem GitHub Repository .

Im nächsten Teil unserer Kolumne zeigen wir Ihnen dann, wie Sie auch Webseiten in ähnlicher Weise wie Ihre Dokumentation mit AsciiDoc generieren können. Bis dahin: Treat your Docs as Code!

Geschrieben von
Gernot Starke
Gernot Starke
    Informatikstudium an der RWTH Aachen, Dissertation über Software-Engineering an der J. Kepler Universität Linz. Langjährige Tätigkeit bei mehreren Software- und Beratungsunternehmen als Softwareentwickler, -architekt und technischer Projektleiter. 1996 Mitgründer und technischer Direktor des „Object Reality Center“, einer Kooperation mit Sun Microsystems. Dort Entwickler und technischer Leiter des ersten offizielle Java-Projekts von Sun in Deutschland. Seit 2011 Fellow der innoQ GmbH.  
Ralf D. Müller
Ralf D. Müller
Ralf D. Müller arbeitet als Architekt und Entwickler. Er erlebt täglich die Notwendigkeit effektiver Dokumentation. Außerdem ist er erklärter AsciiDoc-Fan und Committer bei arc42 sowie Gründer des docToolchain-Projekts.
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: