AA_123rf-27405198_belchonock-123RF.jpg

© belchonoc, 123RF

Mit AsciiDoc aus einem Quelltext viele Formate erzeugen

Aus einer Quelle

Das Markdown-Format bietet die Möglichkeit, ohne verwirrende Tags einen Text zu erstellen, den Sie dann in verschiedenste Ausgabeformate konvertieren.

Einmal schreiben, überall veröffentlichen – die Idee von AsciiDoc [1] ist alt: aus einem in einem speziellen Format abgefassten Dokument über einen Konverter Varianten des Dokuments in unterschiedlichen Formaten zu erzeugen. Daran haben sich schon viele Entwickler versucht, meist mit eher mäßigem Erfolg.

Für das System spricht, dass etliche Entwickler aktiv an dem Projekt arbeiten und es weite Verbreitung genießt. Das schürt die Hoffnung, dass es im Wesentlichen so funktioniert, wie es die Dokumentation verspricht. Inzwischen nehmen sogar einige Verlage Quelltexte in diesem Format an oder nutzen es zumindest intern für ihre Zwecke. Der damit quasi industrielle Einsatz spricht ebenfalls für AsciiDoc.

Das System besteht aus dem Quelltext und einem Konverter, der Ersteren in die entsprechenden Ausgaben umwandelt. Die einzelnen Formate erzeugt die Software über sogenannte Backends. Die Tabelle "Ausgabe" zeigt, welche Backends AsciiDoc kennt und was sie erzeugen.

Ausgabe

Backend Formate
docbook5 Docbook (aktuelle Version), PDF
docbook45 Docbook (verbreitete Version), PDF
xhtml11 HTML 1.1 (voreingestellt)
html4 HTML 4
html5 HTML 5
slidy (X)HTML-Präsentationen
wordpress Webseiten, Blogs, CMS
latex Standard-LaTeX (für PDF Fineprint)
epub E-Books

Das Designziel des Markups für die Quelltexte war ein für Menschen leicht verständliches Format, das dennoch relativ weitreichende Möglichkeiten mitbringt. Dazu gehört unter anderem, alle üblichen Auszeichnungen und Strukturen zu unterstützen, die heute im Alltag zum Einsatz kommen. Das schließt neben den hierarchischen Ebenen zum Gliedern eines Texts auch Verweise innerhalb des Dokuments sowie URLs auf externe Inhalte ein. Darüber hinaus ermöglicht die Software das Einbetten von Stichwörtern, Indizes und Fußnoten, literarischen Referenzen sowie Bildern und Tabellen.

Bei AsciiDoc orientierten sich die Entwickler an vielen der ohnehin schon weit verbreiteten Konventionen für Textdateien. Vieles kommt Ihnen vermutlich bekannt vor, da Sie es wahrscheinlich schon verwendet haben – etwa beim Unterstreichen einer Überschrift mit Istgleich-Zeichen oder dem Markieren eines Listenpunkts mit einem Sternchen am Zeilenanfang.

Absätze, das wohl wichtigste Element zum Gliedern eines Texts, erzeugen Sie durch eine Leerzeile. Beginnt der Fließtext eines Absatzes nicht in der ersten Spalte, also mit mindestens einem Leerzeichen oder Tabulator, behandelt AsciiDoc den gesamten Absatz besonders und übernimmt ihn wortwörtlich, ohne Interpretation der enthaltenen Formatierungen. Das schlägt sich in einer Schrift mit fester Laufweite bei der Ausgabe nieder.

AsciiDoc unterstützt zudem eine spezielle Form der Absatzformatierung: In der Zeile vor dem fraglichen Absatz darf eine Anweisung der Form [Typ] in einer ansonsten leeren Zeile stehen (Listing 1), wobei AsciiDoc zwischen vier solcher Typen unterscheidet (siehe Tabelle "Absatztypen").

Absatztypen

