Komplette Anleitung zur Verwendung von AsciiDoc unter Linux

Kurz: In diesem ausführlichen Handbuch werden die Vorteile der Verwendung von AsciiDoc erläutert und die Installation und Verwendung von AsciiDoc unter Linux erläutert.

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 on Apple IIc von der französischen Editorversion Soft. Dann wechselte ich zu GUI-Tools mit dem hervorragenden Microsoft Word 5 für Apple Macintosh, dann zu dem für mich weniger überzeugenden StarOffice auf Sparc Solaris, das bereits als OpenOffice bekannt war, als ich definitiv auf Linux umstieg. Alle diese Werkzeuge waren wirklich Textverarbeitungsprogramme.

Aber die WYSIWYG-Redakteure haben mich nie wirklich überzeugt. Daher habe ich viele verschiedene mehr oder weniger für Menschen lesbare Textformate untersucht: troff, HTML, RTF, TeX / LaTeX, XML und schließlich AsciiDoc, das Tool, das ich heute am häufigsten verwende. Tatsächlich benutze ich es gerade, um diesen Artikel zu schreiben!

Wenn ich diese Geschichte geschrieben habe, dann, 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 den Text mit der Maus auswählen. Der größte Teil der Formatierung erfolgte jedoch durch Hinzufügen von nicht aufdringlichen Tags zum Text. So wie es mit AsciiDoc gemacht wird. Natürlich war es nicht die erste Software, die das tat. Aber es war das erste Mal, dass ich benutzt habe!

Warum AsciiDoc (oder ein anderes Textdateiformat)?

Ich sehe zwei Vorteile in der Verwendung von Textformaten zum Schreiben: Erstens gibt es eine klare Trennung zwischen Inhalt und Präsentation. Dieses Argument kann diskutiert werden, da einige Textformate wie TeX oder HTML eine gute Disziplin erfordern, um diese Trennung einzuhalten. Auf der anderen Seite können Sie durch die Verwendung von Vorlagen und Stylesheets mit WYSIWYG-Editoren ein gewisses Maß an Trennung erreichen. Ich stimme dem zu. Ich finde jedoch immer noch Probleme mit der Darstellung der GUI-Tools. Während Sie sich bei Verwendung von Textformaten nur auf den Inhalt konzentrieren können, ohne dass Sie durch einen Schriftstil oder eine Witwenlinie beim Schreiben gestört werden. Aber vielleicht bin es nur ich? Ich kann jedoch nicht zählen, wie oft ich mit dem Schreiben aufgehört habe, um ein kleines Styling-Problem zu beheben - und meine Inspiration verloren zu haben, als ich zum Text zurückkehrte. Wenn Sie anderer Meinung sind oder eine andere Erfahrung haben, zögern Sie nicht, mir im Kommentarbereich unten zu widersprechen!

Wie auch immer, mein zweites Argument wird weniger der persönlichen Interpretation unterliegen: Auf Textformaten basierende Dokumente sind in hohem Maße interoperabel . Sie können sie nicht nur mit einem beliebigen Texteditor auf einer beliebigen Plattform bearbeiten, sondern Sie können auch problemlos Textrevisionen mit einem Tool wie git oder SVN verwalten oder die Textänderung mithilfe gängiger Tools wie sed, AWK, Perl usw. automatisieren. Um Ihnen ein konkretes Beispiel zu geben: Wenn ich ein textbasiertes Format wie AsciiDoc verwende, benötige ich nur einen Befehl, um aus einem Masterdokument ein hochgradig personalisiertes Mailing zu erstellen, während derselbe Job mit einem WYSIWYG-Editor eine geschickte Verwendung von „Feldern“ erfordert hätte. und durch mehrere Assistentenbildschirme gehen.

Was ist AsciiDoc?

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

Auch wenn diese Definition abstrakt erscheinen könnte, ist dies etwas Einfaches: Einige Schlüsselwörter oder Zeichen in Ihrem Dokument haben eine spezielle Bedeutung, die das Rendering des Dokuments verändert. Dies ist genau das gleiche Konzept wie die Tags in HTML. Ein wesentlicher Unterschied zu AsciiDoc ist jedoch die Eigenschaft des Quelldokuments, dass es für den Menschen leicht lesbar bleibt.

