[[Vorlage(Getestet, focal bionic)]] {{{#!vorlage Wissen [:Pakete installieren: Installation von Programmen] [:Terminal: Ein Terminal öffnen] [:Editor: Einen Editor öffnen] }}} [[Inhaltsverzeichnis(2)]] [[Bild(Wiki/Icons/terminal.png, 48, align=left)]] [https://pandoc.org/ Pandoc] {en} ist ein Dokumentenkonverter für die Kommandozeile. Mit ihm können Textdateien, die in einer Auszeichnungssprache verfasst wurden, in ein anderes Format wie [:LaTeX:] oder [wikipedia:Html:HTML] umgewandelt werden ([:Pandoc#Unterstuetzte-Formate:Liste der unterstützten Formate]). Das Programm wurde von [http://johnmacfarlane.net/ John MacFarlane] {en} in [wikipedia:Haskell_(Programmiersprache):Haskell] geschrieben und steht unter der [wikipedia:GNU_General_Public_License:GPL]-Lizenz. Auf der Homepage von Pandoc gibt es die Möglichkeit, Pandoc [https://pandoc.org/try online auszuprobieren] {en}. = Hintergrund = Im Internetzeitalter werden Texte häufig in verschiedenen Formaten benötigt. Ein vorstellbarer Anwendungsfall ist bspw. die Ausarbeitung von Notizen zu einem Blogartikel, der leicht abgeändert als Wikipedia-Artikel publiziert und anschließend mit LaTeX zu einem Aufsatz umgeschrieben wird, bevor er als [:LibreOffice:]-Dokument an eine Zeitschrift versandt wird. Die Kernthesen des Aufsatzes werden schließlich in Folienform auf einer Konferenz präsentiert und auf einer Webseite der Öffentlichkeit zugänglich gemacht. Hier setzt Pandoc an: Es erlaubt die Konvertierung in die erforderlichen Formate. Ausgangsformat ist dabei im Idealfall eine – meist intuitiv verständliche – vereinfachte Auszeichnungssprache wie [wikipedia:Markdown:] oder [wikipedia:ReStructuredText:]. {{{#!vorlage Hinweis Bei komplexeren Ausgangsformaten (wie bspw. LaTeX) kann es sein, dass die Konvertierung Fehler aufweist. Ein häufiges Problem sind beispielsweise typographische Anführungszeichen. Die von Pandoc erzeugte Ausgabedatei sollte daher vor der Weiterverwendung überprüft werden. }}} Eine solche – in einer vereinfachten Auszeichnungssprache geschriebene – Datei (hier im Markdown-Format) kann wie das folgende Beispiel aussehen: {{{ # Markdown-Text ## Abschnitt 1 *Pandoc* kann **Markdown** verarbeiten, eine einfache Markup-Sprache, aus der von Parsern u.a. HTML- und LaTeX-Dokumente generiert werden können. Man kann Syntax-Elemente auch "escapen", also bspw. die automatische \*Kursivierung\* verhindern. Markdown Text beherrscht: - Listen unnummeriert - auf mehreren Ebenen verschachteln - ... so wie hier - Tabellen - und vieles mehr Listen nummeriert: 1. erste Element 2. zweites Element Linien: - - - ## Abschnitt 2 Außerdem gibt es noch weitere Auszeichnungselemente, bspw. Zitatblöcke: > "All stories are true ... But this one really happened, if that’s what you mean." ### Abschnitt 2a Dieses Dokument ist nur ein simples Beispiel! }}} Wenn man einen Markdown-Editor wie [:ReText:], [:Typora:] oder [launchpad:utext:] {en} verwendet, kann man bereits innerhalb eines Vorschaufensters die Auszeichnung verfolgen. {{{#!vorlage Tabelle <:>[[Bild(./utext_markdown.png, x300)]] +++ <:>Markdown-Editor [launchpad:utext:] mit Vorschaufenster }}} Pandoc wandelt diese Datei auf Wunsch bspw. in ein LaTeX-Dokument um. Das Ergebnis einer solchen Umwandlung mit: {{{#!vorlage Befehl pandoc -s -S -f markdown -t latex -o ausgabe.tex eingabe.md }}} sieht wie folgt aus: {{{#!code latex \documentclass{article} \usepackage{amssymb,amsmath} \usepackage[mathletters]{ucs} \usepackage[utf8x]{inputenc} % Redefine labelwidth for lists; otherwise, the enumerate package will cause % markers to extend beyond the left margin. \makeatletter\AtBeginDocument{% \renewcommand{\@listi} {\setlength{\labelwidth}{4em}} }\makeatother \usepackage{enumerate} \usepackage[breaklinks=true,unicode=true,pdfborder={0 0 0}]{hyperref} \setlength{\parindent}{0pt} \setlength{\parskip}{6pt plus 2pt minus 1pt} \setcounter{secnumdepth}{0} \begin{document} \section{Markdown-Text} \subsection{Abschnitt 1} \emph{Pandoc} kann \textbf{Markdown} verarbeiten, eine einfache Markup-Sprache, aus der von Parsern u.a. HTML- und LaTeX-Dokumente generiert werden können. Man kann Syntax-Elemente auch ``escapen'', also bspw. die automatische *Kursivierung* verhindern. Markdown Text beherrscht: \begin{itemize} \item Listen unnummeriert \begin{itemize} \item Mit mehreren Verschachtelungsebenen \item \ldots{} so wie hier \end{itemize} \item Tabellen \item und vieles mehr \end{itemize} Listen nummeriert: \begin{enumerate}[1.] \item erste Element \item zweites Element \end{enumerate} Linien: \begin{center}\rule{3in}{0.4pt}\end{center} \subsection{Abschnitt 2} Außerdem gibt es noch weitere Auszeichnungselemente, bspw. Zitatblöcke: \begin{quote} ``All stories are true \ldots{} But this one really happened, if that's what you mean.'' \end{quote} \subsubsection{Abschnitt 2a} Dieses Dokument ist nur ein simples Beispiel! \end{document} }}} An dieser Beispiel-Datei sieht man auch gut, dass Pandoc sich nicht an deutsche Formatierungs- und Maßeinheitskonventionen hält. Bei einer Umwandlung in eine LaTeX-Datei sollte daher das Ergebnis entweder noch manuell korrigiert oder Pandoc zusätzliche Angaben zur gewünschten Formatierung (d.h. insbesondere: eine individuelle Präambel) übergeben werden. = Installation = Pandoc ist in den offiziellen Paketquellen enthalten. Es muss folgendes Paket installiert [1] werden: {{{#!vorlage Paketinstallation pandoc, universe }}} = Bedienung = == Aufruf == Pandoc wird im Terminal [2] mit folgendem Befehl aufgerufen: {{{#!vorlage Befehl pandoc OPTIONEN EINGABEDATEI }}} == Optionen == Pandoc kennt folgende Optionen: {{{#!vorlage Tabelle Optionen +++ Option Beschreibung +++ `-c URL` oder `--css=URL` Link auf ein CSS-Style-Sheet +++ `--columns=ZAHL` Angabe der Buchstaben pro Zeile (bei aktiviertem automatischen Zeilenumbruch) +++ `--data-dir=DIRECTORY` Verzeichnis, in dem Pandoc nach Dateien sucht (z.B. nach einzubindenden CSS-Stylesheets). Standard: '''~/.pandoc/''' +++ `--epub-stylesheet=DATEI` Verwendung von DATEI (ein CSS-Style-Sheet epub.css) als Formatvorlage für eine EPUB-Ausgabe +++ `-f FORMAT` oder `-r FORMAT` Format der Eingabedatei +++ `-N` oder `--number-sections` Nummerierte Abschnitte in LaTeX-, ConTeXt- oder HTML-Ausgaben (Standard: nicht nummeriert) +++ `--no-wrap` Deaktivierung des automatischen Zeilenumbruchs (Standard: mit für Ausgabeformat passenden Werten aktiviert) +++ `--normalize` Vereinheitlichung des Dokuments (Bsp.: Entfernung aufeinander folgender Leerzeichen) +++ `-o DATEI` oder `--output=DATEI` Ausgabe in DATEI, nicht nach [:Shell/Umleitungen#stdin-stdout-stderr-Kanaele-der-Bash:stdout] +++ `--reference-odt=DATEI` Verwendung von DATEI als Formatvorlage für eine ODT-Ausgabe +++ `-s` oder `--standalone` Ausgabedatei enthält bereits passende Header- und Footer-Felder (Bsp.: vollständiges LaTeX-Ausgabedokument, Präambel also enthalten) +++ `-S` oder `--smart` Typographisch korrekte Konvertierung (Beispiele: typographische Anführungszeichen, Halbgeviertstrich, …) (für LaTeX- und ConTeXt-Ausgaben ist die Option Standard) +++ `-t FORMAT` oder `-w FORMAT` Format der Ausgabedatei +++ `--template=DATEI` DATEI wird als Vorlage für das Ausgabedokument verwendet (nur mit `--standalone`) +++ `--toc` oder `--table-of-contents` Automatische Generierung von Inhaltsverzeichnis in Ausgabedokument }}} Weitere Optionen und teilweise detailliertere Angaben sind der [:man:Manpage] zu entnehmen. == Unterstützte Formate == Pandoc unterstützt folgende Formate (diese Tabelle bezieht sich auf die aktuelle Version, die nicht der unter Ubuntu installierten entsprechen muss): {{{#!vorlage Tabelle Von Pandoc unterstützte Formate +++ Formatname Optionsname Eingabe Ausgabe +++ [wikipedia:ConTeXt:] `context` nein ja +++ [wikipedia:DocBook:DocBook XML] `docbook` ja ja +++ [wikipedia:Org-mode:Emacs Org-Mode] `org` ja ja +++ [wikipedia:Epub:EPUB] `epub` ja ja +++ [wikipedia:Texinfo:GNU Texinfo] `texinfo` nein ja +++ [wikipedia:Groff:groff] (Manpages) `man` nein ja +++ [wikipedia:Haskell_(Programmiersprache):Haskell] `native` ja ja +++ [wikipedia:Html:HTML] `html` ja ja +++ [wikipedia:HTML5:HTML 5] `html5` nein ja +++ [wikipedia:JSON:] `json` ja ja +++ [wikipedia:LaTeX:] `latex` ja ja +++ [wikipedia:Markdown:] `markdown` ja ja +++ [wikipedia:Mediawiki:] `mediawiki` ja ja +++ [wikipedia:OpenDocument:ODT (Open Document Text)] `odt` ja ja +++ [wikipedia:Office_Open_XML:OpenDocument XML] `opendocument` ja ja +++ [wikipedia:ReStructuredText:] `rst` ja ja +++ [wikipedia:Rich_Text_Format:RTF (Rich Text Format)] `rtf` nein ja +++ [wikipedia:S5_(Dateiformat):S5] `s5` nein ja +++ [http://www.w3.org/Talks/Tools/Slidy2/ HTML Slidy] {en} `slidy` nein ja +++ [wikipedia:Plain_text:(Plain) Text] `plain` nein ja +++ [wikipedia:Textile:] `textile` ja ja }}} = Beispiele = == Markdown nach ODT == Eine Markdown-Datei '''eingabe.md''' kann mit folgendem Befehl in ein ODT-Dokument (LibreOffice) umgewandelt werden: {{{#!vorlage Befehl pandoc eingabe.md -o ausgabe.odt }}} Vollständig ausgeschrieben würde der Befehl lauten: {{{#!vorlage Befehl pandoc -f markdown -t odt eingabe.md -o ausgabe.odt }}} == ReStructuredText nach HTML == Der folgende Befehl erzeugt aus der RST-Datei '''eingabe.rst''' ein HTML-Dokument '''ausgabe.html''' mit einem Inhaltsverzeichnis (`--toc`), Header und Footer (`-s`) und typographisch korrekten Zeichen (`-S`). Zur Formatierung wird die Datei '''~/.pandoc/format.css''' herangezogen. {{{#!vorlage Befehl pandoc -s -S --toc -c ~/.pandoc/format.css eingabe.rst -o ausgabe.html }}} Pandoc können auch mehrere Eingabedateien übergeben werden: {{{#!vorlage Befehl pandoc -s -S --toc -c ~/.pandoc/format.css -o ausgabe.html eingabe1.rst eingabe2.rst eingabe3.rst }}} == Manpage aus Markdown-Datei == Der folgende Befehl erzeugt aus der Markdown-Datei '''eingabe.md''' die [:man:Manpage] '''ausgabe.1''': {{{#!vorlage Befehl pandoc -s -w man eingabe.md -o ausgabe.1 }}} == Textdatei aus Webseite == Der folgende Befehl erzeugt aus [:ubuntuusers/Moderatoren/Richtig_fragen:dieser Webseite] eine einfache Textdatei: {{{#!vorlage Befehl pandoc -s -t plain -r html http://wiki.ubuntuusers.de/ubuntuusers/Moderatoren/Richtig_fragen -o ausgabe.txt }}} == E-Book-Erstellung (EPUB) == Ein sehr einfaches E-Book im EPUB-Format kann man erstellen, indem man in einem Editor [2] folgenden Inhalt eingibt und als Datei '''eingabe.txt''' abspeichert: {{{ % Mein erstes Buch % Johann Wolfgang von Goethe, Jr. Das ist mein Buch # Kapitel 1 Aller Anfang ist schwer. # Kapitel 2 So long, and thanks for all the fish: Das war's dann auch schon! }}} Anschließend kann die Datei mit folgendem Befehl in ein E-Book umgewandelt werden: {{{#!vorlage Befehl pandoc eingabe.txt -o meinbuch.epub }}} Eine [https://pandoc.org/epub.html Anleitung zum Erstellen komplexerer E-Books] {en} findet sich auf der Website von Pandoc. == PDF-Ausgabe == Pandoc kann – über [:LaTeX:] – praktisch aus jedem Eingabeformat eine PDF-Datei erzeugen: {{{#!vorlage Befehl pandoc eingabe.md -o ausgabe.pdf pandoc eingabe.txt -o ausgabe.pdf }}} In früheren Versionen wurde das zusätzliche Hilfsprogramm '''markdown2pdf''' verwendet, das ausschließlich mit Markdown funktionierte: {{{#!vorlage Befehl markdown2pdf eingabe.md -o ausgabe.pdf }}} == MediaWiki-Konvertierung == Um eine Datei im MediaWiki-Format (wie es von der Wikipedia genutzt wird) zu erstellen, muss folgender Befehl verwendet werden (hier mit einer reST-Eingabedatei): {{{#!vorlage Befehl pandoc -s -S -t mediawiki --toc eingabe.rst -o ausgabe.wiki }}} = Links = == extern == * [https://pandoc.org/ Projektseite] {en} * [https://pandoc.org/README.html Pandoc User’s Guide] {en} – Offizielle Anleitung * [https://pandoc.org/demos.html Examples] {en} – Beispiele * [https://pandoc.org/epub.html Creating an Ebook with Pandoc] {en} – Erstellung eines (mit einer CSS-Datei) formatierten E-Books * [https://kofler.info/folien-mit-pandoc-erstellen/ Folien mit Pandoc erstellen] {de} - Blogbeitrag, 10/2013 * [http://www.linux-community.de/Internal/Artikel/Print-Artikel/LinuxUser/2010/12/Texte-konvertieren-mit-Pandoc Flott durchgereicht - Texte konvertieren mit Pandoc] {de} – Linux User, 12/2010 == intern == * [:docutils:] – Umwandlung von Textdateien * [:Shell/Anwendungen:] {Übersicht} Übersichtsartikel #tag: Büro, Shell, eBook, Präsentation, Markdown