Anweisung Ergebnis
verse Normale Schrift, berücksichtigt harte Zeilenumbrüche (linksbündiger Satz).
quote Normale Schrift, quasi ausgeglichener Satz.
listing Schrift mit fester Laufweite, grau unterlegt, berücksichtigt harte Zeilenumbrüche, linksbündig.
literal Schrift mit fester Laufweite, berücksichtigt harte Zeilenumbrüche, linksbündig.

Listing 1

...
[listing]
Hier beginnt der grau unterlegte Absatz.
...

Mehrere aufeinanderfolgende Leerzeichen im Fließtext fasst AsciiDoc beim Konvertieren zusammen. Um an besonderen Stellen Leerraum fest einzufügen, benötigen Sie spezielle Zeichen ("non breakable spaces"), die Sie mit {nbsp} erzeugen – davon dürfen Sie mehrere hintereinander setzen. Klassische Auszeichnungen im Text bedienen sich der verbreiteten Markdown-Syntax (siehe Tabelle "Markdown in Kürze").

Markdown in Kürze

Anweisung Ergebnis
*Text* Fettdruck
_Text_ Kursivierung
'Text' Kursivierung
+Text+ literaler Text in einer Schrift mit fester Laufweite
`Text` literaler Text in einer Schrift mit fester Laufweite

Die zum Gliedern erforderlichen Ebenen erzeugen Sie bei Bedarf auf zwei Arten: entweder durch einzeilige Anweisungen oder durch eine Variante auf zwei Zeilen. Die sogenannten Singleline Header (siehe Tabelle "Ebenen") erkennen die Konverter nur korrekt, wenn Sie diese tatsächlich in einer Zeile angeben – dafür dürfen die abschließenden Tags fehlen.

Ebenen

Anweisung Ergebnis
= Text = Titel des Dokuments
== Text == Kapitel
=== Text === Abschnitt
==== Text ==== Unterabschnitt
===== Text ===== Abschnitt des Unterabschnitts

Alternativ unterstreichen Sie Überschriften mit unterschiedlichen, die Ebene der Gliederung kennzeichnenden Zeichen (Listing 2): für die erste Ebene mit Gleichheitszeichen, für die zweite mit Minuszeichen, bei der dritten mit Tilden, dann mit dem Caret und schließlich auf der untersten Ebene mit Pluszeichen.

Listing 2

Titel des Dokuments
=======Kapitel
-------Abschnitt
~~~~~~~Unterabschnitt
^^^^^^^Abschnitt des Unterabschnitts
+++++++

Das Beispiel der Gliederungsebenen zeigt einige der wesentlichen Features von AsciiDoc: So gibt sich das Format recht flexibel – etwa dadurch, dass es unterschiedliche Formatierungen im Quelltext zulässt. Das sorgt aber andererseits für eine gewisse Unklarheit. Ähnliches gilt ebenfalls für die Möglichkeit, abschließende Tags bei den einzeiligen Markierungen auszulassen: Das ist zwar komfortabel, erschwert es aber manchmal, Fehler zu finden, die das Konvertieren verhindern. Dieses Problem tritt beim Einsatz mehrzeiliger Tags ebenfalls auf: Diese verursachen in der Praxis erheblich mehr Probleme als ihre einzeiligen Pendants.

In der Zeile vor Überschriften dürfen Sie zusätzlich Anker setzen, sprich: ein Label für Verweise (Listing 3). Die ersten Zeilen eines Dokumentes reserviert AsciiDoc für besondere Aufgaben: Neben dem Titel des Dokuments geben Sie dort optional den Namen des Autors, eine Mailadresse und eine Revisionsnummer samt Datum ein. Diese Angaben verwendet die Software sowohl für die Metadaten des Dokuments wie auch in der Ausgabe als lesbare Information.

Listing 3

[Label]
=== Überschrift des Abschnitts

Verweise und Links