Überprüfen Sie unser GitHub-Repository, um zu vergleichen, wie dieselbe Ausgabe mit wenigen gängigen Textdateien erzeugt werden kann: (Idee für die Kaffeehandbuchseite mit freundlicher Genehmigung von //www.linuxjournal.com/article/1158)

  • coffee.man verwendet den ehrwürdigen troff- Prozessor (basierend auf dem RUNOFF-Programm von 1964). Es wird heute hauptsächlich zum Schreiben von Manpages verwendet. Sie können es versuchen, nachdem Sie die coffee.* -Dateien heruntergeladen haben, indem man ./coffee.man an der Eingabeaufforderung man ./coffee.man eingeben.
  • coffee.tex verwendet die LaTeX- Syntax (1985), um zumeist das gleiche Ergebnis zu erzielen, jedoch für eine PDF-Ausgabe. LaTeX ist ein Satzprogramm, das sich besonders für wissenschaftliche Veröffentlichungen eignet, da es mathematische Formeln und Tabellen gut formatieren kann. Sie können das PDF aus der LaTeX-Quelle mit pdflatex coffee.tex
  • coffee.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.
  • coffee.adoc schließlich die AsciiDoc-Syntax (2002). Sie können aus dieser Datei sowohl HTML als auch PDF erstellen:
 asciidoc coffee.adoc # HTML output a2x --format pdf ./coffee.adoc # PDF output (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF output (Apache FOP) 

Jetzt haben Sie das Ergebnis gesehen, öffnen Sie diese vier Dateien mit Ihrem bevorzugten Texteditor (nano, vim, SublimeText, gedit, Atom, …) und vergleichen Sie die Quellen: Es besteht die große Wahrscheinlichkeit, dass Sie der Meinung sind, dass die AsciiDoc-Quellen einfacher zu lesen sind - und wahrscheinlich auch zu schreiben.

Wie installiere ich AsciiDoc unter Linux?

Die Installation von AsciiDoc ist aufgrund der vielen Abhängigkeiten relativ komplex. 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:

 apt-get install asciidoc fop 

oder den folgenden Befehl:

 yum install acsiidoc fop 

(fop wird nur benötigt, wenn Sie das Apache FOP-Backend für die PDF-Generierung benötigen - dies ist das von mir verwendete PDF-Backend.)

Weitere Details zur Installation finden Sie auf der offiziellen AsciiDoc-Website. Im Moment brauchen Sie nur ein wenig Geduld, da auf meinem minimalen Debian-System für die Installation von AsciiDoc 360 MB heruntergeladen werden müssen (hauptsächlich wegen der LaTeX-Abhängigkeit). Abhängig von Ihrer Internet-Bandbreite bleibt möglicherweise genügend Zeit, um den Rest dieses Artikels zu lesen.

AsciiDoc Tutorial: Wie schreibe ich in AsciiDoc?

Ich habe es mehrmals gesagt: AsciiDoc ist ein für Menschen lesbares 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 einen dieser Artikel verwenden, teilen Sie uns Ihr Feedback im Kommentarbereich am Ende dieses Artikels mit.

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

  • Titel in AsciiDoc werden identifiziert, indem sie mit === oder --- (je nach === werden.
  • Fettgedruckte Zeichenfelder werden zwischen den Starts geschrieben.
  • und Kursivschrift zwischen Unterstrichen.

Diese Konventionen sind weit verbreitet und stammen wahrscheinlich aus der Zeit vor HTML-E-Mails. Darüber hinaus benötigen Sie möglicherweise zwei weitere übliche Konstrukte, die in meinem vorherigen Beispiel nicht dargestellt wurden: Hyperlinks und die Einbeziehung von Bildern, deren Syntax ziemlich selbsterklärend ist.

 // HyperText links link://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog] // Inline Images image://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] // Block Images image:://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] 

Die AsciiDoc-Syntax ist jedoch viel umfangreicher. Wenn Sie mehr wollen, kann ich Sie auf dieses nette AsciiDoc-Spickzettel verweisen: //powerman.name/doc/asciidoc

Wie wird die endgültige Ausgabe gerendert?

Ich gehe davon aus, dass Sie hier bereits einen Text im AsciiDoc-Format geschrieben haben. Ist dies nicht der Fall, können Sie hier einige Beispieldateien herunterladen, die direkt aus der AsciiDoc-Dokumentation kopiert wurden:

 # Download the AsciiDoc User Guide source document BASE="//raw.githubusercontent.com/itsfoss/asciidoc-intro/master" wget "${BASE}"/{asciidoc.txt, customers.csv} 

Da AsciiDoc für Menschen lesbar ist, können Sie 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 (so wie ich es für diesen Artikel gemacht habe). Oder als PDF zum Ausdrucken oder Anzeigen.

In jedem Fall benötigen Sie einen Prozessor . Tatsächlich benötigen Sie unter der Haube mehrere Prozessoren. Denn Ihr AsciiDoc-Dokument wird vor der endgültigen Ausgabe in verschiedene Zwischenformate umgewandelt. Da mehrere Tools verwendet werden, wobei die Ausgabe eines Tools die Eingabe des nächsten ist, spricht man manchmal von einer Toolchain .

Auch wenn ich hier einige innere Details erläutere, müssen Sie verstehen, dass das meiste davon vor Ihnen verborgen bleibt. Es sei denn, Sie müssen die Tools zum ersten Mal installieren - oder Sie möchten einige Schritte des Prozesses optimieren.

In der Praxis?

Für die HTML-Ausgabe benötigen Sie nur das asciidoc Tool. Für kompliziertere Toolchains a2x ich Ihnen, das a2x Tool (Teil der AsciiDoc-Distribution) zu verwenden, das die erforderlichen Prozessoren auslöst, um:

 # All examples are based on the AsciiDoc User Guide source document # HTML output asciidoc asciidoc.txt firefox asciidoc.html # XHTML output a2x --format=xhtml asciidoc.txt # PDF output (LaTeX processor) a2x --format=pdf asciidoc.txt # PDF output (FOP processor) a2x --fop --format=pdf asciidoc.txt 

Auch wenn es direkt eine HTML-Ausgabe erzeugen kann, bleibt die Kernfunktionalität des asciidoc Tools bestehen, um das AsciiDoc-Dokument in das DocBook-Zwischenformat umzuwandeln. DocBook ist ein XML-basiertes Format, das häufig zum Veröffentlichen technischer 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 vom Ausgabeformat wird das DocBook-Zwischendokument durch einen XSLT-Prozessor verarbeitet, um entweder direkt die Ausgabe (z. B. XHTML) oder ein anderes Zwischenformat zu erzeugen.

Dies ist der Fall, wenn Sie ein PDF-Dokument generieren, bei dem das DocBook-Dokument (nach Belieben) entweder als LaTeX-Zwischendarstellung oder als XSL-FO (eine XML-basierte Sprache für die Seitenbeschreibung) konvertiert wird. Schließlich konvertiert ein spezielles Tool diese Darstellung in PDF.

Die zusätzlichen Schritte für PDF-Generierungen sind insbesondere durch die Tatsache gerechtfertigt, dass die Toolchain die Paginierung für die PDF-Ausgabe verarbeiten muss. Für ein Stream-Format wie HTML ist dies nicht erforderlich.

dblatex oder fop?

Da es zwei PDF-Backends gibt, lautet die übliche Frage „Welches ist das Beste?“. Darauf kann ich für Sie keine Antwort geben.

Beide Prozessoren haben Vor- und Nachteile. Und letztendlich wird die Wahl ein Kompromiss zwischen Ihren Bedürfnissen und Ihrem Geschmack sein. Ich empfehle Ihnen daher, sich die Zeit zu nehmen, um beide zu testen, bevor Sie das Backend auswählen, das Sie verwenden möchten. Wenn Sie dem LaTeX-Pfad folgen, wird dblatex als Backend für die PDF-Erstellung verwendet. Wobei es Apache FOP ist, wenn Sie das XSL-FO-Zwischenformat bevorzugen. Vergessen Sie also nicht, in der Dokumentation dieser Tools nachzuschlagen, 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

AsciiDoc erstellt sofort hübsche Dokumente. Aber früher oder später werden Sie was, um ihr Aussehen anzupassen.

Die genauen Änderungen hängen vom verwendeten Backend ab. Bei der HTML-Ausgabe können die meisten Änderungen durch Ändern des mit dem Dokument verknüpften CSS-Stylesheets vorgenommen werden.

custom.css, ich möchte alle Abschnittsüberschriften in Rot anzeigen und die folgende custom.css Datei erstellen:

 h2 { color: red; } 

Verarbeiten Sie das Dokument mit dem leicht geänderten Befehl:

 # Set the 'stylesheet' attribute to # the absolute path to our custom CSS file asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt 

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

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

 [role="summary"] AsciiDoc is a text document format .... 

custom.css Datei custom.css die folgende Regel custom.css :

 .summary { font-style: italic; } 

Generieren Sie das Dokument neu:

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

  1. et voila: Der erste Absatz wird jetzt kursiv dargestellt. Mit ein wenig Kreativität, etwas Geduld und ein paar CSS-Tutorials sollten Sie in der Lage sein, Ihr Dokument nach Ihren Wünschen anzupassen.

AsciiDoc nach PDF

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

Sie können CSS jedoch nicht mehr zum Definieren der Formatierung für die PDF-Ausgabe verwenden. Für die am häufigsten verwendeten Einstellungen gibt es Parameter, die Sie über die Befehlszeile festlegen können. Einige Parameter können sowohl mit dem dblatex- als auch mit dem fop- Backend verwendet werden, andere sind für jedes Backend spezifisch.

Eine Liste der von dblatex unterstützten Parameter finden Sie unter //dblatex.sourceforge.net/doc/manual/sec-params.html

Eine Liste der DocBook XSL-Parameter finden Sie unter //docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Da die Anpassung der Ränder eine häufige Anforderung ist, sollten Sie auch Folgendes beachten: //docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Wenn die Parameternamen zwischen den beiden Backends etwas konsistent sind, unterscheiden sich die Befehlszeilenargumente, mit denen diese Werte an die Backends übergeben werden, zwischen dblatex und fop . Überprüfen Sie also zunächst Ihre Syntax, wenn dies anscheinend nicht funktioniert. Aber um ehrlich zu sein, konnte ich beim Schreiben dieses Artikels den Parameter body.font.family nicht für das dblatex- Backend verwenden. Da ich normalerweise fop benutze, habe ich vielleicht etwas verpasst? Wenn Sie weitere Hinweise dazu haben, lese ich gerne Ihre Vorschläge im Kommentarbereich am Ende dieses Artikels!

Erwähnenswert ist die Verwendung von Nicht-Standard-Schriftarten - auch mit fop -, die zusätzliche Arbeit erfordern. Aber es ist auf der Apache-Website ziemlich gut dokumentiert: //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_ work, but, apparently, it isn't ?!?) a2x -v --format pdf \ --dblatex-opts='--param page.margin.inner=10cm' \ --dblatex-opts='--stringparam body.font.family Helvetica' \ asciidoc.txt 

Fein abgestimmte Einstellung für die PDF-Generierung

Globale Parameter sind hilfreich, wenn Sie nur einige vordefinierte Einstellungen vornehmen müssen. Wenn Sie jedoch das Dokument optimieren (oder das Layout vollständig ändern) möchten, sind einige zusätzliche Anstrengungen erforderlich.

Das Herzstück der DocBook-Verarbeitung ist XSLT. XSLT ist eine Computersprache in XML-Notation, mit der beliebige Transformationen von einem XML-Dokument in ... etwas anderes geschrieben werden können. XML oder nicht.

Beispielsweise müssen Sie das DocBook XSL-Stylesheet erweitern oder ändern, um den XSL-FO-Code für die gewünschten neuen Stile zu erstellen. Wenn Sie das dblatex- Backend verwenden, müssen Sie möglicherweise das entsprechende DocBook-to-LaTeX XSLT-Stylesheet ändern . In letzterem Fall müssen Sie möglicherweise auch ein benutzerdefiniertes LaTeX-Paket verwenden. Aber ich werde mich nicht darauf konzentrieren, da dblatex nicht das Backend ist, das ich selbst benutze. Ich kann Sie nur auf die offizielle Dokumentation verweisen, wenn Sie mehr wissen wollen. Aber wenn Sie damit vertraut sind, teilen Sie uns bitte Ihre Tipps und Tricks im Kommentarbereich mit!

Obwohl ich mich nur auf fop konzentriere, habe ich hier nicht wirklich den Raum, um das gesamte Verfahren 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 ein kursiver zusammenfassender Absatz.

Der Trick, den ich hier benutze, besteht darin, ein neues XSLT-Stylesheet zu erstellen, das ursprüngliche DocBook-Stylesheet zu importieren, aber die Attributmengen oder Vorlagen für die zu ändernden Elemente zu überschreiben:

  #FF0000 italic 

Dann müssen Sie a2x, dieses benutzerdefinierte XSL-Stylesheet zu verwenden, um die Ausgabe anstatt der Standardausgabe mit der Option --xsl-file :

 a2x -v --format pdf \ --fop \ --xsl-file=./custom.xsl \ asciidoc.txt 

Wenn Sie mit XSLT, den hier gegebenen Hinweisen und einigen Fragen zu Ihrer bevorzugten Suchmaschine ein wenig vertraut sind, sollten Sie in der Lage sein, die XSL-FO-Ausgabe anzupassen.

Aber ich werde nicht lügen, einige scheinbar einfache Änderungen in der Dokumentausgabe erfordern möglicherweise einige Zeit, um die DocBook XML- und XSL-FO-Handbücher zu durchsuchen, die Stylesheets-Quellen zu untersuchen und einige Tests durchzuführen, bevor Sie endlich das erreichen, was Sie wollen .

Meine Meinung

Das Schreiben von Dokumenten im Textformat hat enorme Vorteile. Und wenn Sie in HTML veröffentlichen müssen, gibt es nicht viele Gründe, AsciiDoc nicht zu verwenden. Die Syntax ist sauber und ordentlich, die Verarbeitung ist einfach und das Ändern der Präsentation erfordert meist leicht zu erlernende CSS-Kenntnisse.

Und selbst wenn Sie die HTML-Ausgabe nicht direkt verwenden, kann HTML heute in 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, wodurch alle Formatierungen erhalten blieben, ohne dass etwas direkt in WordPress eingegeben werden musste.

Wenn Sie in PDF veröffentlichen müssen, bleiben die Vorteile für den Autor gleich. Es wird sicherlich schwieriger, wenn Sie das Standardlayout gründlich ändern müssen. In einer Unternehmensumgebung 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 ein Vergnügen sein, Text mit AsciiDoc zu schreiben. Und zu sehen, wie diese Schriften automatisch in schöne HTML-Seiten oder PDF-Dokumente konvertiert werden!

Wenn Sie schließlich feststellen, dass AsciiDoc zu einfach oder zu komplex ist, sehen Sie sich möglicherweise einige andere Dateiformate mit ähnlichen Zielen an: Markdown, Textile, reStructuredText oder AsciiDoctor, um nur einige zu nennen. Selbst wenn man sich auf Konzepte stützt, die bis in die Anfänge des Computerbetriebs zurückreichen, ist das Ökosystem für lesbare Texte ziemlich umfangreich. Wahrscheinlich reicher war es erst vor 20 Jahren. Als Beweis basieren viele moderne statische Website-Generatoren auf ihnen. Leider liegt dies außerhalb des Geltungsbereichs dieses Artikels. Lassen Sie es uns wissen, wenn Sie mehr darüber erfahren möchten!

Empfohlen

Holen Sie sich Adobe Style Icons für 10 Open Source Creative Apps
2019
Endless zielt darauf ab, Linux dabei zu unterstützen, Endless People zu erreichen
2019
openSUSE ist jetzt auf dem Windows-Subsystem für Linux verfügbar
2019