FAQs

Wie kann ich die Beschriftungen für Elemente wie Tabellen, Abbildungen, etc. anpassen?

In der Asciidoctor-Dokumentation findet man unter Using Asciidoctor with Other Languages Attribute und Möglichkeiten für das Anpassen und Übersetzen von Beschriftungen.

Folgend ein paar ausgewählte Dokument-Attribute, die die standardmäßig in englisch vorgegebene Beschriftung umbennen:

:toc-title: Inhaltsverzeichnis
:table-caption: Tabelle
:figure-caption: Abbildung

Alternativ lassen sich diese auch sprachabhängig oder angepasst aus dem Asciidoctor Projekt übernehmen:

  1. Im Dokumentenverzeichnis wird ein Ordner locale angelegt.

  2. In dieses Verzeichnis werden aus dem Asciidoctor-Repository die Dateien attributes.adoc und attributes-de.adoc kopiert.

  3. Dokument-Attribute wir folgt ergänzen:

    :lang: de
include::locale/attributes.adoc[]

Wie kann ich einen Teil einer Quelltextdatei als (ausklappbaren) Code-Block einbinden?

Mit dem Attribut lines wird beim include die Anfangs- und Endzeile getrennt durch .. des einzubindenden Abschnittes festgelegt. Es ist auch möglich mehrere Abschnitte aus einer Datei mit lines=2..4;8..12 festzulegen. Eine Angabe von -1 für die Endzeile bedeutet bis zur letzten Zeile.

Weitere Hinweise und Varianten (bspw. Tags) findet man im offiziellen User Manual: Select Portions of a Document to Include.

Syntax
.Ergebnis
[source,c]
----
include::src/code.c[lines=2..5] (1)
----
Ergebnis
fgets(vBuf, 128, stdin);
x = atof(vBuf);
1 Es werden die Zeilen 2 bis 5 inkludiert.
Syntax mit aufklappbarem Block
.Ergebnis (1)
[%collapsible] (2)
====
[source,c]
----
include::src/code.c[lines=11..12]
----
====
Ergebnis 
fgets(vBuf, 128, stdin);
x = atof(vBuf);
1 Titel des aufklappbaren Blockes
2 Das Makro [%collapsible] erzeugt im generierten HTML Dokument einen aufklappbarer Block mit allem, was sich zwischen den Blockbegrenzungen ==== befindet.

Wie kann ich Bilder und Diagramm besser einbinden?

Um Schreibfehler beim mehrfachen Verwenden der Angaben eines Bildes bei der Einbindung im Dokument zu vermeiden, ist es sinnvoll, diese vorab als Attribute zu definieren. Attribute können für jedes weitere Bild wieder neu gesetzt werden.

