---
title: Vollständiges Handbuch zur Verwendung von AsciiDoc unter Linux - WebSetNet
updated: 2020-04-13 18:11:27Z
created: 2020-04-13 17:54:20Z
tags:
  - IT
  - Development/Asciidoctor
source: https://websetnet.net/de/complete-guide-using-asciidoc-linux/
---

[Complete Guide](https://websetnet.net/de/complete-guide-using-asciidoc-linux/)

_**Kurz: Dieses detaillierte Handbuch beschreibt die Vorteile von AsciiDoc und zeigt Ihnen, wie Sie AsciiDoc in Linux installieren und verwenden.**_

Im Laufe der Jahre habe ich viele verschiedene Tools verwendet, um Artikel, Berichte oder Dokumentationen zu schreiben. Ich denke, alles begann für mich mit Luc Barthelets Epistole auf Apple IIc vom französischen Editor Version Soft. Dann wechselte ich zu GUI-Tools mit dem hervorragenden Microsoft Word 5 für Apple Macintosh, dann zu dem weniger überzeugenden (für mich) StarOffice unter Sparc Solaris, das bereits als OpenOffice bekannt war, als ich definitiv zu Linux wechselte. Alle diese Werkzeuge waren _wirklich_ [Textverarbeitungen](https://www.computerhope.com/jargon/w/wordssor.htm).

Aber ich wurde nie wirklich davon überzeugt [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) Redakteure. Also habe ich viele verschiedene mehr oder weniger menschenlesbare Textformate untersucht: [troff](https://en.wikipedia.org/wiki/Troff), [HTML](https://en.wikipedia.org/wiki/HTML), [RTF](https://en.wikipedia.org/wiki/Rich_Text_Format), [TeX](https://en.wikipedia.org/wiki/TeX)/[Latex](https://en.wikipedia.org/wiki/LaTeX), [XML](https://en.wikipedia.org/wiki/XML) und schlussendlich [AsciiDoc](https://en.wikipedia.org/wiki/AsciiDoc) Welches ist das Werkzeug, das ich heute am meisten verwende? Tatsächlich benutze ich es gerade, um diesen Artikel zu schreiben!

Wenn ich diese Geschichte geschrieben habe, war es, weil die Schleife irgendwie geschlossen ist. Epistole war ein Textverarbeitungsprogramm der Textkonsolen-Ära. Soweit ich mich erinnere, gab es Menüs, und Sie können mit der Maus Text auswählen. Der größte Teil der Formatierung erfolgte jedoch durch Hinzufügen nicht aufdringlicher Tags zum Text. Genau wie bei AsciiDoc. Natürlich war es nicht die erste Software, die das tat. Aber es war das erste, das ich benutzt habe!

![Steuern der Textausrichtung in Luc Barthelets Epistole (1985-Apple II) mithilfe von Befehlen, die in den Text eingebettet sind](https://itsfoss.com/wp-content/uploads/2017/09//epistole-manual-command-example-version-soft-luc-barthelet-1985.png)

## Warum AsciiDoc (oder ein anderes Textdateiformat)?

Ich sehe zwei Vorteile in der Verwendung von Textformaten für das Schreiben: Erstens gibt es eine klare Trennung zwischen dem Inhalt und der Präsentation. Dieses Argument ist offen für Diskussionen, da einige Textformate wie TeX oder HTML eine gute Disziplin erfordern, um diese Trennung einzuhalten. Und auf der anderen Seite können Sie mit der Verwendung eines gewissen Grades der Trennung erreichen [Vorlagen und Stylesheets](https://wiki.openoffice.org/wiki/Documentation/OOo3_User_Guides/Getting_Started/Templates_and_Styles) mit WYSIWYG-Editoren. Ich stimme dem zu. Trotzdem finde ich Präsentationsprobleme mit GUI-Tools aufdringlich. Wenn Sie Textformate verwenden, können Sie sich nur auf den Inhalt konzentrieren, ohne dass Sie beim Schreiben durch einen Schriftstil oder eine Witwenlinie gestört werden. Aber vielleicht bin es nur ich? Ich kann jedoch nicht zählen, wie oft ich mit dem Schreiben aufgehört habe, nur um ein kleines Stylingproblem zu beheben - und meine Inspiration verloren zu haben, als ich zum Text zurückkam. Wenn Sie nicht einverstanden sind oder eine andere Erfahrung haben, zögern Sie nicht, mir im Kommentarbereich unten zu widersprechen!

Jedenfalls wird mein zweites Argument weniger der persönlichen Interpretation unterliegen: Dokumente, die auf Textformaten basieren, sind hoch _interoperabel_. Nicht nur Sie können sie mit jedem Texteditor auf jeder Plattform bearbeiten, aber Sie können Textrevisionen mit einem Tool wie [git](https://en.wikipedia.org/wiki/Git) or [SVN](https://en.wikipedia.org/wiki/Apache_Subversion)oder automatisieren Sie Textänderung unter Verwendung der allgemeinen Werkzeuge wie [Durst](https://en.wikipedia.org/wiki/Sed), [AWK](https://en.wikipedia.org/wiki/AWK), [Perl](https://en.wikipedia.org/wiki/Perl) und so weiter. Um Ihnen ein konkretes Beispiel zu geben: Wenn Sie ein textbasiertes Format wie AsciiDoc verwenden, benötige ich nur einen Befehl, um ein hochgradig personalisiertes Mailing aus einem Masterdokument zu erstellen, während für denselben Job mit einem WYSIWYG-Editor eine geschickte Verwendung von „Feldern“ erforderlich gewesen wäre. und durch mehrere Assistentenbildschirme gehen.

## Was ist AsciiDoc?

Streng genommen ist AsciiDoc ein Dateiformat. Es definiert syntaktische Konstrukte, die einem Prozessor helfen, die Semantik der verschiedenen Teile Ihres Textes zu verstehen. Normalerweise, um eine schön formatierte Ausgabe zu erzeugen.

Auch wenn diese Definition abstrakt erscheinen mag, ist dies etwas Einfaches: Einige Schlüsselwörter oder Zeichen in Ihrem Dokument haben eine besondere Bedeutung, die das Rendering des Dokuments verändern. Dies ist das exakt gleiche Konzept wie die Tags in HTML. Ein Hauptunterschied zu AsciiDoc besteht jedoch darin, dass die Eigenschaft des Quelldokuments erhalten bleibt _leicht_ für Menschen lesbar.

Kariert [unser GitHub-Repository](https://github.com/itsfoss/asciidoc-intro/tree/master/coffee) Um zu vergleichen, wie die gleiche Ausgabe mit wenigen gemeinsamen Textdateien Format erzeugt werden kann: (Kaffee Manpage Idee mit freundlicher Genehmigung von [http://www.linuxjournal.com/article/1158](https://href.li/?http://www.linuxjournal.com/article/1158))

*   `coffee.man` benutzt das ehrwürdige _troff_ Prozessor (basierend auf dem 1964 [ABFLIESSEN](https://en.wikipedia.org/wiki/TYPSET_and_RUNOFF) Programm). Es wird heute meistens zum Schreiben verwendet [Manpages](https://en.wikipedia.org/wiki/Man_page). Sie können es versuchen, nachdem Sie das heruntergeladen haben `Kaffee.*` Dateien durch Eingabe `Mann ./coffee.man` an Ihrer Eingabeaufforderung.
*   `Kaffee.tex` verwendet das _Latex_ Syntax (1985), um meist das gleiche Ergebnis zu erzielen, jedoch für eine PDF-Ausgabe. LaTeX ist ein Satzprogramm, das besonders für wissenschaftliche Publikationen geeignet ist, da es mathematische Formeln und Tabellen gut formatieren kann. Sie können das PDF mit der LaTeX-Quelle erstellen `pdflatex kaffee.tex`
*   `Kaffee.html` verwendet das HTML-Format (1991), um die Seite zu beschreiben. Sie können diese Datei direkt mit Ihrem bevorzugten Webbrowser öffnen, um das Ergebnis zu sehen.
*   `Kaffee.adoc`, schließlich, verwendet die AsciiDoc-Syntax (2002). Sie können sowohl HTML als auch PDF aus dieser Datei erzeugen:

```shell
asciidoc coffee.adoc # HTML-Ausgabe a2x --format pdf ./coffee.adoc # PDF-Ausgabe (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF-Ausgabe (Apache FOP)
```

Nachdem Sie das Ergebnis gesehen haben, öffnen Sie diese vier Dateien mit Ihrem Favoriten [Texteditor](https://en.wikipedia.org/wiki/Text_editor) (nano, vim, SublimeText, gedit, Atom,…) und vergleichen Sie die Quellen: Es besteht eine große Wahrscheinlichkeit, dass Sie der Meinung sind, dass die AsciiDoc-Quellen leichter zu lesen sind - und wahrscheinlich auch zu schreiben sind.

## Wie installiere ich AsciiDoc unter Linux?

AsciiDoc ist aufgrund der vielen Abhängigkeiten relativ komplex zu installieren. Ich meine komplex, wenn Sie es aus Quellen installieren möchten. Für die meisten von uns ist die Verwendung unseres Paketmanagers wahrscheinlich der beste Weg:

```shell
apt-get installieren asciidoc fop
```

oder der folgende Befehl:

```shell
yum installieren acsiidoc fop
```

(FOP wird nur benötigt, wenn Sie die [Apache FOP](https://en.wikipedia.org/wiki/Formatting_Objects_Processor) Backend für die PDF-Generierung - dies ist das PDF-Backend, das ich selbst verwende)

Weitere Details zur Installation finden Sie unter [die offizielle AsciiDoc Webseite](https://href.li/?http://www.methods.co.nz/asciidoc/INSTALL.html). Im Moment brauchen Sie nur ein wenig Geduld, da die Installation von AsciiDoc zumindest auf meinem minimalen Debian-System erfordert, dass 360MB heruntergeladen wird (hauptsächlich wegen der LaTeX-Abhängigkeit). Welche, abhängig von Ihrer Internet-Bandbreite, Ihnen viel Zeit geben kann, um den Rest dieses Artikels zu lesen.

## AsciiDoc Tutorial: Wie schreibe ich in AsciiDoc?

Ich sagte es mehrmals, AsciiDoc ist ein Menschenlesbares _Textdateiformat_. So können Sie Ihre Dokumente mit dem Texteditor Ihrer Wahl schreiben. Es gibt sogar spezielle Texteditoren. Aber ich werde hier nicht darüber sprechen - einfach weil ich sie nicht benutze. Wenn Sie jedoch eine davon verwenden, zögern Sie nicht, Ihr Feedback über den Kommentarbereich am Ende dieses Artikels zu teilen.

Ich habe nicht vor, hier ein weiteres AsciiDoc-Syntax-Tutorial zu erstellen: Es gibt bereits viele davon im Web. Daher werde ich nur die sehr grundlegenden syntaktischen Konstrukte erwähnen, die Sie in praktisch jedem Dokument verwenden werden. Aus dem oben zitierten einfachen Beispiel für den Befehl „Kaffee“ können Sie Folgendes ersehen:

*   **Titel** in AsciiDoc werden identifiziert, indem man sie mit zugrunde legt `===` or ```---``` (abhängig von der Titelebene),
*   **fett** Zeichenspannen werden zwischen Starts geschrieben,
*   und weiterführende **Kursivschrift** zwischen Unterstrichen.

Das sind ziemlich häufige Konventionen, die wahrscheinlich auf die Zeit vor der HTML-E-Mail zurückgehen. Außerdem benötigen Sie möglicherweise zwei andere häufige Konstrukte, die in meinem vorherigen Beispiel nicht dargestellt sind: **Hyperlinks** und weiterführende **Bilder** Einschluss, dessen Syntax ziemlich selbsterklärend ist.

```
// Link Hypertext Links: https: //itsfoss.com [ItsFoss Linux Blog] // Inline Bilder image: https: //itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png [ ItsFOSS Text Logo] // Bilder blockieren image :: https: //itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png [ItsFOSS Text Logo]
```

Aber die AsciiDoc-Syntax ist viel reicher. Wenn Sie mehr wollen, kann ich Sie auf diesen netten AsciiDoc Cheatsheet hinweisen: [http://powerman.name/doc/asciidoc](https://href.li/?http://powerman.name/doc/asciidoc)

## Wie rendert man die endgültige Ausgabe?

Ich gehe davon aus, dass Sie bereits einen Text nach dem AsciiDoc-Format geschrieben haben. Wenn dies nicht der Fall ist, können Sie herunterladen [Tauchen Sie hier in die Geschichten unserer zufriedenen Kunden ein](https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master) einige Beispieldateien, die direkt aus der AsciiDoc-Dokumentation kopiert wurden:

```
# Laden Sie das AsciiDoc-Benutzerhandbuch als Quelldokument herunter BASE = 'https: //raw.githubusercontent.com/itsfoss/asciidoc-intro/master' wget "$ {BASE}" / {asciidoc.txt, customers.csv}
```

Seit AsciiDoc ist _für Menschen lesbar_Sie können den AsciiDoc-Quelltext direkt per E-Mail an jemanden senden, und der Empfänger kann diese Nachricht ohne weiteres lesen. Möglicherweise möchten Sie jedoch eine besser formatierte Ausgabe bereitstellen. Zum Beispiel als HTML für die Webpublikation (genau wie ich es für diesen Artikel getan habe). Oder als PDF zum Drucken oder Anzeigen.

In allen Fällen benötigen Sie eine _Prozessor_. In der Tat benötigen Sie unter der Haube mehrere Prozessoren. Weil Ihr AsciiDoc-Dokument in verschiedene Zwischenformate umgewandelt wird, bevor die endgültige Ausgabe erstellt wird. Da mehrere Werkzeuge verwendet werden, sprechen wir manchmal von einem Ausgang, von dem eines der Eingang des nächsten ist _Werkzeugkette_.

Selbst wenn ich hier einige innere Arbeitsdetails erkläre, müssen Sie verstehen, dass das meiste davon vor Ihnen verborgen bleibt. Es sei denn, Sie müssen die Tools zunächst installieren - oder Sie möchten einige Schritte des Prozesses optimieren.

### In der Praxis?

Für die HTML-Ausgabe benötigen Sie nur die `Asciidoc` Werkzeug. Für kompliziertere Toolchains empfehle ich dir, die `a2x` Tool (Teil der AsciiDoc-Distribution), das die erforderlichen Prozessoren in der folgenden Reihenfolge auslöst:

```
# Alle Beispiele basieren auf dem AsciiDoc Benutzerhandbuch Quelldokument # HTML Ausgabe asciidoc asciidoc.txt firefox asciidoc.html # XHTML Ausgabe a2x --format = xhtml asciidoc.txt # PDF Ausgabe (LaTeX Prozessor) a2x --format = pdf asciidoc. txt # PDF-Ausgabe (FOP-Prozessor) a2x --fop --format = pdf asciidoc.txt
```

Auch wenn es direkt eine HTML-Ausgabe erzeugen kann, ist die Kernfunktionalität des `Asciidoc` Werkzeug bleibt übrig, um das AsciiDoc-Dokument in das Zwischenprodukt zu transformieren [DocBook](https://en.wikipedia.org/wiki/DocBook) Format. DocBook ist ein XML-basiertes Format, das häufig für die Veröffentlichung von technischen Dokumentationen verwendet wird (aber nicht darauf beschränkt ist). DocBook ist ein semantisches Format. Das heißt, es beschreibt Ihren Dokumentinhalt. Aber _nicht_ seine Präsentation. Die Formatierung wird also der nächste Schritt der Transformation sein. Unabhängig davon, welches Ausgabeformat verwendet wird, wird das DocBook-Zwischendokument über ein [XSLT](https://en.wikipedia.org/wiki/XSLT) Prozessor, um entweder direkt die Ausgabe (z. B. XHTML) oder ein anderes Zwischenformat zu erzeugen.

Dies ist der Fall, wenn Sie ein PDF-Dokument erzeugen, bei dem das DocBook-Dokument (nach Ihrem Wunsch) entweder als LaTeX-Zwischendarstellung oder als umgewandelt wird [XSL-FO](https://en.wikipedia.org/wiki/XSL_Formatting_Objects) (eine XML-basierte Sprache für die Seitenbeschreibung). Schließlich wird ein dediziertes Tool diese Darstellung in PDF konvertieren.

Die zusätzlichen Schritte für PDF-Generationen sind insbesondere dadurch gerechtfertigt, dass die Toolchain die Paginierung für die PDF-Ausgabe verarbeiten muss. Dies ist für ein Stream-Format wie HTML nicht erforderlich.

### dblatex oder fop?

Da es zwei PDF-Backends gibt, ist die übliche Frage _"Welches ist das Beste?"_ Etwas, das ich nicht für dich beantworten kann.

Beide Prozessoren haben [Vor-und Nachteile](https://href.li/?http://www.methods.co.nz/asciidoc/userguide.html#_pdf_generation). Und letztendlich wird die Wahl ein Kompromiss zwischen Ihren Bedürfnissen und Ihrem Geschmack sein. Ich ermutige Sie daher, sich die Zeit zu nehmen, beide zu testen, bevor Sie das Backend auswählen, das Sie verwenden werden. Wenn Sie dem LaTeX-Pfad folgen, [dblatex](https://href.li/?http://dblatex.sourceforge.net/) wird das Backend sein, das verwendet wird, um das PDF zu erzeugen. Während es sein wird [Apache FOP](https://xmlgraphics.apache.org/fop/) Wenn Sie das XSL-FO-Zwischenformat bevorzugen. Vergessen Sie also nicht, die Dokumentation dieser Tools zu lesen, um zu sehen, wie einfach es sein wird, die Ausgabe an Ihre Bedürfnisse anzupassen. Es sei denn natürlich, Sie sind mit der Standardausgabe zufrieden!

## Wie kann ich die Ausgabe von AsciiDoc anpassen?

### AsciiDoc zu HTML

Out-of-the-Box, AsciiDoc produziert ziemlich schöne Dokumente. Aber früher oder später wirst du ihr Aussehen anpassen.

Die genauen Änderungen hängen vom verwendeten Backend ab. Für die HTML-Ausgabe können die meisten Änderungen durch Ändern der [CSS](https://en.wikipedia.org/wiki/Cascading_Style_Sheets) Stylesheet, das dem Dokument zugeordnet ist.

Angenommen, ich möchte alle Abschnittsüberschriften in Rot anzeigen. Ich könnte Folgendes erstellen `custom.css` Datei:

```
h2 {Farbe: rot; }
```

Und bearbeiten Sie das Dokument mit dem leicht modifizierten Befehl:

```
# Setzen Sie das Attribut 'stylesheet' auf # den absoluten Pfad zu unserer benutzerdefinierten CSS-Datei asciidoc -a stylesheet = $ PWD / custom.css asciidoc.txt
```

Sie können Änderungen auch auf einer feineren Ebene vornehmen, indem Sie a hinzufügen _Rolle_ Attribut zu einem Element. Dies wird übersetzt in ein _Klasse_ Attribut im generierten HTML.

Versuchen Sie beispielsweise, unser Testdokument so zu ändern, dass das Rollenattribut dem ersten Absatz des Textes hinzugefügt wird:

```
[role = "Zusammenfassung"] AsciiDoc ist ein Textdokumentformat ....
```

Fügen Sie dann der folgenden Regel die folgende hinzu `custom.css` Datei:

```
.summary {font-style: kursiv; }
```

Erneutes Generieren des Dokuments:

```
asciidoc -a stylesheet = $ PWD / custom.css asciidoc.txt
```

[![](data:image/gif,GIF89a%01%00%01%00%80%00%00%00%00%00%FF%FF%FF%21%F9%04%01%00%00%00%00%2C%00%00%00%00%01%00%01%00%00%02%01D%00%3B)](https://websetnet.b-cdn.net/wp-content/uploads/2018/10/unnamed-file-252.png)

1.  et voila: Der erste Absatz wird jetzt kursiv angezeigt. Mit ein bisschen Kreativität, etwas Geduld und ein paar CSS-Tutorials, sollten Sie in der Lage sein, Ihr Dokument nach Ihrem Willen anzupassen.

### AsciiDoc zu PDF

Das Anpassen der PDF-Ausgabe ist etwas komplexer. Nicht aus Sicht des Autors, da der Quelltext identisch bleibt. Verwenden Sie schließlich dasselbe Rollenattribut wie oben, um die Teile zu identifizieren, die einer speziellen Behandlung bedürfen.

Sie können CSS jedoch nicht mehr verwenden, um die Formatierung für die PDF-Ausgabe zu definieren. Für die gebräuchlichsten Einstellungen gibt es Parameter, die Sie über die Befehlszeile einstellen können. Einige Parameter können sowohl mit der _dblatex_ und die _Geck_ Backends, andere sind spezifisch für jedes Backend.

Eine Liste der unterstützten dblatex-Parameter finden Sie unter [http://dblatex.sourceforge.net/doc/manual/sec-params.html](https://href.li/?http://dblatex.sourceforge.net/doc/manual/sec-params.html)

Eine Liste der DocBook XSL-Parameter finden Sie unter [http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html](https://href.li/?http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html)

Da die Margin-Anpassung eine ziemlich häufige Anforderung ist, sollten Sie sich das auch ansehen: [http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html](https://href.li/?http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html)

Wenn die Parameternamen zwischen den beiden Backends etwas konsistent sind, unterscheiden sich die Befehlszeilenargumente, die verwendet werden, um diese Werte an die Backends zu übergeben _dblatex_ und weiterführende _Geck_. Überprüfen Sie also zuerst Ihre Syntax, wenn dies anscheinend nicht funktioniert. Aber um ehrlich zu sein, konnte ich beim Schreiben dieses Artikels das nicht schaffen `body.font.family` Parameter arbeiten mit dem _dblatex_ Backend. Da benutze ich normalerweise _Geck_Vielleicht habe ich etwas verpasst? Wenn Sie mehr Hinweise dazu haben, werde ich mehr als glücklich sein, Ihre Vorschläge im Kommentarbereich am Ende dieses Artikels zu lesen!

Erwähnenswert ist die Verwendung von nicht standardmäßigen Schriftarten - auch mit _Geck_–Erfordern Sie zusätzliche Arbeit. Aber es ist ziemlich gut auf der Apache-Website dokumentiert: [https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk](https://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk)

```
# XSL-FO / FOP a2x -v --format pdf --fop --xsltproc-opts = '- stringparam page.margin.inner 10cm' --xsltproc-opts = '- stringparam body.font.family Helvetica' --xsltproc-opts = '- stringparam body.font.size 8pt' asciidoc.txt # dblatex # (body.font.family _should_ funktioniert, aber anscheinend nicht?!?) a2x -v --format pdf --dblatex-opts = '- Parameter page.margin.inner = 10cm' --dblatex-opts = '- stringparam body.font.family Helvetica' asciidoc.txt
```

### Feinkörnige Einstellung für die PDF-Erzeugung

Globale Parameter sind nett, wenn Sie nur einige vordefinierte Einstellungen anpassen müssen. Wenn Sie jedoch das Dokument fein abstimmen oder das Layout komplett ändern möchten, benötigen Sie zusätzliche Anstrengungen.

Im Kern der DocBook-Verarbeitung gibt es [XSLT](https://en.wikipedia.org/wiki/XSLT). XSLT ist eine Computersprache, ausgedrückt in XML-Notation, die es ermöglicht, eine beliebige Transformation von einem XML-Dokument in… etwas anderes zu schreiben. XML oder nicht.

Zum Beispiel müssen Sie das erweitern oder ändern [DocBook XSL Stylesheet](https://href.li/?http://www.sagehill.net/docbookxsl/) um den XSL-FO-Code für die neuen Stile zu erstellen, die Sie möchten. Und wenn du das benutzt _dblatex_ Im Backend muss dazu eventuell das entsprechende DocBook-to-LaTeX XSLT Stylesheet modifiziert werden. In diesem Fall müssen Sie möglicherweise auch ein benutzerdefiniertes LaTeX-Paket verwenden. Aber darauf werde ich mich nicht konzentrieren _dblatex_ ist nicht das Backend, das ich selbst benutze. Ich kann dich nur auf das hinweisen [offizielle Dokumentation](https://href.li/?http://dblatex.sourceforge.net/doc/manual/sec-custom.html) wenn du mehr wissen willst. Aber noch einmal, wenn Sie damit vertraut sind, teilen Sie bitte Ihre Tipps und Tricks im Kommentarbereich!

Auch wenn nur auf konzentriert _Geck_Ich habe hier nicht wirklich den Raum, um den gesamten Vorgang zu beschreiben. Daher zeige ich Ihnen nur die Änderungen, mit denen Sie ein ähnliches Ergebnis erzielen können wie mit wenigen CSS-Zeilen in der obigen HTML-Ausgabe. Das heißt: Abschnittsüberschriften in rot und a _Zusammenfassung_ Absatz in Kursivschrift.

Der Trick, den ich hier verwende, besteht darin, ein neues XSLT-Stylesheet zu erstellen, das das ursprüngliche DocBook-Stylesheet importiert, aber die Attributsätze oder Vorlagen für die Elemente, die wir ändern wollen, überschreibt:

```
<? xml version = '1.0'?> <xsl: stylesheet xmlns: xsl = "http://www.w3.org/1999/XSL/Transform" xmlns: exsl = "http://exslt.org/common" exclude-result-prefixes = "exsl" xmlns: fo = "http://www.w3.org/1999/XSL/Format" version = '1.0'> <! - Importieren Sie das standardmäßige DocBook Stylesheet für XSL-FO - -> <xsl: import href = "/ etc / asciidoc / docbook-xsl / fo.xsl" /> <! - DocBook XSL definiert viele Attributgruppen, mit denen Sie die Ausgabeelemente steuern können -> <xsl: attribute- set name = "section.title.level1.properties"> <xsl: attribute name = "farbe"> # FF0000 </ xsl: attribute> </ xsl: attribute-set> <! - Für feinkörnige Änderungen muss XSLT-Templates schreiben oder überschreiben, wie ich es unten für 'Zusammenfassung' simpara (Absätze) getan habe -> <xsl: template match = "simpara [@ role = 'summary']"> <! - Capture geerbtes Ergebnis -> <xsl: variable name = "basesult"> <xsl: apply-imports /> </ xsl: variable> <! - Passen Sie das Ergebnis an -> <xsl: for-each select = "exsl: node- set ($ basesult) / node () "> <xsl: kopieren> <xsl: copy-of select =" @ * "/> <xsl: a attribute name = "font-style"> kursiv </ xsl: attribut> <xsl: copy-of select = "knoten ()" /> </ xsl: copy> </ xsl: for-each> </ xsl: template > </ xsl: stylesheet>
```

Dann müssen Sie anfordern `a2x` Verwenden Sie das benutzerdefinierte XSL-Stylesheet, um die Ausgabe zu erstellen, anstatt die Standardausgabe mithilfe der `--xsl-Datei` Option:

```
a2x -v --format pdf --fop --xsl-datei =. / custom.xsl asciidoc.txt
```

[![](data:image/gif,GIF89a%01%00%01%00%80%00%00%00%00%00%FF%FF%FF%21%F9%04%01%00%00%00%00%2C%00%00%00%00%01%00%01%00%00%02%01D%00%3B)](https://websetnet.b-cdn.net/wp-content/uploads/2018/10/unnamed-file-253.png)

Mit ein wenig Vertrautheit mit XSLT, den hier gegebenen Hinweisen und einigen Fragen zu Ihrer bevorzugten Suchmaschine sollten Sie in der Lage sein, mit der Anpassung der XSL-FO-Ausgabe zu beginnen.

Aber ich werde nicht lügen, einige scheinbar einfache Änderungen in der Dokumentenausgabe erfordern möglicherweise, dass Sie einige Zeit damit verbringen, die DocBook XML- und XSL-FO-Handbücher zu durchsuchen, die Stylesheet-Quellen zu untersuchen und einige Tests durchzuführen, bevor Sie schließlich das erreichen, was Sie wollen .

## Meine Meinung

Das Schreiben von Dokumenten mit einem Textformat hat enorme Vorteile. Und wenn Sie in HTML veröffentlichen müssen, gibt es nicht viel Grund dafür _nicht_ mit AsciiDoc. Die Syntax ist sauber und ordentlich, die Verarbeitung ist einfach und das Ändern der Präsentation bei Bedarf erfordert meist einfach zu erlernende CSS-Kenntnisse.

Und selbst wenn Sie die HTML-Ausgabe nicht direkt verwenden, kann HTML heute mit vielen WYSIWYG-Anwendungen als Austauschformat verwendet werden. Als Beispiel habe ich dies hier getan: Ich habe die HTML-Ausgabe dieses Artikels in den WordPress-Editionsbereich kopiert und so die gesamte Formatierung beibehalten, ohne etwas direkt in WordPress eingeben zu müssen.

Wenn Sie als PDF veröffentlichen müssen, bleiben die Vorteile für den Verfasser gleich. Die Dinge werden sicherlich schwieriger, wenn Sie das Standardlayout in der Tiefe ändern müssen. In einem Unternehmensumfeld bedeutet dies wahrscheinlich, dass Sie ein mit XSLT qualifiziertes Dokument einstellen, um die Stylesheets zu erstellen, die Ihrem Branding oder Ihren technischen Anforderungen entsprechen - oder dass jemand im Team diese Fähigkeiten erwerben kann. Sobald dies erledigt ist, wird es eine Freude sein, Text mit AsciiDoc zu schreiben. Und sehen, wie diese Schriften automatisch in schöne HTML-Seiten oder PDF-Dokumente konvertiert werden!

Wenn Sie schließlich AsciiDoc entweder zu einfach oder zu komplex finden, können Sie sich einige andere Dateiformate mit ähnlichen Zielen ansehen: [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet), [Textil-](https://txstyle.org/), [reStructuredText](https://href.li/?http://docutils.sourceforge.net/docs/user/rst/quickstart.html) or [AsciiDoctor](https://href.li/?http://asciidoctor.org/) um nur einige zu nennen. Auch wenn es auf Konzepten basiert, die bis in die frühen Tage der Computerverarbeitung zurückreichen, ist das von Menschen lesbare Textformat-Ökosystem ziemlich reichhaltig. Wahrscheinlich reicher war es nur 20 Jahren. Als Beweis, viele moderne [statische Website-Generatoren](https://www.smashingmagazine.com/2015/11/modern-static-website-generators-next-big-thing/) basieren auf ihnen. Leider ist dies für diesen Artikel nicht möglich. Also lassen Sie es uns wissen, wenn Sie mehr darüber erfahren möchten!

[Frequenz](https://itsfoss.com/asciidoc-guide/)