AsciiDoc

Grau

Asciidoc ist eine einfache Aufzeichungssprache die leicht lesbar ist.

Mit AsciiDoc können umfangreiche Dokumenten geschrieben und in verschiedene Formate konvertiert werden.

Dieser PDF-Dokument / HTML-Seite wurde in dieses Format geschrieben und soll ein einfache Beispiel für den Umgang sein.

Der Quellcode sieht so aus:

 PDF oder HTML aus einer Textdatei erzeugen
 ==========================================
 :doctype: article
 :lang: de
 :encoding: UTF-8

 AsciiDoc
 --------

 Asciidoc ist eine einfache Aufzeichungssprache die
 leicht lesbar ist.

 Mit AsciiDoc können umfangreiche Dokumenten
 geschrieben und in verschiedene Formate
 konvertiert werden.

 Dieser PDF-Dokument / HTML-Seite wurde in dieses
 Format geschrieben
 und soll ein einfache Beispiel für den Umgang sein.

 Der Quellcode sieht so aus:

 ---------
    PDF oder HTML aus einer Textdatei erzeugen
    ==========================================
    ...
 ----------

» Text nach HTML konvertieren

Die Konvertierung erfolg aus der Kommandozeile mit:

 $ asciidoc -f html5 <datei.txt>

-f html besagt, dass eine HTML 5 Datei erzeugt werden soll. datei.txt ist der Name der Text Datei, erzeug wird datei.html.

oder

 $ asciidoc -f html5 -o <ausgabe.html> <datei.txt>

» Zusätzliche CSS Datei hinzufügen

 $ asciidoc -b html5 -a stylesheet=`pwd`/datei.css index.html

» Text als Vortragsfolien (HTML) erzeugen

 $ asciidoc -b slidy2 <datei.txt>

» Text nach PDF konvertieren

Vorraussetzung hierfür ist, dass dblatex installiert ist.

 $ a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0"<datei.txt>

a2x gehöhrt zur Paket asciidoc und sollte zur Umsetzung in PDF verwendet werden. Je nach Dokument kann es jedoch schief gehen!

 $ a2x -f pdf --fop index.txt

» Alternative zur PDF Erzeugung

Alternativ könner wkhtmltopdf oder weasyprint verwendet werden.

 $ wkhtmltopdf <datei.html> <datei.pdf>
 $ weasyprint -f pdf  <datei.html> <datei.pdf>
 $ pandoc --latex-engine=xelatex -f html -V geometry:margin=2cm -V papersize:a4paper <datei.html> -o <datei.pdf>

» AsciiDoc anpassen

Mit Themen kann das Aussehen der erzeugten HTML Seiten an den eigene Bedürfnisse angepasst werden.

Hierzu muss lediglich eine passende css Datei geschrieben werden und als Theme hinzugefügt werden.

 $ asciidoc -theme list
 /etc/asciidoc/themes/volnitsky
 /etc/asciidoc/themes/flask
 $ asciidoc --theme install compact.css.zip
 $ asciidoc --theme list
 /etc/asciidoc/themes/volnitsky
 /etc/asciidoc/themes/flask
 /home/user/.asciidoc/themes/compact

Ebenso können auch Backends installiert und verwendet werden.

» Ändern der Datei ~/asciidoc/​themes/​compact/​compact.css

 @media print {
   @page {
     size: A4 portrait;
     margin: 20mm;
     @bottom-left {
       content: 'PDF oder HTML aus einer Textdatei erzeugen';
       font-size: 12pt;
       font-family: 'Liberation Mono';
       vertical-align:top;
     }
     @bottom-right {
       content: "Seite " counter(page) " von " counter(pages);
       font-size: 12pt;
       font-family: 'Liberation Mono';
       vertical-align:top;
      }
   }
 }

Pandoc

Pandoc kann ähnliche Arbeiten wie AsciiDoc verrichten, es stehen aber mehr Ausgabeformate zur Verfügung.