Einbindung eines Bildes
:imageTitle: Ich bin ein Bildtitel (1)
:imageFile: image-file.jpg (2)
:imageWidth: 800 (3)
image::{imageFile}[title="{imageTitle}", alt="{imageTitle}", width={imageWidth}] (5) (6)
:imageTitle: Ich bin ein Bildtitel (1)
:imageFile: image-file.jpg (2)
:imageWidth: 800 (3)
:imageID: id01 (4)
image::{imageFile}[title="{imageTitle}", alt="{imageTitle}", id="{imageID}", width={imageWidth}] (5) (6)
1 Attribut für den Bildtitel und Alternativtext. Unterscheiden sie sich, kann ein :imageAlt: dafür verwendet werden.
2 Attribut für den Dateinamen mit Dateiendung
3 (optional) Angabe der Bildbreite
4 (optional) Vergabe einer ID, welche im Dokument als Sprungmarke verwendet wird. Alternativ geht auch ein [#id01] ohne dem id="{imageID}" Attribut.
5 Einbindung des Bildes (Blocksyntax) mit Hilfe der Attribute.
6 Weitere optionale Attribute:

  • width= …​ gibt die Ausgabebreite des Bildes an

  • link= …​ Link auf sich selbst oder ein anderes Ziel
Einbindung eines PlantUML-Diagrammes (Beispiel für ein Block Macro)
:diagramTitle: Asciidoctor mit PlantUML (1)
:diagramFile: asciidoctor-with-plantuml (2)
plantuml::{plantumlsdir}/{diagramFile}.puml[title="{diagramTitle}", alt="{diagramTitle}", format="svg", target="{diagramsdir}/{diagramFile}"] (5)
:diagramTitle: Asciidoctor mit PlantUML (1)
:diagramFile: asciidoctor-with-plantuml (2)
:diagramWidth: 800 (3)
:diagramID: id02 (4)
plantuml::{plantumlsdir}/{diagramFile}.puml[title="{diagramTitle}", alt="{diagramTitle}", id="{diagramID}", format="svg", target="{diagramsdir}/{diagramFile}", width=800, link="{imagesdir}/{diagramsdir}/{diagramFile}.svg", subs=attributes+] (5) (6)
1 Attribut für den Diagrammtitel und Alternativtext. Unterscheiden sie sich, kann ein :diagramAlt: dafür verwendet werden.
2 Attribut für den Dateinamen ohne Dateiendung, da der Dateiname als Name für die generierte Datei genommen wird. So wird aus diagram.puml eine diagram.svg Datei.
3 (optional) Angabe der Bildbreite
4 (optional) Vergabe einer ID, welche im Dokument als Sprungmarke verwendet wird. Alternativ geht auch ein [#id02] ohne dem id="{imageID}" Attribut.
5 Einbindung des Diagrammes (Asciidoctor Diagram) mit Hilfe der Attribute.

  • format= …​ Zielformat des generierten Diagrammes

  • target= …​ Zielordner, in welchem das generierte Diagramm abgelegt wird. Ist ein globales :imagesdir: gesetzt, befindet der Zielordner darin.
6 Weitere optionale Attribute:

  • width= …​ gibt die Ausgabebreite des Diagrammes an

  • link= …​ Link auf sich selbst oder ein anderes Ziel

  • subs=attributes+ …​ Attribute des Asciidoctor-Dokumentes werden an das PlantUML-Diagramm durchgereicht

Wie verwende ich Silbentrennung im PDF Export?

Damit Silbentrennung in den exportierten PDF-Dokumenten angewendet wird, muss das RubyGem text-hyphen installiert und zwei Dokumentenattribute vorhanden sein.

  1. Vorbereitung (Asciidoctor - Installation und Konfiguration):

    $ gem install text-hyphen

  2. Dokumentenattribute:

    :lang: DE
:hyphens:

Die generierten PDF-Dokumente enthalten jetzt eine Silbentrennung, was gerade für Texte in Tabellen sinnvoll ist.

Wie kann ich mehrere Bilder nebeneinander ausgeben?

Am einfachsten kann man Bilder nebeneinander als inline-Makro (Variante 1) ausgeben:

Variante 1: Bilder ohne Titel als inline-Bilder (HTML, PDF)
Code:
image:test.jpg[test, width=200]
image:test.jpg[test, width=200]
image:test.jpg[test, width=200]
Ergebnis:

test test test

Möchte man zusätzlich die Abbildungsbezeichnung mit ausgeben, wofür das block-Makro verwendet wird, wären mögliche Lösungen die Varianten 2 und 3:

Variante 2: Bilder mit Titel und Textposition mit float (left/right), nur für HTML
Diese Variante funktioniert nur für die Generierung von HTML-Dokumenten. In PDFs werden Sie untereinander angeordnet.
Code:
[.clearfix] (1)
--
.Testbild 1 (2)
image::test.jpg[test, width=200, float="left"] (3)
.test2
image::test.jpg[test, width=200, float="left"]
.test3
image::test.jpg[test, width=200, float="left"]
--
1 Aufheben des float-Verhaltens nach dem ---Block.
2 Bildtitel
3 Bild als block-Makro mit float="left"
Ergebnis:
test
Abbildung 1. Testbild 1
test
Abbildung 2. Testbild 2
test
Abbildung 3. Testbild 3
Variante 3: Bilder mit Titel und Tabelle mit ausgeblendeten Linien (HTML, PDF)
Code:
[%autowidth, frame=none, grid=none, cols="3*a"] (1)
|===
| .Testbild 1 (2)
image::test.jpg[test, width=200]
| .Testbild 2
image::test.jpg[test, width=200]
| .Testbild 3
image::test.jpg[test, width=200]
|===
1 Die Angabe der Spaltenanzahl X in cols=X*a muss zur Bildanzahl passen.
2 Angabe des Bildes mit Titel und als block-Makro image::.
Ergebnis:
test
Abbildung 4. Testbild 1
test
Abbildung 5. Testbild 2
test
Abbildung 6. Testbild 3

Wie kann ich eigene HTML-/CSS-formatierte Inhalte einbinden?

Eigene Stylesheets und HTML-Codes können über ein Docinfo File und Passthrough Blocks in das Asciidoc-Document aufgenommen.

Details
docinfo.html
<link rel="stylesheet" media="screen" type="text/css" href="file.css" />
Variante: html-Code
++++
<div class=""><p>...</p></div>
++++
Variante: html-Datei
++++
include::file.html[]
++++

Ein Beispiel ist in meinem Asciidoctor-Playground auf GitHub zu finden.

Bugs & Bugfixes

Warum erscheint beim erzeugen eines PDFs die Fehlermeldung "PNG uses unsupported interlace method"?

Es gibt im Dokument Bilder, welche mit einem nicht unterstützten Interlacing-Format erstellt wurden. Dies kann beim Erstellen von PDF-Dokumenten aus Asciidoctor heraus zu obigem Fehler und dem Nichteinfügen führen.

Fehlermeldung:
% asciidoctor-pdf documentation.adoc
asciidoctor: WARNING: could not embed image: /.../example.png; PNG uses unsupported interlace method; install prawn-gmagick gem to add support

Lösungsvariante 1

Öffnen Sie die betreffenden Bilder in einem Bildbearbeitungsprogramm ihrer Wahl und speichern Sie diese erneut als PNG-Datei ab. (Falls vorhanden, im Speichern-/Exportieren-Dialog ggf. entsprechende Interlacing-Einstellungen beachten.)

Lösungsvariante 2

Installieren Sie, wie in der obigen Fehlermeldung erwähnt, noch zusätzlich das RubyGem prawn-gmagick:

% gem install prawn-gmagick

Warum funktioniert in Visual Studio Code die Anzeige von Bildern in der Vorschau eines AsciiDoc-Dokumentes nicht?

Grund könnte ein Fehler in der aktuellen AsciiDoc Extension (2.8.3, 2.8.4) von VS Code sein. Hier hilft es die Bilder direkt als data url in das HTML-Dokument für die Vorschau generieren zu lassen.

Das kann in den Einstellungen von VS Code unter: Preferences  Extensions  Asciidoc → Asciidoc: Preview Attributes → Edit in settings.json angepasst werden. Hier wird ein "data-uri": "" in den "asciidoc.preview.attributes": {} Bereich eingefügt:

"asciidoc.preview.attributes": {
    "data-uri": ""
},

Der Bugfix hat keine Auswirkung auf das Generieren der Dokumente mit den asciidoctor Kommandos im Terminal, sondern bezieht sich nur auf die Vorschau in VS Code.