BibTeX-Referenzen unter DokuWiki einsetzen.

Das bibtex-Plugin entstand vor dem Hintergrund, das Dokuwiki zur Dokumentation in den Naturwissenschaften zu verwenden. Gleichzeitig blickt der Autor des Plugins auf mehr als zwölf Jahre intensiver Erfahrung mit LaTeX und BibTeX zurück. Daraus entstand der Wunsch, vorhandene BibTeX-Dateien ebenfalls innerhalb des Dokuwikis verwenden zu können sowie ähnlich einfach und komfortabel wie in einem LaTeX-Dokument die jeweiligen Quellen angeben zu können.

Ein weiteres wesentliches Ziel war dabei die (zumindest rudimentäre) Unterstützung von BibTeX-Strings, da der Autor des Plugins für die Verwaltung seiner BibTeX-Datenbank wissenschaftlicher Artikel davon Gebrauch macht.

Hintergrund: Ein eleganter Weg, zwischen dem vollen und abgekürzten Titel bei Journalen hin- und herzuschalten, ist die Pflege zweier BibTeX-Dateien in denen jeweils nur BibTeX-Strings stehen, die eine (interne) Abkürzung zum abgekürzten oder vollen Journaltitel auflösen. Die internen Abkürzungen finden gleichzeitig für das Benennungsschema der Dateien¹⁾ Anwendung.

Gleich vorweg: Das bibtex-Plugin ist bei weitem nicht so mächtig wie BibTeX in Verbindung mit LaTeX. Das betrifft sowohl die Möglichkeit, die Darstellung der Referenzen sowohl im Text als auch in der Bibliographie zu kontrollieren, als auch die (mit dem natbib-Paket unter LaTeX mögliche) Vielfalt der Referenzen im Text (z.B. \citeauthor{key} oder die zusätzliche Angabe von Seitenzahlen über \cite[S. xx]{key}).

Natürlich wurde auch dieses Plugin mit den eigenen Ansprüchen und der eigenen speziellen Situation vor Augen programmiert. Trotzdem wurde auf möglichst allgemeines Vorgehen und Modularität und Erweiterbarkeit geachtet.

Im Gegensatz zu allen anderen dem Autor bekannten bibtex-Plugins für dokuwiki kommt dieses Plugin der Verwendung von Zitationen unter LaTeX am nächsten.

Die Fähigkeiten des Plugins im Überblick:

• einfache Syntax zur Angabe von Referenzen im Text
• Verwendung vorhandener BibTeX-Dateien
  • eine oder mehrere Dateien angebbar
  • Angabe pro Seite oder zentral über dokuwiki-Konfigurationsoberfläche
