AsciiDoc im Vergleich
AsciiDoc ist für technische Redakteure das Mittel der Wahl. Hier sind die Vorteile gegenüber Markdown, LaTeX und reStructuredText.
Die Wahl der richtigen Auszeichnungssprache ist entscheidend für technische Schreiber. In diesem Artikel werfen wir einen Blick auf AsciiDoc und vergleichen es mit anderen populären Sprachen. AsciiDoc ist eine leicht zu lesende Auszeichnungssprache. AsciiDoc-Dateien können abhängig vom Konverter in viele Formate, einschließlich HTML, PDF, ePub und Manpage, konvertiert werden.
Wir vergleichen AsciiDoc mit den Auszeichnungssprachen Markdown, LaTeX und reStructuredText. Jede Sprache hat ihre Vor- und Nachteile. Daher spielt der Einsatzzweck stets eine große Rolle bei der Auswahl der richtigen Sprache. Wir stellen uns daher die Frage: Wie sehr eignen sie sich jeweils für technische Redakteure?
Inhaltsverzeichnis
AsciiDoc vs. Markdown
AsciiDoc vs. LaTex
AsciiDoc vs. restructured Text
Was ist Markdown?
Markdown ist eine leichte Auszeichnungssprache, mit einer einfachen Syntax. Die Sprache wurde insbesondere von Blogs, Foren, sowie Kurznachrichtendiensten übernommen und ist daher insbesondere bei Autoren sehr beliebt. Dank ihrer einfachen Syntax ist der Einsteig leicht zu stemmen, wodurch sie zur bekanntesten Auszeichnungssprache wurde. Laut John Gruber, der zusammen mit Aaron Schwartz Markdown entwickelt hat, ist die Sprache ein Text-zu-HTML Konverter. Die Entwickler verfolgten das Design-Ziel, dass Markdown Texte selbst im Quelltext leserlich und publizierbar sind. Das liegt daran, dass sie nur wenige Tags oder sonstige Formatierungs-Anweisungen enthalten.
Wann ist AsciiDoc besser?
Obwohl Markdown ein breites Publikum anspricht, hat es nicht den notwendigen Umfang, um für technische Dokumentationen eingesetzt zu werden. Hier sind die wichtigsten Vorteile von AsciiDoc gegenüber Markdown:
Alle Funktionen in einer Sprache
Markdown ist in viele Dialekte zersplittert, wie Markdown, Python-Markdown, Markdown XL, MultiMarkDown und mehr. Jeder dieser Dialekte fügt bestimmte Funktionen hinzu, die im Standard-Markdown fehlen. Beispiele sind Tabellen, Hinweise (Admonitions) oder Cross-Referenzen. Sobald Sie diese Elemente benötigen, müssen Sie HTML-Code einbetten oder Markdown-Dialekte benutzen. In AsciiDoc hingegen sind all diese Funktionen in einer Sprache enthalten, die sich auf dem Weg zur Standardisierung befindet. Die Funktionen sind nativ enthalten, Sie benötigen keine HTML Kenntnisse.
Vielseitige Ausgabeformate
Standardmäßig ist Markdown auf die Ausgabe von HTML beschränkt. AsciiDoc hingegen ermöglicht die Erzeugung verschiedener Ausgabeformate wie HTML, PDF, Manpage und DocBook. Über letzteres können Sie Dateien dann in viele weitere Formate wie ePub konvertieren. Dies bietet eine größere Flexibilität bei der Veröffentlichung Ihrer Inhalte.
Keine Programmierung für eigene Attribute notwendig
Attribute sind ein Begriff aus AsciiDoc. Sie werden verwendet, um Dokumente in Inhalt, Form oder Stil anzupassen. Sie benötigen in Markdown oft Programmierkenntnisse, um eigene Attribute zu implementieren, während diese Funktion in AsciiDoc standardmäßig enthalten ist. In AsciiDoc wählen Sie aus den mitgelieferten Attributen, oder definieren Eigene. Sie nutzen eigene Attribute, um beispielsweise Text-Variablen für wiederkehrende Inhalte zu setzen. Nehmen wir mal an, dass Sie die URL Ihrer Unternehmens-Website mehrfach nennen möchten. Hierfür erstellen wir ein eigenes Attribut namens :url:. Bevor Sie die URL im Dokument zu ersten Mal benennen, schreiben Sie in einer Zeile :url: www.xyz.com. Nun geben Sie das Attribut an beliebigen Stellen mit {url} wieder aus. Änderungen nehmen Sie in der Definition vor, alle weiteren Instanzen aktualisieren sich automatisch. Attribute lassen sich ebenfalls verschachteln.
Zusammengefasst: AsciiDoc ist für technische Redakteure die effizientere und flexiblere Wahl. Sie haben alle Funktionen in einer Sprache. Sobald Ihr Text fertig ist, publizieren Sie die Inhalte in mehrere Formaten - nicht nur in HTML.
Was ist LaTeX?
Leslie Lamport entwickelte das Textsatzsystem LaTeX, das auf Donald E. Knuths TeX-System basiert. LaTeX ist besonders bei Wissenschaftlern und Fachleuten im Bereich der akademischen Schriften sehr beliebt. Es handelt sich um ein Textsatzsystem, das auf einem typographischen Satzsystem aufbaut. Es wird häufig für wissenschaftliche und technische Dokumente sowie für Bücher, Artikel und Berichte verwendet. Im akademischen Bereich ist LaTeX aufgrund seiner Fähigkeit, komplexe mathematische Formeln und wissenschaftliche Notationen präzise darzustellen, besonders beliebt. Aufgrund der hohen Qualität der Typografie bevorzugen viele wissenschaftliche Zeitschriften und Universitäten LaTeX für die Veröffentlichung von Artikeln und für Abschlussarbeiten.
Sowohl LaTeX als auch AsciiDoc ermöglichen es dem Autor, sich auf den Inhalt zu konzentrieren, während das Design unabhängig über die Stile gehandhabt wird. Beide sind unabhängig von einem speziellen Editor, was bedeutet, dass Sie die Quellen in jedem Texteditor bearbeiten können. Darüber hinaus sind sie plattformübergreifend einsetzbar und liefern auf jedem Betriebssystem die gleiche Qualität in der Ausgabe. LaTeX hat einen größeren Funktionsumfang. Dennoch lassen sich mathematische Formeln, Fußnoten, und weitere Kernelemente ebenfalls in AsciiDoc abbilden.
Wann ist AsciiDoc besser?
AsciiDoc verwendet kürzere und prägnantere Markups im Vergleich zu LaTeX. Das Prinzip ist es, eine leserliche und einfache Syntax zu ermöglichen. Das erleichtert den Einstieg für neue Nutzer. Im Gegensatz dazu hat LaTeX durch die komplexere Syntax eine steilere Lernkurve.
Sollten Sie dennoch Funktionen aus LaTeX für Ihr AsciiDoc Dokument benötigen, ist dies kein Problem: Programme wie pandoc ermöglichen es Ihnen nach LaTeX zu konvertieren. Dies bietet Ihnen die Flexibilität, die Vorteile beider Sprachen zu nutzen, je nach den Anforderungen ihres Projekts.
Zusammengefasst: LaTeX brilliert bei spezialisierten, akademischen Arbeiten und Dokumenten mit komplexen mathematischen Formeln. AsciiDoc hingegen ist einfacher und intuitiver. Daraus ergeben sich Vorteile, die es für ein breiteres Spektrum von Projekten attraktiver machen. Die Wahl zwischen AsciiDoc und LaTeX hängt demnach von Ihren Anforderungen und persönlichen Präferenzen ab.
Was ist reStructuredText?
reStructuredText wird vorwiegend für Software-Dokumentationen verwendet wird. Sie kommt aus dem Ökosystem der Programmiersprache Python. In diesem Ökosystem wird sie vor allem in Kombination mit den Konvertern Docutils oder Sphinx verwendet. Ein zentrales Merkmal von reStructuredText ist seine Erweiterbarkeit: Mit Werkzeugen wie Sphinx können Nutzer eingebaute Erweiterungen aktivieren oder eigene Erweiterungen erstellen, um das Dokument in beinahe allen Bereichen anzupassen.
Wann ist AsciiDoc besser?
AsciiDoc bietet eine leichter verständliche Syntax im Vergleich zu reStructuredText. Demnach reduziert sich die Einarbeitungszeit für Neueinsteiger. Insbesondere die Einrückungen, sowie ungewöhnlichen Notationen und unterschiedlichen Syntaxformen erschwert es Neulingen, die Sprache leicht zu erlernen, da sie als besonders eigen und schwer zugänglich gilt.
AsciiDoc ist so gestaltet, dass es auch für technisch weniger versierte Nutzer zugänglich ist, was die Zusammenarbeit in Teams erleichtert. So müssen Sie beispielsweise Python installieren, um reStructuredText einzurichten. Während reStructuredText primär von und für die Python-Community erstellt wurde, genießt AsciiDoc eine breitere Unterstützung. Um die Auszeichnungssprache hat sich eine aktive Gemeinschaft gebildet, die ständig dazu beiträgt, die Sprache und die zugehörigen Werkzeuge zu verbessern.
Zusammengefasst: reStructuredText hat seine Stärken in der Python-Community und bei den Erweiterungsmöglichkeiten. AsciiDoc hingegen besticht durch eine einfache Syntax bei hohem Funktionsumfang. Damit ist die Sprache eine ausgezeichneten Wahl für eine breite Palette von Dokumentationsprojekten, unabhängig vom technischen Hintergrund der Nutzer.
Unser Fazit
Nachdem wir die verschiedenen Auszeichnungssprachen AsciiDoc, Markdown und reStructuredText miteinander verglichen haben, wird deutlich, dass jede Sprache ihre spezifischen Stärken und Einsatzgebiete hat. Die Wahl zwischen diesen Sprachen hängt nicht nur von den technischen Anforderungen eines Projekts ab, sondern auch von den persönlichen Vorlieben des Redakteurs oder Entwicklers:
Markdown ist eine ausgezeichnete Wahl für einfache Dokumente. Das vereinfacht die Kollaboration mit anderen Nutzern, da der Einstieg bei beiden Varianten am geringsten ist. LaTex wird vor allem in akademischen Kreisen eingesetzt. Insbesondere die Ausgabe mathematischer Formeln ist hier erwähnenswert. reStructuredText ist besonders in der Python-Community beliebt und überzeugt durch seine Erweiterungsmöglichkeiten.
AsciiDoc hingegen glänzt, sobald Dokumente umfangreicher werden und anspruchsvollere Formatierungen wie komplexe Tabellen, Fußnoten oder Cross-Referenzen erfordern. AsciiDoc ist auf dem Weg zur Standardisierung, wodurch alle Funktionen in einer Sprache enthalten sind. Dadurch haben Sie im Gegensatz zu Markdown keine Dialekte. Dennoch bleibt die Sprache leserlich und einfach zu lernen. Die höhere Benutzerfreundlichkeit zeichnet Sie gegenüber LaTeX und reStructuredText aus.
Übrigens: Wir haben in einem anderen Blogpost verglichen, wie viele Zeichen für einfache Elemente in AsciiDoc, Markdown und LaTeX benötigt werden.
AsciiDoc mit adoc Studio
Die Erstellung von AsciiDoc-Dateien im Terminal mag für einige ein Hindernis dargestellt haben, doch mit adoc Studio gehört dies der Vergangenheit an. Sie schreiben Ihren Text im Editor und sehen stets die aktuelle Vorschau als HTML und PDF. Es ist keine Konvertierung über das Terminal notwendig, um das Dokument im Ausgabeformat zu sehen. Vorbei ist die Zeit, in der technisch komplexe Installationen oder manuelle Updates im Terminal Sie von Ihrer Arbeit abgehalten haben. Und für alle, die gerne auf dem iPad arbeiten: adoc Studio läuft auf den aktuellen macOS- und iOS-Geräten, sodass Sie Ihre Arbeit überallhin mitnehmen können.
Es ist Zeit, die Vorteile von AsciiDoc voll auszuschöpfen. Probieren Sie adoc Studio aus und erleben Sie, wie unkompliziert und produktiv Ihre Dokumentationsarbeit sein kann.