Bei Verweisen innerhalb eines Dokumentes erzeugt [[Label]] den Anker, auf den Sie an beliebiger Stelle im Text mit <<Label>> oder <<Label,Text>> verweisen. Obwohl AsciiDoc laut Beschreibung voll auf Unicode setzt, führen Sonderzeichen im Label zu Problemen beim Konvertieren. Der oben erwähnte Text für den Verweis entschärft die Situation etwas: Die Software setzt ihn an den Stellen ein, an denen der Verweis im Fließtext steht, und erlaubt darin beliebige Zeichen.

Fehlt der Verweistext, setzt AsciiDoc beim Konvertieren stattdessen das zuvor definierte Label oder ein anderes Element ein. Die Regeln dafür, was die Software dazu verwendet, gestalten sich vielfältig: Bei Abschnitten etwa kommt der Text der Überschrift zum Einsatz.

Auf andere Dokumente verweisen Sie in einer der in den ersten beiden Zeilen von Listing 4 gezeigten Formen. Pfade geben Sie, falls erforderlich, zusammen mit dem Dateinamen an. Für URLs nutzen Sie eine einfache Syntax (Listing 4, Zeile 3 und 4). Beides erkennt das Programm automatisch an dem Schlüsselwort http:. Das Gleiche gilt für Mailadressen (Zeile 5 und 6).

Listing 4

link:Dateiname#ID
link:Dateiname#ID[Text]
http://Adresse
http://Adresse[Text]
mailto:Adresse
mailto:Adresse[Text]

Bilder kann AsciiDoc auf zwei unterschiedliche Arten einbinden: Im Fließtext als "inline graphics" oder als eigenen Block, quasi als Bild-Absatz. Das Schlüsselwort images: kommt für Bilder im Fließtext zum Einsatz:

images:Dateiname[Text]

Selbst wenn ein Text fehlt, müssen Sie die eckigen Klammern immer angeben. Tatsächlich darf der Text zum Beschriften zusätzliche Formatierungen für das Bild enthalten, beispielsweise eine Größenangabe in der Form height=14pt.

Setzen Sie die Grafiken in einen eigenen Absatz, dann besteht der erste Teil des Schlüsselworts aus images, gefolgt von zwei Doppelpunkten. Danach tragen Sie den Dateinamen ein (optional mit Pfad) gefolgt von den eckigen Klammern. In diese dürfen Sie einen Text eintragen, zwischen doppelten Hochkommas nach dem Schlüsselwort caption=. Alternativ – und übersichtlicher – ist aber die in Listing 5 verwendete Form, die zusätzlich noch ein Label für die Grafik definiert.

Listing 5

[[Label]]
.Text
images::Dateiname[Optionen]

Listen gehören zu den Elementen, die sich mit AsciiDoc wirklich gut formatieren lassen. Besonders einfach geht das mit Aufzählungen, die Spiegelstriche verwenden: Hier leiten Sie die Zeile mit einem Minuszeichen oder einem Sternchen ein. Erhöhen Sie die Anzahl der führenden Zeichen, erhöhen Sie zugleich die Tiefe der Ebene.

Nach einem ähnlichen System gestalten Sie nummerierte Listen. Dabei schaltet AsciiDoc in jeder Ebene die Art des Nummerierens um (Listing 6). Noch eleganter klappt das mit der Punkt-Form: Stellen Sie der Zeile einen bis maximal fünf Punkte voran, so entstehen im Ergebnis nummerierte Listen nach den oben genannten Kriterien.

Listing 6

1. Dezimalzahlen
a. Kleinbuchstaben
F. Großbuchstaben
iii) kleine römische Zahlen
IX) große römische Zahlen

Sie dürfen die Typen der Listen mischen und verschachteln, müssen dann aber sehr genau auf Leerzeilen achten, damit AsciiDoc erkennt, welche Elemente zusammengehören und wo eine Liste endet. Da dies erfahrungsgemäß oft zu Schwierigkeiten führt, hilft es, zunächst die Listen in einer separaten Datei zu speichern und testweise zu übersetzen. Funktioniert alles, fügen Sie den Code in das Dokument ein.

