Hintergrund: Es gibt bereits ein entsprechendes Plugin, dokutexit, das Vergleichbares leistet, also zumindest eine dokuwiki-Seite in LaTeX-Code umwandelt und das Ergebnis dann gleich noch via pdflatex in ein PDF-Dokument verwandelt. Allerdings ist der resultierende LaTeX-Quellcode alles andere als schön und für eine Weiterverarbeitung als LaTeX-Dokument fairerweise unbrauchbar.

Ziel (dieser Seite): Erst einmal eine Sammlung von Gedanken, was man beim Schreiben des Plugins alles berücksichtigen muß, und dann nach und nach konkretere Ansätze für die Umsetung.

<note important> Diese Seite dient gerade als Notizzettel für Ideen, während die Umsetzung des Plugins schon begonnen hat. Daher sind die Inhalte ständig im Fluß und es gibt keine Garantie, daß manch vielversprechend klingende Idee jemals implementiert wird (für ausgesprochen schlechte Ideen gilt Ähnliches). </note>

<note important>Mac OS X: Das mitgelieferte Entpackprogramm stinkt und kommt nicht mit den ZIP-Archiven klar (sehrwohl hingegen der Befehl zip auf der Kommandozeile). Eine echte Alternative zum mitgeliegerten Entpacker ist Unarchiver.</note>

• Umwandlung einer dokuwiki-Seite in einen ordentlichen LaTeX-Quellcode
• komfortables Herunterladen des LaTeX-Quellcodes mitsamt aller externen Quellen:
  • Bilder
  • BIBTeX-Einträge (nur die benötigten, in einer bib-Datei)
• weitgehende Konfigurierbarkeit über die Konfigurationsoberfläche von dokuwiki

1. Plugin-Klasse erzeugen (Renderer!) ✔
2. Ausgabe des LaTeX-Quellcodes der Grundelemente der Seite ✔
3. anfängliche Konfigurationsmöglichkeiten ✔
4. ZIP-Archiv inklusive der Bilder ✔
   • temp-Dir aufräumen!
5. Bilder als PDF einbinden, so vorhanden ✔
6. zusätzlichen Code für den Header aus Plugins ✔
   • Idee: Plugins können ihre eigenen Strukturen definieren und verwenden
7. verschiedene LaTeX-Templates ✔
8. …
9. erste „veröffentlichte“ Version (0.1)
10. …
11. fertiges, stabiles, sicheres Plugin, das keine Wünsche offen läßt

Eine noch grob unvollständige Liste von Fragen zur Funktionalität und zur Umsetzung des Plugins:

• Wie geht man mit den Überschriften um?
  • dokuwiki-Konvention: nur eine H1-Überschrift pro Seite (als Überschrift)
  • H1 entweder als Titel umsetzen oder als höchste Überschrift (section oder chapter, je nach Dokumentenklasse)
• Was ist die Standardklasse?
  • article oder report?
    • Für die meisten Anwendungsfälle wäre „article“ wohl angebracht.
    • „report“ definitiv im Zusammenspiel mit dem „include“-Plugin und mehreren Seiten (s.u. und später)
  • grundsätzlich: Plugin-intern einen (über die Konfiguration zugänglichen) Schalter einbauen, der die höchste Überschrift (section bzw. chapter) festlegt
• Einbinden von Bildern
  • sollten wesentlich höher aufgelöst sein als die Fassung, die normalerweise im Wiki eingebunden ist
  • Festlegung der Dimensionen
• Kompilieren des LaTeX-Quellcodes (pdflatex) oder nur Sourcecode zum Herunterladen anbieten?
  • Vorteil des Kompilierens wäre ein (hoffentlich) schön gesetztes PDF-Dokument.
  • Nachteil ist die Abhängigkeit von einer (serverseitig) lokalen LaTeX-Installation
    • alternativ externen LaTeX-Compiler verwenden:
      http://texblog.net/latex-link-archive/online-compiler/
    • eleganterweise über einen Schalter in der Konfiguration festlegen
  • evtl. konfigurierbar mit den Optionen „nur Quellcode“ bzw. „Quellcode und PDF-Dokument“