• Unterstützung der BibTeX-Strings (@STRING{key = {value}})
  • aktuell funktioniert nur die Ersetzung, wenn das Feld alleinig aus dem String besteht, noch nicht das Zusammenfügen von Strings (concatenation, über #)
• Zitierstil für die Referenzen im Text wählbar
  • momentan stehen folgende Zitierstile zur Verfügung: apa, alpha, authordate, numeric
• Formatierung der Referenzen nach BibTeX-Eintragstyp (article, book, inproceedings, …)
  • über die dokuwiki-Konfigurationsoberfläche frei einstellbar
• Sortierung der Referenzen in der Bibliographie wählbar
  • Beim Zitierstil „numeric“ wird diese Einstellung ignoriert und die Zitationen werden in der Reihenfolge ihres Auftauchens im Text sortiert. (Das ist der Tatsache geschuldet, daß dokuwiki eine Seite nur einmal parst und es daher schwierig ist, im Nachhinein Zahlen der Referenzen zu verändern.)
• Ersetzung der häufigsten in BibTeX-Einträgen vorkommenden LaTeX-Codefragmente in HTML, u.a.
  • Umlaute (wenn als \„a etc. angegeben)
  • Akzente (z.B. \'e)
  • Kursiv- und Fettdruck (\emph{…} und \textbf{…})
  • der \url{…}-String
  • griechische Buchstaben (im mathematischen Modus)
  • Hoch- und Tiefstellung (im mathematischen Modus)
  • einige mathematische Sonderzeichen (z.B. \to, \bullet)

Gegenüber BibTeX unter LaTeX fehlende Funktionen:

• Zusammenfügen von BibTeX-Strings (concatenation, über #)
• Unterstützung der @preamble{}
• erweiterte \cite{}-Syntax von natbib
• Querverweise innerhalb der Referenzen (cross-citing)
• weitestgehende Konfigurierbarkeit der Sortierung und Zitierstile (via makebst bzw. direkte Bearbeitung der bst-Dateien)

Das Plugin hat zwei Syntaxkomponenten, eine, die XML-artige Codeblöcke zur Parameterübergabe parst und eine weitere, die die eigentlichen Referenzen verarbeitet. Ein XML-artiger Codeblock kann am Anfang der Seite angegeben werden, um Optionen zu übergeben, ein weiterer muss zwingend an der Stelle angegeben werden, ab der die Bibliographie erscheinen soll²⁾.

Man kann, muss aber nicht notwendigerweise am Beginn einer Seite einen bibtex-Codeblock schreiben, in dem man die wesentlichen Parameter wie BibTeX-Quellen und Zitierstil angibt.

Werden die BibTeX-Quellen über die Konfigurationsoberfläche von Dokuwiki gesetzt, kann auf diesen Codeblock verzichtet werden. Er überschreibt Einstellungen zum Zitierstil gegenüber den Eintragungen über die Konfigurationsdateien (bzw. die Konfigurationsoberfläche, die ja in diese Dateien schreibt), fügt BibTeX-Quellen allerdings nur hinzu.

Bislang können folgende Parameter angegeben werden:

file

BibTeX-Quellen, durch “;„ getrennte Liste von dokuwiki-Seiten

citetype

Zitierstil für die Referenzen im Text

mögliche Optionen: alpha, apa, authordate, numeric

sort

Schalter, der entscheidet, ob die Referenzen alphabetisch sortiert werden

Optionen: true/false

hat für den Zitierstil „numeric“ keinen Effekt

Ein Hinweis zur Sortierung: Sortiert wird nach dem Nachnamen des Erstautors (ohne „von“), gefolgt von der vierstelligen Jahreszahl. Ausgefeiltere Sortierungen, z.B. dass erst alle Zitationen gelistet werden, bei denen der Erstautor alleiniger Autor ist, bevor dann die Zitationen mit weiteren Koautoren folgen, und auch zusätzliche Schalter, um die Sortierreihenfolge weitergehend zu beeinflussen, sind momentan nicht geplant.

Ein Beispiel für einen solchen BibTeX-Block am Anfang einer Datei:

<bibtex>
file=:bib:test
file=:bib:epr
citetype=authordate
sort=true
</bibtex>

Die Syntax der Cite-Befehle (im Text) folgt im Wesentlichen dem vom Autor ursprünglich einmal verwendeten Plugin:

{[whea-tfs-65-1638,kasa-plph-129-726]}
{[kasa-plph-129-726,whea-tfs-65-1638]}
{[aube-n-405-586]}

Die BibTeX-Schlüssel werden in ein doppeltes Klammerpaar eingeschlossen, das aus einem äußeren Paar geschweifter und einem inneren Paar eckiger Klammern besteht.

Die dokuwiki-Ausgabe des obigen Codeblockes sieht dann wie folgt aus:

[Wheaton, 1969Wheaton, R.F.; Ormerod, M.G. (1969): Radiation Damage in Single Crystals of Cysteine, Transactions of the Faraday Society 65:1638-48, Kasahara, 2002Kasahara, Masahiro; Swartz, Trevor E.; Olney, Margaret A.; Onodera, Akihiko; Mochizuki, Nobuyoshi; Fukuzawa, Hideya; Asamizu, Erika; Tabata, Satoshi; Kanegae, Hiromi; Takano, Makoto; Christie, John M.; Nagatani, Akira; Briggs, Winslow R. (2002): Photochemical Properties of the Flavin Mononucleotide-Binding Domains of the Phototropins from Arabidopsis, Rice, and \emphChlamydomonas reinhardtii, Plant Physiology 129:762-773] [Kasahara, 2002Kasahara, Masahiro; Swartz, Trevor E.; Olney, Margaret A.; Onodera, Akihiko; Mochizuki, Nobuyoshi; Fukuzawa, Hideya; Asamizu, Erika; Tabata, Satoshi; Kanegae, Hiromi; Takano, Makoto; Christie, John M.; Nagatani, Akira; Briggs, Winslow R. (2002): Photochemical Properties of the Flavin Mononucleotide-Binding Domains of the Phototropins from Arabidopsis, Rice, and \emphChlamydomonas reinhardtii, Plant Physiology 129:762-773, Wheaton, 1969Wheaton, R.F.; Ormerod, M.G. (1969): Radiation Damage in Single Crystals of Cysteine, Transactions of the Faraday Society 65:1638-48] [Aubert, 2000Aubert, Corinne; Vos, Marten H.; Mathis, Paul; Eker, André P. M.; Brettel, Klaus (2000): Intraprotein radical transfer during photoactivation of DNA photolyase, Nature 405:586-590]

Die Bibliographie selbst, also die Liste der zitierten Referenzen, wird wieder durch ein XML-artiges Konstrukt veranlasst:

<bibtex bibliography>
</bibtex>

Wichtig ist hier die Angabe des zusätzlichen Parameters „bibliography“, da er dem Plugin mitteilt, dass es jetzt die Bibliographie ausgeben soll. Entsprechend sollte dieser Codeblock sinnvollerweise am Ende der Seite, zumindest aber nach allen Zitationen, auftauchen, da DokuWiki Seiten nur einmal parst und alle Zitationen, die erst nach diesem Codeblock eingefügt werden, keine Aufnahme in die Bibliographie finden.

Auch hier kann man wieder mit zusätzlichen Optionen das Ergebnis beeinflussen, allerdings ist die Zahl der Optionen deutlich eingeschränkt, da es an dieser Stelle z.B. nicht mehr sinnvoll ist, weitere Quellen einzufügen oder gar den Zitierstil ändern zu wollen.

Bislang können folgende Parameter angegeben werden:

sort

Schalter, der entcheidet, ob die Referenzen alphabetisch sortiert werden

Optionen: true/false

hat für den Zitierstil „numeric“ keinen Effekt

Die Ausgabe des oben angegebenen Codeblockes sieht dann entsprechend wie folgt aus:

• Wheaton, R.F.; Ormerod, M.G. (1969): Radiation Damage in Single Crystals of Cysteine, Transactions of the Faraday Society 65:1638-48
• Kasahara, Masahiro; Swartz, Trevor E.; Olney, Margaret A.; Onodera, Akihiko; Mochizuki, Nobuyoshi; Fukuzawa, Hideya; Asamizu, Erika; Tabata, Satoshi; Kanegae, Hiromi; Takano, Makoto; Christie, John M.; Nagatani, Akira; Briggs, Winslow R. (2002): Photochemical Properties of the Flavin Mononucleotide-Binding Domains of the Phototropins from Arabidopsis, Rice, and \emphChlamydomonas reinhardtii, Plant Physiology 129:762-773
• Aubert, Corinne; Vos, Marten H.; Mathis, Paul; Eker, André P. M.; Brettel, Klaus (2000): Intraprotein radical transfer during photoactivation of DNA photolyase, Nature 405:586-590

Für den Fall, dass man ausser den oder anstatt der im Text zitierten Referenzen weitere Referenzen angeben möchte, zum Beispiel für weiterführende Literatur, ist auch das möglich.

Der Aufruf erfolgt wie schon für die Ausgabe der Bibliographie (s.o.) durch ein XML-artiges Konstrukt, dessen Grundstruktur wie folgt aussieht:

<bibtex furtherreading>
</bibtex>

Allerdings ist es hier wichtig, mit dem Schalter nocite=³⁾ Referenzen anzugeben, die in dieser erweiterten Bibliographie erscheinen sollen. Dabei können pro nocite=-Zeile mehrere BibTeX-Schlüssel durch Komma getrennt und/oder mehrere nocite=-Zeilen angegeben werden.

Ein Beispiel könnte wie folgt aussehen:

<bibtex furtherreading>
file=:bib:other
citetype=numeric
sort=true
nocite=fedo-bj-84-2474,brig-pc-13-993
nocite=kopp-nar-32-D230
</bibtex>

Wie man erkennen kann, sind hier wieder alle Optionen (Schalter) erlaubt, die schon für die Bibliographie am Seitenanfang erlaubt waren. Sind über die Konfiguration bereits die BibTeX-Quellen, der Zitierstil und die Sortierung festgelegt, dann bedarf es hier nur noch der Angabe der BibTeX-Schlüssel über nocite.

Wird als Zitierstil „numeric“ gewählt, fängt die Nummerierung wieder bei 1 an. Werden über file= weitere BibTeX-Quellen angegeben, werden diese zu den bereits vorhandenen Quellen (entweder über die DokuWiki-Konfiguration oder über die Angabe am Seitenanfang festgelegt) hinzugefügt.

Die Ausgabe des oben angegebenen Beispiels sieht dann so aus:

[1]

Briggs, W.R.; Beck, C.F.; Cashmore, A.R.; Christie, J.M.; Hughes, J.; Jarillo, J.A.; Kagawa, T.; Kanegae, H.; Liscum, E.; Nagatani, A.; Okada, K.; Salomon, M.; Rüdiger, W.; Sakai, T.; Takano, M.; Wada, M.; Watson, J.C. (2001): The Phototropin Family of Photoreceptors, Plant Cell 13:993-997

[2]

Fedorov, Roman; Schlichting, Ilme; Hartmann, Elisabeth; Domratcheva, Tatjana; Fuhrmann, Markus; Hegemann, Peter (2003): Crystal Structures and Molecular Mechanism of a Light-Induced Signaling Switch: The Phot-LOV1 Domain from Chlamydomonas reinhardtii, Biophysical Journal 84:2474-2482

[3]

Kopp, Jürgen; Schwede, Torsten (2004): The SWISS-MODEL Repository of annotated three-dimensional protein structure homology models, Nucleic Acids Research 32:D230-D234

Ein anderes Beispiel könnte folgenden Code haben:

<bibtex furtherreading>
citetype=authordate
sort=true
nocite=kasa-plph-129-726,whea-tfs-65-1638,hoff_aepr,kay2002-FAD,hore_aepr
</bibtex>

Das Ergebnis sieht dann wie folgt aus, und hier wird auch gleichzeitig klar, dass die mittels nocite= angegebenen Referenzen der ersten „furtherreading“-Bibliographie nicht wieder angezeigt werden, die beiden Bibliographien also vollständig unabhängig sind:

• Kasahara, Masahiro; Swartz, Trevor E.; Olney, Margaret A.; Onodera, Akihiko; Mochizuki, Nobuyoshi; Fukuzawa, Hideya; Asamizu, Erika; Tabata, Satoshi; Kanegae, Hiromi; Takano, Makoto; Christie, John M.; Nagatani, Akira; Briggs, Winslow R. (2002): Photochemical Properties of the Flavin Mononucleotide-Binding Domains of the Phototropins from Arabidopsis, Rice, and \emphChlamydomonas reinhardtii, Plant Physiology 129:762-773
• Wheaton, R.F.; Ormerod, M.G. (1969): Radiation Damage in Single Crystals of Cysteine, Transactions of the Faraday Society 65:1638-48

Im Ergebnis bedeutet das, dass man über den „furtherreading“-Schalter in der Angabe von <bibtex>…</bibtex> beliebig viele Listen weiterführender Literatur erzeugen kann, die voneinander (bis auf die angegebenen BibTeX-Quellen) unabhängig sind.

Das bibtex-Plugin ist über die DokuWiki-interne Administrations- und Konfigurationsoberfläche in weiten Teilen konfigurierbar. Insbesondere können dort BibTeX-Quellen, der Zitierstil und die Sortierung angegeben werden, so dass die Angabe des XML-artigen Codeblockes am Anfang einer Seite entfällt.

Des Weiteren sind für jeden Eintragstyp die Formatierungsstrings einstellbar. Das ist insbesondere bei den BibTeX-Eintragstypen von Vorteil, bei denen es fast keine verpflichtenden Felder gibt (@misc, @unpublished) und es deshalb schwer ist, verbindliche Vorgaben zu machen.

• Verbesserung des Codes
  • Sicherheitsaspekte: quoting von Sonderzeichen
• nocite in „normaler“ Bibliographie erlauben ✔
• Links auf PDFs (so vorhanden)
  • setzt voraus, daß der Dateiname gleich dem BIBTeX-Schlüssel ist
  • nur anzeigen, wenn der gegenwärtige Nutzer die Rechte an der Datei hat
    • Wichtig für die Verwendung in (halb-)offenen Wikis, da die PDFs von wissenschaftlichen Artikeln in der Regel strengen Regeln hinsichtlich der Weiterverbreitung unterliegen.
    • auth_quickaclcheck() Link
  • Ablage evtl. unter data/media/bib/
    • Da die Bibliographien überall liegen können, sollte das über eine Konfigurationsoption (mit Standardeinstellung /data/media/bib/, dann entsprechend dargestellt als :bib) gelöst werden.

• Rendering für andere Modi als xhtml
  • LaTeX
    • Verbesserung der Unterstützung des <bibliography>-Tags
    • Handhabung der Referenzen (evtl. zugänglich machen, so daß nur die zitierten Referenzen in eine Datei geschrieben werden können)
  • ODT
    • vorerst einfach die Referenzen der Bibliographie entsprechend umsetzen
    • Wenn keine Bibliographie angegeben ist, evtl. in Fußnoten verpacken? Alternativ dann nur die Schlüssel anzeigen⁴⁾
    • Problem ist momentan, daß die Funktion bibtexrenderer die BIBTeX-Einträge in HTML rendert, was man entsprechend für ODT abwandeln müßte. Ein Umsetzen des LaTeX-Quellcodes in den BIBTeX-Einträgen in DokuWiki-Markup und anschließendes Parsen/Rendern über die normalen DokuWiki-Werkzeuge wäre vermutlich der sauberste Weg. Das erscheint momentan aber aufgrund der Komplexität und des mangelnden Überblicks über derartige DokuWiki-Interna nicht gangbar.

• Referenzmanager als eigenes Fenster (vgl. dem Medienmanager)
  • Suchen nach Publikationen
  • bequemes Einfügen des jeweiligen Schlüssels an der aktuellen Stelle

Die jeweils neueste Version zum Herunterladen:

• GitHub: https://github.com/tillbiskup/dokuwiki-bibtex

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

Direkt aus dem GitHub-RSS-Feed:

• Merge pull request #8 from SECtim/sqlite_performance (2024/02/24 18:30)
• Update changelog (2024/02/24 18:28)
• Update plugin info (2024/02/24 17:57)
• Merge branch 'SECtim-improved_bibliography_formatting' (2024/02/24 17:56)
• Execute SQL insert/update statements in a single transaction (2023/11/20 10:22)
• Deduplicate code for storing entries (2023/11/20 09:35)
• Merge branch 'master' into improved_bibliography_formatting (2023/11/20 08:09)
• Add format string syntax change to CHANGELOG.md (2023/11/20 07:37)

Umbenennung von „bibtex“ in „bibtex4dw“, um es (endlich) auf dokuwiki.org „publizieren“ zu können, größere Änderungen am Code, u.a. Zusammenfassung von SQL-Anfragen in eine Transaktion (massive Beschleunigung) und Anfänge von Rewrite.

Optional kann das bibtex-Plugin nun auf eine SQLite-Datenbank (unter Verwendung des sqlite-Plugins) zurückgreifen. Das erhöht gerade bei großen Datenbanken die Geschwindigkeit merklich – bzw. behebt die Latenzen beim Rendern von Seiten mit Referenzen.

Anzeige von PDF-Dokumenten: Gibt es zu einer Referenz in einem konfigurierbaren Namensraum eine PDF-Datei mit identischem Namen wie der BIBTeX-Schlüssel und hat der angemeldete Nutzer darüber hinaus Leserechte auf diesen Namensraum, wird ihm ein PDF-Link am Ende der Referenz angezeigt.

Zur Verwendung mit dem neuen DokuWiki-Standard-Template wurde die Darstellung der „Tooltips“ angepaßt und in JavaScript realisiert (das war notwendig, damit sie nicht abgeschnitten werden).