Um ein weiteres Strukturelement handelt es sich bei den sogenannten Delimited Blocks, Strukturen, die bestimmte Formatierungen verwenden, wie bei der Anzeige von Quelltexten. Im LaTeX-Jargon hießen diese "Umgebungen". Zunächst definieren Sie zwischen den eckigen Klammern die Variante der Umgebung, dann folgt durch eine Reihe von speziellen Trennzeichen der Anfang der Umgebung. Normalerweise gibt es mehrere Varianten jeder dieser Umgebungen, die allerdings nicht bei allen Formaten gleichermaßen bereitstehen oder unterschiedlich erscheinen. Listing 7 zeigt die grundlegende Strukturen.

Listing 7

///////////////////Kommentar
///////////////////
-------------------Listing
-------------------
...................Verbatim-Text
...................
*******************Eingerahmter Text
*******************
___________________Zitat (eingerückt)
___________________
+++++++++++++++++++Durchgereichter Code
+++++++++++++++++++

Alle Blöcke beginnen zwingend am Zeilenanfang einer ansonsten leeren Zeile. Sie bestehen aus einer Reihe spezieller Zeichen, wie Sternchen, Minuszeichen oder Ähnliches. Bis eine identische Zeile auftritt, dürfen Sie nun den gewünschten Code eingeben.

In der Zeile vor der den Block einleitenden Zeile legen Sie die Variante, den sogenannten "Style", der Umgebung fest. Das funktioniert allerdings nicht immer; viele der eigentlich vorgesehenen Styles harmonieren nicht mit allen Ausgabeformaten, sondern führen beim Übersetzen zum Abbruch.

Die in Listing 8 gezeigte Open-Block-Struktur beginnt und endet mit zwei Minuszeichen. Sie dient in der Variante abstract für Zusammenfassungen, als partintro nimmt sie die einleitenden Texte für Teile eines Buchs ("Parts") auf. Zudem erlaubt sie das Fortsetzen von Listen [2].

Listing 8

[Variante]
--Code
--

Das AsciiDoc-Tabellenformat liefert für einfache, kurze Inhalte recht gute Ergebnisse. Listing 9 zeigt den Quelltext für eine simple Tabelle. Alle wesentlichen Einstellungen erfolgen über Optionen, die zwischen den eckigen Klammern vor der Tabelle stehen. Die Tabelle selbst erstellen Sie durch Pipe- und Gleichheitszeichen. Bei kurzen Inhalten stellt das kein Problem dar; bei komplexeren Tabellen steigt die Fehlerrate in der Praxis schnell an.

Listing 9

.Tabellenüberschrift
[width="66%",cols="<m,a",frame="all",options="header"]
|======================
|Spaltenüberschrift 1 |Spaltenüberschrift 2
|1        |Item 1
|2        |Item 2
|3        |Ein sehr langer Eintrag, der nicht mehr in eine Zeile passt und automatisch umbrochen wird.
|======================

Die Tabellenoptionen gliedern sich in mehrere Gruppen (siehe Tabelle "Zeilen und Spalten"). Bei AsciiDoc dürfen Tabellen immer eine Kopfzeile – üblicherweise für die Bezeichner der Spalten – und eine Fußzeile umfassen. Beide erhalten spezielle Formate, sofern Sie dieses durch die Schlüsselworte header beziehungsweise footer aktivieren.

Zeilen und Spalten

Option Werte Funktion
grid none, cols, rows, all Linien in der Tabelle
frame topbot, none, sides, all Linien außen
options header, footer Kopfzeile, Fußzeile
format psv, csv, dsv Trennzeichen für Spalten
valign top, bottom, middle Vertikale Ausrichtung
width Prozentwert zwischen 1 und 100 Breite der Tabelle
cols Multiplikator*, Ausrichtung, Weite, Stil Beschreibung für die Spalte

