[[Vorlage(getestet, jammy)]] {{{#!vorlage Wissen [:Pakete installieren: Installation von Programmen] [:Terminal: Ein Terminal öffnen] [:Editor: Einen Editor öffnen] }}} [[Inhaltsverzeichnis(1)]] Die [sourceforge2:docutils:Docutils] {en} sind ein Sammlung von (Hilfs-)Programmen, mit denen Textdateien sehr einfach in HTML-Seiten, LaTeX-Dokumente, XML-Dateien, [http://meyerweb.com/eric/tools/s5/ S5-Präsentationen] {en} und OpenDocument Text File (ODT) umgewandelt werden können. Die Quelldatei ist dabei immer die gleiche, lediglich der eingesetzte Textparser bestimmt Ausgabeformat. Die Docutils entstammen dem Python-Umfeld und sind auch komplett in [:Python:] geschrieben, aber ansonsten nicht Python-spezifisch, sondern universell einsetzbar. Als Markup-Sprache verwenden die Docutils [http://docutils.sourceforge.net/rst.html reStructuredText] {en}, eine sehr einfache Markup-Sprache, welche der Syntax eines Wikis nicht unähnlich ist. reStructuredText ist unter Python die Standard-Sprache für Dokumentationen. = Installation = == aus den Pakwtquellen == Aus den offiziellen Paketquellen sind die Docutils für Python 3.x über folgendes Paket installierbar [1]: {{{#!vorlage Paketinstallation python3-docutils }}} == Manuell == Die aktuelle Version der Docutils lässt sich via [:pip:] installieren: [[Vorlage(Pipinstallation, docutils)]] = Verwendung = Prinzipiell kann man Dokumente in reStructuredText-Syntax mit jedem beliebigen Editor erstellen[4]. Es gibt aber auch spezielle Editoren wie z.B. [:ReText:], die eine Vorschau beinhalten, was insbesondere zum Erlernen der Syntax praktisch ist. Eine Einführung in die Syntax findet man in der [https://docutils.sourceforge.io/docs/user/rst/quickstart.html offiziellen Dokumentation] {en}. Wer es besonders eilig hat, liest die [https://docutils.sourceforge.io/docs/user/rst/quickref.html Schnellanleitung] {en}. Die Syntax erlaubt alle bekannten Elemente wie interne und externe Links, Hervorhebungen, Tabellen, Listen, Fußnoten, automatische Inhaltsverzeichnisse, Hinweisboxen, Einbinden von Bildern und vieles mehr. Im Folgenden ein kurzes, einfaches Beispiel: {{{ ==================== reStructuredText ==================== .. contents Abschnitt 1 ~~~~~~~~~~~~ Die *Docutils* enthalten **reStructuredText**, eine einfache Markup-Sprache, aus der von in Python geschriebenen Parsern u.a. HTML- und LaTeX-Dokumente generiert werden können. reStructuredText beherrscht: * Listen - nummeriert - unnummeriert * Tabellen * und vieles mehr Abschnitt 2 ~~~~~~~~~~~~ Außerdem gibt es Direktiven für Hinweis-Boxen, zum Einbinden von Bildern etc. Abschnitt 2A ############## Dieses Dokument ist nur ein simples Beispiel... mit einem externen Link auf die Homepage von Python_ .. _Python : http://www.python.org }}} Dieses Dokument kann dann unter einem beliebigen Namen gespeichert werden. Möchte man daraus eine HTML5-Datei machen, nutzt man '''rst2html5'''[2]: {{{#!vorlage Befehl rst2html5 DATEINAME AUSGABEDATEI.html }}} '''AUSGABEDATEI.html''' wird automatisch angelegt oder - falls schon vorhanden - ohne Warnung überschrieben. Der generierte HTML-Code für das obige Beispiel sieht so aus: {{{#!code html < reStructuredText

reStructuredText

Abschnitt 1

Die Docutils enthalten reStructuredText, eine einfache Markup-Sprache, aus der von in Python geschriebenen Parsern u.a. HTML- und LaTeX-Dokumente generiert werden können.

reStructuredText beherrscht:

Abschnitt 2

Außerdem gibt es Direktiven für Hinweis-Boxen, zum Einbinden von Bildern etc.

Abschnitt 2A

Dieses Dokument ist nur ein simples Beispiel... mit einem externen Link auf die Homepage von Python

}}} [[Bild(rst.webp, 300, align=right)]] Wie man sieht ist das Stylesheet in die Datei eingebettet, weiterhin wird valides HTML erzeugt. Wie das Ergebnis aussieht, zeigt das Bildschirm-Foto. Mit den Befehlen `rst2xml` kann man entsprechend XML-Dateien (inkl. Doctype-Deklaration) erzeugen, mit `rst2latex` ein [:LaTeX:]-Dokument, mit `rst2odt` ein ODT-Dokument und mit `rst2s5` eine S5-basierte Präsentation. Alle `rst2...`-Befehle kennen eine Vielzahl von Optionen, welche für das "normale" Parsen aber nicht benötigt werden. Eine komplette Übersicht inkl. kurzer Erklärung erhält man, wenn man einen der Parser (egal welchen) ohne Angabe eines Dateinamens aufruft. Oder man ruft die (sehr ausführliche) [:man:Manpage] zum jeweiligen Parser auf. == Fortgeschrittene Möglichkeiten == Das obige Beispiel ist recht simpel, reStructuredText ist aber wesentlich leistungsfähiger. So kann man das Markup z.B. um eigene Direktiven erweitern, eigene Stylesheets einbinden oder die Arbeit des Parsers über die Optionen detailliert beeinflussen. Entsprechende Hinweise findet man in der Dokumentation. = Links = == intern == * [:ReText:] - grafischer Editor für reST, Markdown und Textile * [:Pandoc:] - Alternativprogramm, dass auch Markdown unterstützt == extern == * [sourceforge2:docutils:Projektseite] {en} * [http://docutils.sourceforge.net/rst.html reST-Dokumentation] {en} * [github:rst2pdf/rst2pdf:rst2pdf] und [http://rst2pdf.ralsina.me/stories/index.html rst2pdf] {en} - aus reStructuredText direkt eine PDF-Datei erzeugen #tag: Büro, Python