# Referencer Plugin-Leitfaden V 1.1.6

Referencer ist ein Werkzeug, das Ihnen bei der Verwaltung Ihrer Dokumentensammlung hilft und aus Ihren Dokumenten eine Bibliografie erstellt. Dieser Leitfaden beschreibt die Plugin-Schnittstelle von Referencer.

2009
John Spray
2009
Mario Blättermann (mariobl@gnome.org)
Referencer Development Team

Das vorliegende Dokument kann gemäß den Bedingungen der GNU General Public License (GPL), Version 2 kopiert, verteilt und/oder modifiziert werden. Eine Kopie der GPL finden Sie unter diesem Link oder in der mit diesem Handbuch gelieferten Datei COPYING.

John
Spray

    	    jcspray@icculus.org

Referencer Plugin-Leitfaden V 1.1.6
18. Juni 2009

John Spray

This is the Plugin Writing Guide version 1.1.6 of Referencer.

## Rückmeldungen

Um Fehler zu melden oder einen Vorschlag zur Anwendung Referencer oder zu diesem Handbuch zu machen, besuchen Sie bitte die

## Einführung

Die Plugin-Schnittstelle von Referencer stellt einen relativ schmerzlosen Weg zum Hinzufügen neuer Funktionalität bereit. Plugins können entweder weitere Einträge zu Menüs und Werkzeugleisten der Benutzeroberfläche hinzufügen (Aktionen-Plugins) oder Hilfsfunktionen zum Herunterladen von Metadaten für Dokument bereitstellen (Metadaten-Plugins).

Zum Zeitpunkt der Erstellung dieses Leitfadens ist die Plugin-Schnittstelle noch neu und noch nicht ausreichend getestet. Obwohl nicht völlig unbrauchbar, gibt es doch Schwachstellen. Informieren Sie sich darüber in der Mailingliste.

Dieses Dokument bezieht sich auf die Version 1.1.6 von Referencer.

## Installieren von Plugins

Plugins sind Python-Skripte. Diese müssen nicht ausführbar sein, jedoch ist die Dateiendung .py zwingend notwendig. Beim Start sucht Referencer an verschiedenen Orten nach Plugins: ./plugins, $PREFIX/lib/referencer, und ~/.referencer/plugins.

## Allgemeine API

### Informative Beschreibung des Plugins

Alle Plugins müssen eine Beschreibungsdatei im Dateiabschnitt `referencer_plugin_info` enthalten. Diese stellt eine Anzahl von Feldern bereit, die das Plugin beschreiben. Alle Plugins müssen zwingend die folgenden Felder bereitstellen, weitere optionale Felder werden in den folgenden Abschnitten beschrieben.

#### Plugins

Plugin-Name | Beschreibung
--- | ---
author | Name des Autors oder durch Kommata getrennte Liste, z.B. "Hans Schmidt"
version | Eine Zeichenkette für die Version des Plugins, z.B. "1.3.2"
longname | Der Zweck des Plugins, z.B. "Format author initials"

Die Struktur der Plugin-Informationen könnte folgendermaßen definiert werden:

    	referencer_plugin_info =
    	 {
    	 "author":    "John Spray",
    	 "version":   "1.1.2",
    	"longname": _("Generate keys from metadata")
    	}

### Hilfsfunktionen

Importieren Sie das Modul `referencer`, um auf folgende Funktionen zugreifen zu können:

referencer.download(Kurzbeschreibung, Langbeschreibung, Adresse)

  Funktion zur Vereinfachung von Web-Downloads. Gibt eine Zeichenkette zurück, die den Inhalt der heruntergeladenen Datei enthält, oder eine leere Zeichenkette bei Fehlern. Beispiel:

      referencer.download("Downloading tripe", "Downloading page from
      slashdot.org", "http://www.slashdot.org")

  Um die Einfachheit zu gewährleisten, übernimmt diese Funktion die Proxy-Einstellungen von gnome-vfs, so dass sie bevorzugt werden sollte, falls keine komplexe HTTP-Funktionalität gefordert ist. Im Falle eines Fehlers gibt die Funktion stets eine leere Zeichenkette zurück.

referencer._(Text)

  Übersetzungsfunktion. Um die Übersetzbarkeit aller für den Benutzer sichtbaren Zeichenketten zu gewährleisten, sollten Sie "from referencer import _" benutzen. Jede sichtbare Zeichenkette sollte als _("Etwas Text") ausgedrückt werden.

referencer.pref_get(Schlüssel)

  Lädt eine persistente Konfigurationszeichenkette. Falls der Schlüssel nicht gefunden wurde, wird eine leere Zeichenkette zurückgegeben. Um Konflikte mit anderen Plugins zu vermeiden, sollte jedes Plugin Schlüsselnamen verwenden, die den Namen des Plugins als Präfix enthalten. Diese Konfigurationseinträge werden in der GConf-Datenbank zusammen mit der originalen Konfiguration von Referencer gespeichert.

referencer.pref_set(Schlüssel, Wert)

  Setzt eine persistente Konfigurationszeichenkette.

### Die `document`-Klasse

Referencer präsentiert individuelle Dokumente über die document-Klasse. Eine begrenzte Anzahl von Getter/Setter-Methoden werden unterstützt:

get_field(Schlüssel)

  Holt ein Feld wie z.B. »author«. Groß-/Kleinschreibung wird nicht berücksichtigt. Eingebaute Felder sind »doi«, »title«, »volume«, »number«, »journal«, »author«, »year« und »pages«. Weitere Felddefinitionen können, müssen aber für ein Dokument nicht existieren. Das Holen eines nicht existierenden Feldes gibt eine leere Zeichenkette zurück.

set_field(Schlüssel, Wert)

  Legt ein Feld fest.

get_key()

  Holt den Schlüssel des Dokuments. Dies ist die Kennung, die der Benutzer zur Referenzierung eines Dokuments in einem Latex-Dokument verwendet.

set_key(Wert)

  Legt den Schlüssel fest.

get_filename()

  Holt die Adresse (z.B. »file:///home/ich/Eine_Datei.pdf«) der einem Dokument zugeordneten Datei.

set_filename(Wert)

  Setzt die Adresse des Dokuments auf Wert.

parse_bibtex(Wert)

  Liest den Wert als Klartext-BibTex ein und füllt die Felder des Dokuments entsprechend aus.

### Konfigurationsdialog

Plugins können eine Konfigurationsschnittstelle anbieten, die über den Einstellungsdialog aufgerufen werden kann. Der Konfigurationsknopf im Einstellungsdialog ist aktiviert, wenn das Plugin `referencer_config()` eine Funktion einschließt.

## Aktionen-Plugins

Drei Dinge sind zum Einfügen von Aktionen in die Benutzeroberfläche von Referencer notwendig: eine Beschreibung der Aktion, eine den Ort der Steuerelemente beschreibende Zeichenkette sowie eine Funktion, welche die Aktion implementiert.

Eine Aktion wird in einer Beschreibung mit den folgenden Feldern definiert:

### Aktionen

Feld | Beschreibung
--- | ---
name | Name des Autors oder durch Kommata getrennte Liste, z.B. "Hans Schmidt"
label | Eine Zeichenkette für die Version des Plugins, z.B. "1.3.2"
tooltip | Ausführliche Beschreibung
icon | Dateiname oder Stock-Name, z.B. »foo.png«, oder »_stock:gtk-edit«.
callback | Funktion der Aktion
sensitivity (optional) | Funktion zur Regelung der Empfindlichkeit
accelerator (optional) | Tastenkürzel, z.B. "<control><shift>q"

Die Definition einer Aktion könnte etwa so aussehen:

    action =
     {
       "name":"_plugin_genkey_genkey",
       "label":_("Generate Key"),
       "tooltip":_("Generate keys for the selected documents from their metadata"),
       "icon":"_stock:gtk-edit",
       "callback":"do_genkey",
       "sensitivity":"sensitivity_genkey",
       "accelerator":"<control>g"
     }

Das Plugin sollte auch eine Liste namens `referencer_plugin_actions` erzeugen, die alle Aktionen enthält:

    referencer_plugin_actions = [action]

Um die Aktionen in der Benutzeroberfläche zu platzieren, muss das Feld »ui« zur Beschreibung in `referencer_plugin_info` hinzugefügt werden. Der Wert von »ui« ist ein Stück GtkUIManager-XML. Dies legt Elemente der Benutzerschnittstelle als Kind-Elemente existierender Strukturen wie Menüs oder Werkzeugleisten fest. Die Eltern-Struktur wird als `src/referencer_ui.h` im Referencer-Quellcode definiert. Hier ein Beispiel für die Erzeugung von Menueinträgen im Menü Dokument und in der Werkzeugleiste:

    <ui>
     <menubar name='MenuBar'>
      <menu action='DocMenu'>
       <placeholder name='PluginDocMenuActions'>
         <menuitem action='_plugin_genkey_genkey'/>
       </placeholder>
      </menu>
     </menubar>
     <toolbar name='ToolBar'>
      <placeholder name='PluginToolBarActions'>
       <toolitem action='_plugin_genkey_genkey'/>
      </placeholder>
     </toolbar>
     <popup name='DocPopup'>
      <placeholder name='PluginDocPopupActions'>
       <menuitem action='_plugin_genkey_genkey'/>
      </placeholder>
     </popup>
    </ui>

Die als »callback« und »sensitivity« in der Aktionsbeschreibung referenzierten Funktionen haben beide den Prototypen `Meine_Funktion(Bibliothek, Dokumente)`, wobei Dokumente eine Liste für `referencer.document` ist und Bibliothek ungenutzt bleibt. Beispiel:

    def sensitivity_genkey (library, documents):
        pass

    def do_genkey (library, documents):
        pass

Einige Plugin-Aktionen erfordern die Anzeige zusätzlicher Elemente der Benutzeroberfläche wie beispielsweise Dialoge. Dies kann mittels PyGTK realisiert werden. Eine ausführliche Beschreibung von PyGTK würde den Rahmen dieses Dokuments sprengen. Es gibt zahlreiche Schritt-für-Schritt-Anleitungen zum Schreiben von PyGTK-Anwendungen. Beachten Sie, dass GTK bereits von Referencer initialisiert wird, daher muss sich ein Plugin nicht um die Initialisierung oder Finalisierung von GTK sorgen. Beispielsweise könnte der folgende Code vollständig allein stehen:

    import gobject
    import gtk
    dialog = gtk.Dialog (buttons=(
        gtk.STOCK_CANCEL, gtk.RESPONSE_REJECT,
        gtk.STOCK_OK, gtk.RESPONSE_ACCEPT))
    label = gtk.Label ("Hello World")
    dialog.vbox.pack_start (label)
    dialog.show_all ()
    response = dialog.run ()
    dialog.hide ()

Ein Beispiel eines Aktionen-Plugins finden Sie in der Datei `plugins/genkey.py` im Quellcode von Referencer.

## Metadaten-Plugins

Metadaten-Plugins stellen eine Funktion zum Ausfüllen der Metadaten-Felder eines Dokuments bereit, basierend auf dem Bezeichner des Dokuments.

Um anzugeben, welche Bezeichnerformate unterstützt werden, sollte das Plugin eine Liste von Zeichenketten namens `referencer_plugin_capabilities` erzeugen. Zum Zeitpunkt der Erstellung dieses Leitfadens sind folgende Werte möglich: »doi«, »pubmed« und »arxiv«.

Um die Suche auszuführen, sollte eine Funktion `resolve_metadata`(Dokument, Methode) erzeugt werden. Dokument ist das `referencer.document`, dessen Felder ausgefüllt werden sollen, und Methode ist eine der in `referencer_plugin_capabilities` aufgelisteten die Fähigkeiten beschreibenden Zeichenketten.

Ein Beispiel eines Metadaten-Plugins finden Sie in der Datei `plugins/pubmed.py` im Quellcode von Referencer.

## Info zu Referencer

Referencer und dieser Plugin-Leifaden wurden von John Spray (jcspray@icculus.org) geschrieben. Einige Beiträge zu diesem Handbuch kamen von Mario Blättermann (mariobl@gnome.org. Weitere Informationen über Referencer sowie die aktuellste Dokumentation finden Sie auf der Projekt-Website.

Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 2 der Lizenz oder (nach Ihrer Option) jeder späteren Version. Eine Kopie dieser Lizenz ist in dieser Dokumentation enthalten, eine weitere in der Datei COPYING, die im Quellcode dieses Programms enthalten ist.