Die Angabe eines Stils für die Spalten verursacht eine Reihe von Nebenwirkungen, wie Sie am Beispiel aus Listing 11 ausprobieren können, indem Sie das Format für die Spalten von a auf v umstellen. Wirklich unübersichtlich gestaltet sich der Einsatz von Formatierungen für die Zellen; Abbildung 1 zeigt ein abschreckendes Beispiel.

Abbildung 1: AsciiDoc erlaubt zwar weitgehende Formatierungen in Tabellen, aber der Quelltext verliert dann zunehmend an Klarheit.

Probleme

Fehler beim Abfassen von AsciiDoc-Dokumenten treten naturgemäß erst beim Übersetzen zutage. Einige Editoren, darunter wie Emacs, unterstützen die Eingabe entsprechender Quelltexte durch spezielle Modi, die zumindest einige einfache Flüchtigkeitsfehler bereits beim Schreiben aufdecken. Komplexere logische oder gar Syntaxfehler finden diese Helfer freilich nicht.

Die AsciiDoc-Dokumentation [3] fällt recht dürftig aus, sodass es sinnvoll ist, die wenigen Beispiele zur Hand zu haben, wenn es an das erste eigene Projekt geht. Einige der Dokumente finden sich auf der Website, darunter ein Artikel, der den Einsatz von Indexen zeigt [4], eine als Artikel formatierte Variante des User Guides [5] sowie eine Vorlage für ein Buch [6], das komplexere Strukturen wie eine Literaturliste, ein Kolophon und eine Widmung vorstellt.

Das Übersetzen mit dem AsciiDoc-Skript in der Form asciidoc Optionen Quelltext sowie der Einsatz der A2x-Toolchain benötigen erstaunlich viel Zeit, um aus relativ einfachen Quelltexten EPUBs oder PDFs zu generieren. Über die Option -v erhalten Sie detailliertere Informationen zum Vorgang.

Bei der reinen Text- oder HTML-Ausgabe sieht es etwas besser aus: Allerdings unterstützen diese Formate nur eine Teilmenge der Möglichkeiten, sodass sie sich bestenfalls für eine Vorschau der Dokumente eignen.

Um den Zeitaufwand zu minimieren, hat sich der Einsatz des Shell-Operators && bewährt: Darüber verknüpfen Sie das Erzeugen einer HTML-Datei mit dem eines aufwendigeren Formats. Die syntaktischen Fehler finden und beheben Sie dann bei der schnelleren HTML-Konvertierung, und nur wenn diese erfolgreich verläuft, erfolgt das Umwandeln in die anderen Formate.

Allerdings garantiert ein erfolgreiches Konvertieren nach HTML noch lange nicht, dass eine PDF-Datei das gewünschte Ergebnis zeigt. Gerade die Ausgabe für den Druck ist eine echte Schwachstelle von AsciiDoc (Abbildung 2). Tatsächlich fällt es relativ schwer, direkt mit AsciiDoc gut gesetzte PDFs zu erzeugen: Hier bietet sich der Zwischenschritt über den LaTeX-Export als Mittel der Wahl an. AsciiDoc erzeugt Standard-LaTeX, das Sie dann nach dem manuellen Bearbeiten in einem weiteren Schritt in ein PDF-Dokument übersetzen.

Abbildung 2: Selbst Dokumente, die sowohl mittels Dblatex als auch mit FOP funktionieren, zeigen bei der PDF-Ausgabe gravierende Unterschiede.

Der Vorteil der zweiten Methode liegt vor allem darin, dass Ihnen dabei alle Möglichkeiten von LaTeX offenstehen, der Aufwand sich jedoch in engen Grenzen hält. AsciiDoc unterstützt aber nur eine kleine Teilmenge der in LaTeX vorhandenen Formate; unter anderem keine Picture-Umgebungen, was deren Einsatz entweder ausschließt oder Sie dazu zwingt, diese nachzureichen.