• Umgang mit Links
  • pdflatex kann grundsätzlich ja mit Links umgehen
  • was tun mit internen Links innerhalb der Seite? Umsetzen als Referenzen?
    • definitiv in Abhängigkeit von den Konfigeinstellungen hinsichtlich automatischer Labels für die Überschriften

• mehrere Dokumente zusammenführen
  • geht evtl. analog zum odt-Plugin über das include-Plugin
  • einzelne H1 als chapter und Verwendung der report-Klasse
  • evtl. zusätzliche Angaben zu Titel etc.

insofern könnte man überlegen, ob man das „h1“ einer Wikiseite beim Export einer einzelnen Wikiseite in LaTeX einfach in den „title“ schreibt - und mit „section“ für „h2“ weitermacht - und dann entsprechend für den report einfach nur das „h1“ in ein „chapter“ statt in den „title“ schreibt
aber soweit, daß man mehrere Seiten als einen Report exportieren kann, bin ich noch nicht mal richtig gedanklich…

• DokuWiki-Markup „durchgestrichen“
  • \usepackage[normalem]{ulem} (das „normalem“ ist wichtig!)
• Pakete nach Bedarf einbauen (?)
  • der header wird eh erst am Ende geschrieben und das Dokument nach dem Parsen zusammengesetzt

• Export-Auswahlliste im Template des Wikis über oder unter dem Suchfeld
  • auf Dauer evtl. sogar nicht nur ODT und LaTeX, sondern auch diverse andere Formate (vom ODT ausgehend) bzw. Entscheidung zwischen LaTeX-Quellcode und LaTeX-Source mit allen weiteren Daten als ZIP-Archiv

• evtl. alle benötigten/eingebundenen LaTeX-Pakete mit in das ZIP-Archiv verpacken
  • Erspart die Situation, daß man nur das ZIP-Archiv heruntergeladen hat, aber ein paar der notwendigen Pakete nicht lokal installiert sind.

• pdflatex unterstützt nativ als Grafikformate PDF, JPG und PNG
• GIF wird nicht unterstützt
  • → evtl. GIF auf der Kommandozeile in PNG umbauen

    imagepng(imagecreatefromgif("filename.gif"),"filename.png");

• alle Bilder landen im Unterverzeichnis „figs“
  • Gilt natürlich nur für den Fall, daß ein ZIP-Archiv mit den LaTeX-Quellen und den zugehörigen Bildern erzeugt wird.

Die meisten Dinge sollten über die Konfigurationsoberfläche des DokuWiki zugänglich sein. Dabei ist wichtig, irgendwie die Balance zwischen zu vielen Optionen und einer weitgehenden einfachen Konfigurierbarkeit durch Nutzer, die keinen Dateisystemzugriff haben, zu gewährleisten. Die Grundeinstellungen sollten ein vernünftiges Arbeiten unter Standardbedigungen ermöglichen.

• Dokumentenklasse
  • erstmal nur „article“ oder „report“ unterstützen
• section labels
  • Schalter, legt fest, ob section labels automatisch erzeugt werden
• höchste Überschriftenebene
  • chapter oder section
  • danach richtet sich auch, was mit dem H1 passiert (title oder chapter)
• Zeichencodierung (inputenc-Paket)
• Seitenlayout (geometry-Paket)
  • Papiergröße
  • Ränder
• Titel (erstmal nur im Fall der article-Klasse)
  • Datum anzeigen (Schalter)
  • Autor anzeigen (Schalter)

Das Standard-Markup von DokuWiki hinsichtlich der Einbindung von Bildern entspricht nicht den Ansprüchen, die man (aus einer wissenschaftlichen Perspektive kommend) an die Einbindung von Abbildungen (und gleichermaßen Tabellen) hat.²⁾ Insbesondere gibt es keine einfache Möglichkeit, für Bilder und Tabellen eine entsprechende (formatierte) Beschreibung anzufügen, die klar zum jeweiligen Bild bzw. zur jeweiligen Tabelle gehört.³⁾ Hier versucht das caption-Plugin Abhilfe zu schaffen und geht dabei den bewährten Weg über einfache XML-Container.

