[[Vorlage(getestet, xenial)]] {{{#!vorlage Wissen [:Pakete installieren: Installation von Programmen] [:Terminal: Ein Terminal öffnen] [:sudo: Root-Rechte erlangen] [: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 und [http://meyerweb.com/eric/tools/s5/ S5-Präsentationen] {en} umgewandelt werden können. Die Quelldatei ist dabei immer die gleiche, lediglich der eingesetzte Textparser bestimmt das "Ergebnis". 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 offiziellen Paketquellen sind die Docutils für Python 3.x über folgendes Paket installierbar [1]: {{{#!vorlage Paketinstallation python3-docutils }}} Für Python 2.x lautet der Paketname: {{{#!vorlage Paketinstallation python-docutils }}} = Manuell == [[Vorlage(Fremd, Software)]] Die manuelle Installation ist sehr einfach. Man lädt den aktuellen [https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ Snapshot] {dl} herunter und installiert ihn via [:pip:] [2]: {{{#!vorlage Befehl pip install docutils-code-VERSION-trunk.zip }}} Soll das Programm systemweit installiert werden, muss pip mit Root-Rechten [3] ausgeführt werden. Weitere Details findet man auch in der [http://docutils.sourceforge.net/README.html#installation Anleitung zur Installation] {en} auf der Projektseite. = 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 [http://docutils.sourceforge.net/rst.html#user-documentation offiziellen Dokumentation] {en}, aufgeteilt in die Bereiche "User-Dokumentation" und "Reference Documentation". Wer es besonders eilig hat, liest die [http://docutils.sourceforge.net/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\\:\\: Inhaltsverzeichnis 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 }}} {{{#!vorlage Hinweis In der Zeile `.. contents\\:\\: Inhaltsverzeichnis` sind die rückwärtigen Schrägstriche zu entfernen. Wegen eines Inyoka-Bugs sind diese im Quelltext enthalten. }}} Dieses Dokument kann dann unter einem beliebigen Namen gespeichert werden. Möchte man daraus eine HTML-Datei machen, nutzt man '''rst2html''': {{{#!vorlage Befehl rst2html 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 reStructured Text

reStructured Text

Inhaltsverzeichnis

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...

}}} [[Bild(rst.png, 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 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. = Dokumentation = Installiert man die Docutils über die Paketverwaltung, wird auch die komplette Dokumentation sowohl im HTML-Format als auch als Textdatei installiert. Zu finden ist die Dokumentation im Ordner '''/usr/share/doc/python-docutils/docs/'''. Die lokal installierte Dokumentation ist weitestgehend identisch mit der online verfügbaren, gilt aber speziell für die auf dem eigenen Rechner vorhandene Version. = Links = * [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 * [:ReText:] - grafischer Editor für reST, Markdown und Textile * [:Pandoc:] - Alternativprogramm, dass auch Markdown unterstützt #tag: Büro, Python