Diesen Artikel als PDF kaufen

Express-Kauf als PDF

Umfang: 7 Heftseiten

Preis € 0,99
(inkl. 19% MwSt.)

LinuxCommunity kaufen

Einzelne Ausgabe
 
Abonnements
 
TABLET & SMARTPHONE APPS
Bald erhältlich
Get it on Google Play

Deutschland

Ähnliche Artikel

  • Txt2tags 2.6 produziert Asciidoc und Docbook

    Das GPL-lizenzierte Konvertierungstool Txt2tags beherrscht in Version 2.6 neue Ausgabeformate.
  • Etikettenschwindel
    Ein LaTeX-Editor verspricht Komfort bei der Eingabe des komplexen Markups. RTextdoc jedoch leistet sich im Test einige große Schnitzer.
  • Echt einfach
    Einfache Formatierungen für Wikis oder HTML-Seiten erzeugen Sie am schnellsten mit Markdown. Der Editor Utext hilft Ihnen unter Ubuntu und dessen Ablegern beim Erstellen und Bearbeiten solcher Texte.
  • Verknüpft und verwoben
    Quellen und Referenzen sauber und nachhaltig zu verwalten, macht viel Arbeit, ist allerdings für solides wissenschaftliches Arbeiten unabdingbar. Wir stellen die wichtigsten Open-Source-Werkzeuge vor, die Sie dabei unterstützen.
  • Optimiert
    Lädt eine Webseite nur schleppend, sucht man die Schuld schnell bei der Infrastruktur oder dem Webbrowser des Anwenders. Doch das Zusammenspiel von Webserver, Webseite und Browser ist kompliziert. Eine Reihe von Kniffen hilft, das Laden der Webseite zu beschleunigen.
Kommentare

Infos zur Publikation

LU 11/2017: Server für Daheim

Digitale Ausgabe: Preis € 8,50
(inkl. 19% MwSt.)

LinuxUser erscheint monatlich und kostet 5,95 Euro (mit DVD 8,50 Euro). Weitere Infos zum Heft finden Sie auf der Homepage.

Das Jahresabo kostet ab 86,70 Euro. Details dazu finden Sie im Computec-Shop. Im Probeabo erhalten Sie zudem drei Ausgaben zum reduzierten Preis.

Bei Google Play finden Sie digitale Ausgaben für Tablet & Smartphone.

HINWEIS ZU PAYPAL: Die Zahlung ist ohne eigenes Paypal-Konto ganz einfach per Kreditkarte oder Lastschrift möglich!

Stellenmarkt

Aktuelle Fragen

Lieber Linux oder Windows- Betriebssystem?
Sina Kaul, 13.10.2017 16:17, 2 Antworten
Hallo, bis jetzt hatte ich immer nur mit
IT-Kurse
Alice Trader, 26.09.2017 11:35, 2 Antworten
Hallo liebe Community, ich brauche Hilfe und bin sehr verzweifelt. Ih bin noch sehr neu in eure...
Backup mit KUP unter Suse 42.3
Horst Schwarz, 24.09.2017 13:16, 3 Antworten
Ich möchte auch wieder unter Suse 42.3 mit Kup meine Backup durchführen. Eine Installationsmöglic...
kein foto, etc. upload möglich, wo liegt mein fehler?
kerstin brums, 17.09.2017 22:08, 5 Antworten
moin, zum erstellen einer einfachen wordpress website kann ich keine fotos uploaden. vom rechne...
Arch Linux Netzwerkkonfigurationen
Franziska Schley, 15.09.2017 18:04, 0 Antworten
Moin liebe Linux community, ich habe momentan Probleme mit der Einstellung des Lan/Wlan in Arc...