Die markdown Aufzeichnungssprache ist aber ein wenig anders,

Die HTML Dateien beinhaltet nur der Inhaltsteil, Kopfdaten CSS müssen eingebaut werden oder ein minimale Header Option -s.

Damit ist es leichter die Ausgabe entsprchend seine Wünsche zu getallten zumal der erzeugten Code einfacher ist als derjenigen von AsciiDoc.

» HTML Erzeugung

 $ pandoc -t html5 -o <datei.html> <datei.txt>
 $ pandoc -t html5 -V lang:de,title:"PDF oder HTML aus einer Textdatei erzeugen" -o <datei.html> -s <datei.txt>

» HTML mit eigene CSS

CSS kann auch vorgegeben werden:

 $ pandoc -t html5 -o <datei.html> -H <css.html> <datei.txt>

Bemerkung die Datei <css.html> beinhaltet entweder eine Referenz beinhalten

 <link rel="stylesheet" type="text/css" href="datei.css">

oder

        <style type="text/css">
                body {
                        font-family: Sans;
                }
                ...
        </style>

» PDF Erzeugung

 $ pandoc -o <datei.pdf> -s <datei.txt>

Die Ausgabe sieht nicht so gut aus, weitere Paremeter müssen angegeben werden.

 $ pandoc -V geometry:margin=2cm -V papersize:a4paper -o <datei.pdf> <datei.pa>

gibt schon eine bessere Ausgabe.

Vergleich AsciiDoc / Pandoc

» Vorteile AsciiDoc

  • Lesbarer bei Titel
    Titel
    =====
    Untertitel
    ----------
    Unter Untertitel
    ~~~~~~~~~~~~~~~~
  • Einbau Zusätzliche CSS Datei besser gelöst
  • Weiter auf neue Seite vorhanden

» Vorteile Pandoc

  • Mehr Ein- Ausgabe Formate

» Nachteile AsciiDoc

  • PDF Erzeugung mittels dblatex geht nicht immer

» Nachteile Pandoc

  • PDF Ausgabe könnte viel besser sein
  • Weiter auf neue Seite NICHT vorhanden kann emuliert werden
    Workaround:
    \newpage
    <div class="newpage">
  • Bild material unzureichend unterstützt!

Vergleich wkhtmlpdf / weasyprint / Eingebaute PDF-Ausgabe

wkhtmlpdf und weasyprint bieten den Vorteil, dass die PDF Ausgabe leichter beeinflusst wird. Wenn die Werkzeuge das Einbinden von Bilder unterstützen, werden diese auch richtin in der PDF-Ausgabe angezeigt.

» "Native" Ausgabe

  • Geht möglicherweise nicht
  • Probleme mit Bild-Material

» wkhtmltopdf

  • Ladbare Fonts werden übernommen
  • Seiten Informationen (@page { @top-left {…) werden nicht beachtet!
  • Parameter per Kommandozeile notwendig.
  • Page Breaks werden manchmal ignoriert oder falsch gesetzt.
  • Mehr für den Web als für den Druck vorgesehen.

» weasyprint

  • Ladbare Fonts werden nicht übernommen,
    Workaround (Kopieren nach ~/font/)
  • Seiten Informationen (@page { @top-left {…) werden verarbeitet.
  • Typographisch schon recht gut (Vertikale Ausrichtung)

» Work-arounds

  • Eigene css mit vertikalen Raster
  • Seitenumbrüche fest vorgeben wenn die gewünschte Ergebnisse nicht zustanden kommen.

Typs

» Druck von PDF Dateien aus Evince

  • Druck Dialog: Reiter Seitenverarbeitung
    • Seitenskalierung: [ Kein ]
    • [   ] Automatisch drehen und Zentrieren
    • [X] Die Seitengröße anhand der Größe der Dokumentseite wählen

Beispiele und Links

» Beispiele AsciiDoc

» Beispiele Pandoc

» links