Für weitere Details siehe die Seite zum caption-Plugin.

Eine komfortable Variante, insbesondere vor dem Hintergrund, daß man nicht nur LaTeX-, sondern auch ODT-Export (über das ODT-Plugin) haben möchte, ist der Einbau einer Auswahlliste in das verwendete Template (z.B. über oder unter dem Suchfeld, je nach Gegebenheiten):

<div class="export">
  Export: 
  <form method="get" action="<?php wl($ID)?>">
    <select name="do">
      <option value="export_odt">ODT</option>
      <option value="export_dokulatex" selected="selected">LaTeX</option>
    </select>
    <input type="submit" value="Go" class="button" />
  </form>
</div>

Natürlich könnte man die Schaltfläche „Go“ noch als Grafik umsetzen, was evtl. Platz sparte.

Für eine Reihe von DokuWiki-Markups gibt es keine direkte und einfache LaTeX-Entsprechung. Deshalb müssen hier erst einmal von LaTeX-Seite Ideen für entsprechenden Code entstehen, die im LaTeX getestet werden und dann entsprechend implementiert werden können.

• Listings
  • Es gibt entsprechende LaTeX-Pakete, die halbwegs schöne Listings setzen können - inkl. Zeilennummern und Hervorhebung.
• note-Plugin
  • Es gibt Möglichkeiten, farbige Boxen mit runden Ecken zu basteln:
    http://www.cv-templates.info/2009/07/wrapping-text-in-rounded-corners-colorbox-in-latex-with-tikz-and-pgf/

Zumindest für einen Teil dieser Plugins wäre es evtl. sogar nützlich, entsprechenden LaTeX-Code zu schreiben, der Definitionen für Umgebungen bereithält. Nachteilig an diesem Vorgehen ist allerdings noch, daß man dann keine saubere Trennung mehr zwischen dokulatex-Plugin und den jeweiligen Syntaxplugins hat.

Idee: Gibt es grundsätzlich die Möglichkeit, ähnlich wie bei den CSS-Dateien für die Plugins auch LaTeX-Pakete zu bauen, die entsprechend dann vom dokulatex-Plugin gelesen werden? Damit wäre man dann auch gleich das Problem los, daß man einerseits ordentliches Markup im LaTeX-Quellcode verwenden könnte, aber trotzdem die Unabhängigkeit des jeweiligen Plugins vom dokulatex-Plugin bewahrt hätte. Das dokulatex-Plugin ist ja nur ein möglicher Renderer für eine LaTeX-Ausgabe.

• Es gibt etwas ähnliches über Strukturen im ODT-Plugin - quasi ein Array, in das man all den zusätzlichen Code schreibt und das der jeweilige LaTeX-Renderer dann in den Header der LaTeX-Datei einbaut. Man könnte entsprechend in den Plugins innerhalb des LaTeX-Zweiges zum Rendern eine Abfrage machen, die auf dieses Array des Renderers testet und im Falle seiner Existenz die LaTeX-Strukturen definiert, anderenfalls (zur Rückwärtskompatibilität mit anderen LaTeX-Renderern) den LaTeX-Code eben voll ausschreibt.

    var $specialchars = array(
    	'å' => '\aa',
    	'Å' => '\AA',
    	);

Die jeweils neueste Version zum Herunterladen:

• dokulatex-Plugin, aktuelle Version

Bitte beachten: Nutzung auf eigene Verantwortung. Fehler und Sicherheitslücken sind nicht ausgeschlossen. Jeder, der Fehler entdeckt, wird herzlich gebeten, sie entsprechend via BugZilla (s.u.) zu berichten.

• Bildchen mit „\textwidth“ als Breite brauchen bei der Höhenangabe eine Einheit
• griechische Buchstaben
• # als \# ausgeben

<note tip>Für Bug Reports gibt es mittlerweile BugZilla. Bitte Bugs dort eintragen (zum Bugs eintragen ist einmalig eine Registrierung mit einer gültigen Emailadresse notwendig). </note>