<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY appversion "1.1.6">
<!ENTITY manrevision "1.1.6">
<!ENTITY date "June 2009">
<!ENTITY appname "Referencer">
<!ENTITY app "<application>&appname;</application>">
<!-- Information about the entities
       The legal.xml file contains legal information, there is no need to edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->]>
<article id="index" lang="de">
  <articleinfo>
    <title><application>Referencer</application> Plugin-Leitfaden V 1.1.6</title>
    <abstract role="description">
      <para>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.</para>
    </abstract>
    <copyright> 
      <year>2009</year> 
      <holder>John Spray</holder> 
    </copyright><copyright><year>2009</year><holder>Mario Blättermann (mariobl@gnome.org)</holder></copyright>
    <publisher> 
      <publishername> Referencer Development Team </publishername> 
    </publisher> 
      <legalnotice id="legalnotice">
	<para>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 <ulink type="help" url="ghelp:gpl">Link</ulink> oder in der mit diesem Handbuch gelieferten Datei COPYING.</para>
  </legalnotice>


    <authorgroup>
      <author role="maintainer">
	<firstname>John</firstname> <surname>Spray</surname>
	<affiliation>
	  <address>
	    <email>jcspray@icculus.org</email>
	  </address>
	</affiliation>
      </author> 
    </authorgroup>
    <revhistory>
      <revision>
	<revnumber>Referencer Plugin-Leitfaden V 1.1.6</revnumber>
	<date>18. Juni 2009</date>
	<revdescription>
	  <para role="author">John Spray</para>
	</revdescription>
      </revision>
    </revhistory>

    <releaseinfo>This is the Plugin Writing Guide version 1.1.6 of Referencer.
    </releaseinfo> 
      <legalnotice> 
      <title>Rückmeldungen</title> 
      <para>Um Fehler zu melden oder einen Vorschlag zur Anwendung <application>Referencer</application> oder zu diesem Handbuch zu machen, besuchen Sie bitte die </para>
      </legalnotice>
  </articleinfo>

  <sect1 id="intro">
    <title>Einführung</title>
	<para>Die Plugin-Schnittstelle von <application>Referencer</application> 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).</para>
	<para>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 <ulink url="http://icculus.org/referencer/contact.html" type="help">Mailingliste</ulink>.</para>
	<para>Dieses Dokument bezieht sich auf die Version 1.1.6 von <application>Referencer</application>.</para>
      </sect1>
      
  <sect1 id="referencer-installing-plugins">
    <title>Installieren von Plugins</title>
	<para>Plugins sind Python-Skripte. Diese müssen nicht ausführbar sein, jedoch ist die Dateiendung .py zwingend notwendig. Beim Start sucht <application>Referencer</application> an verschiedenen Orten nach Plugins: ./plugins, $PREFIX/lib/referencer, und ~/.referencer/plugins.</para>
  </sect1>
  <sect1>
    <title>Allgemeine API</title>
     <sect2>
	<title>Informative Beschreibung des Plugins</title>
	<para>Alle Plugins müssen eine Beschreibungsdatei im Dateiabschnitt <varname>referencer_plugin_info</varname> 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.</para>
	<para>
      <table frame="all" id="referencer-TBL-plugin">
	<title>Plugins</title>
	<tgroup cols="2" align="left" colsep="1" rowsep="1">
	  <thead>
	    <row>
	      <entry>Plugin-Name</entry>
	      <entry>Beschreibung</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>author</entry>
	      <entry>Name des Autors oder durch Kommata getrennte Liste, z.B. "Hans Schmidt"</entry>
	    </row>
	    <row>
	      <entry>version</entry>
	      <entry>Eine Zeichenkette für die Version des Plugins, z.B. "1.3.2"</entry>
	    </row>
	    <row>
	      <entry>longname</entry>
	      <entry>Der Zweck des Plugins, z.B. "Format author initials"</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </para>
	<para>Die Struktur der Plugin-Informationen könnte folgendermaßen definiert werden:</para>
	<programlisting>
	referencer_plugin_info =
	 {
	 "author":    "John Spray",
	 "version":   "1.1.2",
	"longname": _("Generate keys from metadata")
	}
	</programlisting>
     </sect2>
     <sect2>
	<title>Hilfsfunktionen</title>
	<para>Importieren Sie das Modul <varname>referencer</varname>, um auf folgende Funktionen zugreifen zu können:</para>
	<variablelist>
        <varlistentry>
          <term>referencer.download(<replaceable>Kurzbeschreibung, Langbeschreibung, Adresse</replaceable>)</term>
          <listitem>
            <para>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:</para>
	    <para>
	    	<programlisting>
referencer.download("Downloading tripe", "Downloading page from
slashdot.org", "http://www.slashdot.org")
		</programlisting>
	    </para>
	    <para>Um die Einfachheit zu gewährleisten, übernimmt diese Funktion die Proxy-Einstellungen von <application>gnome-vfs</application>, 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.</para>            
          </listitem>
        </varlistentry>
        
	<varlistentry>
          <term>referencer._(<replaceable>Text</replaceable>)</term>
          <listitem>
            <para>Ü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.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term>referencer.pref_get(<replaceable>Schlüssel</replaceable>)</term>
          <listitem>
            <para>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 <application>Referencer</application> gespeichert.</para>
          </listitem>
        </varlistentry>       

        <varlistentry>
          <term>referencer.pref_set(<replaceable>Schlüssel, Wert</replaceable>)</term>
          <listitem>
            <para>Setzt eine persistente Konfigurationszeichenkette.</para>
          </listitem>
        </varlistentry>
      </variablelist>
     </sect2>
     <sect2>
	<title>Die <varname>document</varname>-Klasse</title>
	<para><application>Referencer</application> präsentiert individuelle Dokumente über die document-Klasse. Eine begrenzte Anzahl von Getter/Setter-Methoden werden unterstützt:</para>
	<variablelist>

        <varlistentry>
          <term>get_field(<replaceable>Schlüssel</replaceable>)</term>
          <listitem>
            <para>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.</para>            
          </listitem>
        </varlistentry>
        
	<varlistentry>
          <term>set_field(<replaceable>Schlüssel, Wert</replaceable>)</term>
          <listitem>
            <para>Legt ein Feld fest.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term>get_key()</term>
          <listitem>
            <para>Holt den Schlüssel des Dokuments. Dies ist die Kennung, die der Benutzer zur Referenzierung eines Dokuments in einem Latex-Dokument verwendet.</para>
          </listitem>
        </varlistentry>       

        <varlistentry>
          <term>set_key(<replaceable>Wert</replaceable>)</term>
          <listitem>
            <para>Legt den Schlüssel fest.</para>
          </listitem>
        </varlistentry>

	<varlistentry>
          <term>get_filename()</term>
          <listitem>
            <para>Holt die Adresse (z.B. »file:///home/ich/Eine_Datei.pdf«) der einem Dokument zugeordneten Datei.</para>
          </listitem>
        </varlistentry>
 
	<varlistentry>
          <term>set_filename(<replaceable>Wert</replaceable>)</term>
          <listitem>
            <para>Setzt die Adresse des Dokuments auf <replaceable>Wert</replaceable>.</para>
          </listitem>
        </varlistentry>
 
	<varlistentry>
          <term>parse_bibtex(<replaceable>Wert</replaceable>)</term>
          <listitem>
            <para>Liest den Wert als Klartext-BibTex ein und füllt die Felder des Dokuments entsprechend aus.</para>
          </listitem>
        </varlistentry>
 
      </variablelist>
	
     </sect2>
     <sect2>
	<title>Konfigurationsdialog</title>
	<para>Plugins können eine Konfigurationsschnittstelle anbieten, die über den Einstellungsdialog aufgerufen werden kann. Der Konfigurationsknopf im Einstellungsdialog ist aktiviert, wenn das Plugin <varname>referencer_config()</varname> eine Funktion einschließt.</para>
	
     </sect2>
  </sect1>

  <sect1>
	<title>Aktionen-Plugins</title>
	<para>Drei Dinge sind zum Einfügen von Aktionen in die Benutzeroberfläche von <application>Referencer</application> notwendig: eine Beschreibung der Aktion, eine den Ort der Steuerelemente beschreibende Zeichenkette sowie eine Funktion, welche die Aktion implementiert.</para>
	<para>Eine Aktion wird in einer Beschreibung mit den folgenden Feldern definiert:</para>
	<para>
	<table frame="all" id="referencer-TBL-action-plugin">
	<title>Aktionen</title>
	<tgroup cols="2" align="left" colsep="1" rowsep="1">
	  <thead>
	    <row>
	      <entry>Feld</entry>
	      <entry>Beschreibung</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>name</entry>
	      <entry>Name des Autors oder durch Kommata getrennte Liste, z.B. "Hans Schmidt"</entry>
	    </row>
	    <row>
	      <entry>label</entry>
	      <entry>Eine Zeichenkette für die Version des Plugins, z.B. "1.3.2"</entry>
	    </row>
	    <row>
	      <entry>tooltip</entry>
	      <entry>Ausführliche Beschreibung</entry>
	    </row>
	    <row>
	      <entry>icon</entry>
	      <entry>Dateiname oder Stock-Name, z.B. »foo.png«, oder »_stock:gtk-edit«.</entry>
	    </row>
	    <row>
	      <entry>callback</entry>
	      <entry>Funktion der Aktion</entry>
	    </row>
	    <row>
	      <entry>sensitivity (optional)</entry>
	      <entry>Funktion zur Regelung der Empfindlichkeit</entry>
	    </row>
	    <row>
	      <entry>accelerator (optional)</entry>
	      <entry>Tastenkürzel, z.B. "<![CDATA[<control><shift>]]>q"</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
	</para>
	<para>Die Definition einer Aktion könnte etwa so aussehen:</para>
	<para>
	 <programlisting>
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":"<![CDATA[<control>]]>g"
 }
	 </programlisting>
	</para>
	<para>Das Plugin sollte auch eine  Liste namens <varname>referencer_plugin_actions</varname> erzeugen, die alle Aktionen enthält:</para>
	<para>
	 <programlisting>
referencer_plugin_actions = [action]
	 </programlisting>
	</para>
	<para>Um die Aktionen in der Benutzeroberfläche zu platzieren, muss das Feld »ui« zur Beschreibung in <varname>referencer_plugin_info</varname> 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 <filename>src/referencer_ui.h</filename> im <ulink url="http://hg.icculus.org/jcspray/referencer/file/tip/src/referencer_ui.h" type="help"><application>Referencer</application>-Quellcode</ulink> definiert. Hier ein Beispiel für die Erzeugung von Menueinträgen im Menü <guimenu>Dokument</guimenu> und in der Werkzeugleiste:</para>
	<para>
	 <programlisting><![CDATA[
<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>
	 ]]></programlisting>
	</para>
	<para>Die als »callback« und »sensitivity« in der Aktionsbeschreibung referenzierten Funktionen haben beide den Prototypen <varname><replaceable>Meine_Funktion</replaceable>(<replaceable>Bibliothek, Dokumente</replaceable>)</varname>, wobei <replaceable>Dokumente</replaceable> eine Liste für <varname>referencer.document</varname> ist und <replaceable>Bibliothek</replaceable> ungenutzt bleibt. Beispiel: <programlisting>
def sensitivity_genkey (library, documents):
    pass

def do_genkey (library, documents):
    pass
	 </programlisting></para>
	<para>Einige Plugin-Aktionen erfordern die Anzeige zusätzlicher Elemente der Benutzeroberfläche wie beispielsweise Dialoge. Dies kann mittels <application>PyGTK</application> realisiert werden. Eine ausführliche Beschreibung von <application>PyGTK</application> würde den Rahmen dieses Dokuments sprengen. Es gibt zahlreiche Schritt-für-Schritt-Anleitungen zum Schreiben von <application>PyGTK</application>-Anwendungen. Beachten Sie, dass <application>GTK</application> bereits von <application>Referencer</application> initialisiert wird, daher muss sich ein Plugin nicht um die Initialisierung oder Finalisierung von <application>GTK</application> sorgen. Beispielsweise könnte der folgende Code vollständig allein stehen:</para>
	<para>
	 <programlisting>
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 ()
	 </programlisting>
	</para>
	<para>Ein Beispiel eines Aktionen-Plugins finden Sie in der Datei <filename>plugins/genkey.py</filename> im <ulink url="http://hg.icculus.org/jcspray/referencer/file/tip/plugins/genkey.py" type="http"> Quellcode von <application>Referencer</application></ulink>.</para>
  </sect1>

  <sect1>
	<title>Metadaten-Plugins</title>
	<para>Metadaten-Plugins stellen eine Funktion zum Ausfüllen der Metadaten-Felder eines Dokuments bereit, basierend auf dem Bezeichner des Dokuments.</para>
	<para>Um anzugeben, welche Bezeichnerformate unterstützt werden, sollte das Plugin eine Liste von Zeichenketten namens <varname>referencer_plugin_capabilities</varname> erzeugen. Zum Zeitpunkt der Erstellung dieses Leitfadens sind folgende Werte möglich: »doi«, »pubmed« und »arxiv«.</para>
	<para>Um die Suche auszuführen, sollte eine Funktion <varname>resolve_metadata</varname>(<replaceable>Dokument, Methode</replaceable>) erzeugt werden. <replaceable>Dokument</replaceable> ist das <varname>referencer.document</varname>, dessen Felder ausgefüllt werden sollen, und <replaceable>Methode</replaceable> ist eine der in <varname>referencer_plugin_capabilities</varname> aufgelisteten die Fähigkeiten beschreibenden Zeichenketten.</para>
	<para>Ein Beispiel eines Metadaten-Plugins finden Sie in der Datei <filename>plugins/pubmed.py</filename> im <ulink url="http://hg.icculus.org/jcspray/referencer/file/tip/plugins/pubmed.py" type="http"> Quellcode von <application>Referencer</application></ulink>.</para>
  </sect1>

  <sect1 id="referencer-plugins-about">
    <title>Info zu <application>Referencer</application></title>

    <para><application>Referencer</application> und dieser Plugin-Leifaden wurden von John Spray (<email>jcspray@icculus.org</email>) geschrieben. Einige Beiträge zu diesem Handbuch kamen von Mario Blättermann (<email>mariobl@gnome.org</email>. Weitere Informationen über <application>Referencer</application> sowie die aktuellste Dokumentation finden Sie auf der <ulink url="http://icculus.org/referencer" type="http">Projekt-Website</ulink>.</para>
    <para>Dieses Programm ist freie Software. Sie können es unter den Bedingungen der <citetitle>GNU General Public License</citetitle>, 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 <ulink url="ghelp:gpl" type="help">Kopie dieser Lizenz</ulink> ist in dieser Dokumentation enthalten, eine weitere in der Datei COPYING, die im Quellcode dieses Programms enthalten ist.</para>
  </sect1>

</article>
