<chapter id="extending-quanta">
<title
>&quanta; erweitern</title>
<para
>Dieses Kapitel beschreibt, wie Sie &quanta; an Ihre Bedürfnisse anpassen können und wie Sie &quanta; helfen können, besser zu werden.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>
<title
>Erstellen Sie Ihre eignen Dokumentationen für &quanta;</title>
<para
>Vielleicht die beste Hinzufügung zu &quanta; für den normalen Benutzer ist die Möglichkeit, eine spezielle Dokumentation für die Skriptsprache oder die Formatierungssprache hinzuzufügen, die Sie am liebsten mögen. Deswegen beschreibt dieses Kapitel, wie ich einen PHP-Dokumentationsbaum für meine persönliche Nutzung erstelle.</para>
<para
>Bevor Sie Ihre eigene Dokumentation starten, könnten Sie mal in das <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta; Repository</ulink
> schauen, ob jemand das schon für Sie getan hat.</para>
<para
>Es gibt zwei Teile in diesem Prozess. Zuerst müssen Sie ein existierende Dokumentation für die Formatierungs-/Skriptsprache suchen. Dann müssen Sie die docrc-Datei erstellen. Den ersten Teil überlassen wir Ihnen, den zweiten behandeln wir hier.</para>

<para
>Die normale Form der docrc-Datei sieht so aus: <informalexample
> <literallayout>
#KDE Konfigurationsdatei
[Tree]
Doc dir=&lt;pfad, relativ zu dieser Datei, zu den Dokumentations-HTML-Dateien&gt; z.b. php42/
#Elemente im Hauptindex Top Element=&lt;Ihre Beschreibung für diese Dokumentationen
> z.B. PHP 4.2 Dokumentatino

Section 1=Section1.html
Section 2=#Sec2.1,#Sec2.2,#Sec2.3
Sec2.1=Sec2.1.html
Sec2.2=Sec2.2.html
Sec2.3=Sec2.3.html
...

[Context]
ContextList=func1,func2,tag1,tag2,tag3
func1=func1.html
func2=func2.html
tag1=tag1.html
tag2=tag2.html
tag3=tag3.html
</literallayout
> </informalexample
> Die docrc ist in zwei Teile geteilt: Tree und Context. </para>
<para
>Der Abschnitt "Tree" definiert den sichtbaren Teil der Dokumentation im Dokumentationsbaum. Zum Beispiel sehen Sie jetzt in den PHP Dokumentation so etwas:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para
><para
>Bezüglich dieses Bildes, sieht meine docrc so aus: <informalexample
> <literallayout
>#KDE Config File

[Tree]

Doc dir=php42/

#top level elements
Top Element=PHP 4.2 documentation

PHP 4.2 documentation=Table of Contents,#Getting Started,#Language Reference

Table of Contents=index.html

Getting Started=Introduction, ...
Introduction=introduction.html
...

Language Reference=Basic syntax, ...
Basic syntax=language.basic-syntax.html
...

</literallayout
> </informalexample
> Beachten Sie das # vor <quote
>Getting Started</quote
> und <quote
>Language Reference</quote
>. Das zeigt an, dass dies Unterbehälter sind und eigenen Inhalt haben. Ich glaube nicht, dass es hier eine Tiefenbegrenzung gibt.  </para>
<para
>Sie merken, dass das Inhaltsverzeichnis direkt auf eine Datei referenziert ist (und konsequenterweise am oberen Ende der Baumansicht angezeigt wird!).</para>
<important
> <para
>Leerzeichen beeinflussen nichts, aber schauen Sie nach &amp; und &lt; Zeichen. Diese sollten durch &amp;amp; und &amp;lt; in allen xml-basierten &quanta; Resourcendateien ersetzt werden.</para
> </important>
<para
>Der Abschnitt "Context" ist der Abschnitt der docrc-Datei wird benutzt, um kontextabhängige Hilfe zu bekommen. Wenn Sie zum Beispiel ein PHP Skript schreiben und Sie die Dokumentation zur Funktion mysql_fetch_array sehen wollen, wählen Sie die Funktion einfach aus und drücken <menuchoice
> <shortcut
> <keycombo action="simul"
>&Ctrl; <keycap
>H</keycap
> </keycombo
> </shortcut
> <guimenu
> </guimenu
></menuchoice
> für die Kontexthilfe. Sie sehen die Dokumentation zu mysql_fetch_array. Es gibt nur zwei Eintragstypen hier: die "ContextList" und die Dateizugehörigkeitszeilen. <variablelist
> <varlistentry
> <term
>ContextList</term
><listitem
> <para
>Sehr einfach, es ist einfach eine kommagetrennte Liste von den Kontexteinträgen, die Sie verfügbar haben wollen (für PHP sind diese die Funktionen). </para
></listitem
> </varlistentry
> <varlistentry
> <term
>Dateizugehörigkeitszeilen</term
> <listitem
><para
>Sie haben die Form "Kontexteintrag"=HTML-Doku-Datei, z.B. acos=function.acos.html</para
></listitem
> </varlistentry
> </variablelist
>. Eine gekürzte Versino meines Abschnitts "Context" ist hier: <informalexample
> <literallayout>
#Schlagwörter für die Kontexthilfe
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...

abs=function.abs.html
acos=function.acos.html
acosh=function.acosh.html
addcslashes=function.addcslashes.html
addslashes=function.addslashes.html
...
</literallayout
> </informalexample
> </para>
<para
>Nun können Sie Ihre docrc-Datei einfach speichern und zwar nach <filename class="directory"
>$<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
> oder <filename class="directory"
>$<envar
>KDEDIR</envar
>/share/apps/quanta/doc</filename
> für lokale bzw. globale Benutzung. Dann erstellen Sie ein Verzeichnis (das, das Sie in Ihrer docrc-Datei angegeben haben) im selben Verzeichnis und kopieren Ihre HTML-Dokumentation dorthin.</para>
<para
>Sie müssen &quanta; neu starten und sehen dann Ihre Dokumentationen.</para>
<para
>Wenn Sie sich sicher sind, dass Sie gut und es wert sind, geteilt zu werden, senden Sie Ihre docrc-Dateien mit einer Beschreibung von wichtigen Informationen, z.B. welche Dokumentation benutzt wurden an das <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta; Repository</ulink
> für die Benutzung von der &quanta;-Gemeinschaft. Sie werden davon nicht reich werden, aber Sie werden stolz darauf sein, bei der besten Webentwicklungsplattform mitgearbeitet zu haben.</para>

</sect1>

<sect1 id="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Aktionen in &quanta; erstellen</title>
<para
>Aktionen in &quanta; sind die Basis für alle Erweiterungen, die &quanta; hat und in der Zukunft haben wird. Derselbe Mechanismus der eine Aktion in &quanta; definiert, aktiviert die automatische Vervollständigung und Tag-Dialoge. Mit Aktionen sind Ihnen praktisch keine Grenzen gesetzt. Zum Beispiel benutzen wir <ulink url="http://www.w3c.org/People/Raggett/tidy/"
>html tidy</ulink
> auf unseren Webseiten.</para>

<para
>Lassen Sie uns beginnen: <menuchoice
><guimenu
>Einstellungen</guimenu
><guimenuitem
>Aktionen festlegen</guimenuitem
></menuchoice
> </para>
<para
> Wenn Sie den Aktionsdialog starten, sehen Sie dieses Fenster. Links befindet sich eine Liste der aktuell bekannten Aktionen. Sie können eine davon auswählen und dieselben Aktionen für eine existierende Aktion ausführen. </para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Wir erstellen eine neue Aktion, also lassen Sie uns auf den Knopf "Neu" (unten links) klicken und beginnen.</para>

<para
>Nun werden Sie mit einem leeren Satz von Einstellungen konfrontiert: <variablelist
> <varlistentry
> <term
>Text</term
> <listitem
><para
>Das ist der Name der Aktion</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Tool tip</term
> <listitem
><para
>Ich bin mir nicht sicher, wo das angezeigt wird. Es ist freiwillig!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Statustext</term
> <listitem
><para
> Ich weiß auch nicht wofür das ist. Es ist freiwillig!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Diese Aktion platzieren auf (Place this action onto)</term
> <listitem
><para
>Das aktiviert die Box, aus der Sie auswählen können, auf welche Werkzeugleiste die Aktion platziert weren soll. Wenn Sie nichts wählen, können Sie die Aktion später unter <menuchoice
><guimenu
>Einstellungen</guimenu
><guimenuitem
>Werkzeugleisten einrichten</guimenuitem
></menuchoice
> hinzufügen.</para
></listitem
> </varlistentry
> </variablelist
> Nachdem Sie diese grundlegenden Dinge ausgefüllt haben, können Sie ein Symbol für die Aktion auswählen, indem Sie auf den Symbolknopf links vom Feld "Text" klicken. </para>

<para
>Nun das wichtige der Aktion. Die Aktionsdefinition.</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Wenn wir ein Formatierungstag definieren, benutzen wir den Reiter "Tag", um die Parameter des Tags einzugeben.</para>
<para
> Dazu: <variablelist
> <varlistentry
> <term
>&lt;Formatierung
></term
> <listitem
><para
>Dort geben Sie den namen des Tags ein, wie es in Ihrem Dokument erscheinen soll. z.B. &lt;div align=center&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>&lt;/tag
></term
> <listitem
><para
>Hier geben Sie ein schließendes Tag ein, wenn es eines gibt. z.B. &lt;//div&gt;. Falls es keines gibt, lassen Sie die Box unangekreuzt.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Dialog <quote
>Tag bearbeiten</quote
> öffnen, falls verfügbar (Run <quote
>Edit Tag</quote
> dialog if available)</term
> <listitem
><para
>Das öffnet den Dialogeditor, falls eine Formatierungsdatei für diesen Eintrag existiert. Schauen Sie in den Abschnitt <link linkend="tag-files"
>Formatierungsdateien</link
> für weitere Informationen darüber.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Un nun... Zurück zu unserem Programmablauf. Machen wir weiter mit unserer html tidy Aktion.</para>
<para
>Klicken Sie auf den Reiter "Skript" um das folgende erscheinen zu lassen:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject
></para>
<para
> <variablelist
> <varlistentry
> <term
>Eingabebox oben</term
> <listitem
><para
>Dort geben Sie die gewünschte Anwendung an. In unserem Fall ist das /usr/local/bin/tidy, da ich dort tidy aufbewahre.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Nun zu den Seiten Eingabe/Ausgabe/Fehler.</para>
<para
><emphasis
>Reiter "Eingabe"</emphasis
> <variablelist
> <varlistentry
> <term
>Keine</term
> <listitem
><para
>Keine Eingabe für dieses Skript. Das kann nützlich sein, wenn wir ein Tcl/Tk-Skript starten, das ein Fenster für die Benutzerabfrage öffnet und dann die Ergebnisse zurückgibt. Wir werden für tidy etwas anderes wählen.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Markierter Text</term
> <listitem
><para
>Genau was drauf steht. Es gibt eine Kopie des aktuell ausgewählten Textes in die Standardeingabe des Skripts. Wir könnten das für tidy benutzen, aber es ist nicht lustig, alles in einem großen Dokument zu markieren.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Aktuelles Dokument</term
> <listitem
><para
>Schiebt den Inhalt der Editorversion der Datei durch die Standardeingabe des Skriptes. Das benutzen wir für tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Nun klicken Sie bitte auf den Reiter <emphasis
>Ausgabe</emphasis
>. Dort entscheiden wir, wo das Skript die Ausgabe hinschreibt. <variablelist
> <varlistentry
> <term
>Keine</term
> <listitem
><para
>Oh. Das wäre schön, wenn wir eine externe Anwendung starten, die nur eine Eingabe entgegennimmt und nichts ausgibt. Das ist keine Lösung für uns mit tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Einfügen an Cursor-Position</term
> <listitem
><para
>Genau was es sagt. Stellen Sie sicher, dass der Cursor genau da steht, wo der Text eingefügt werden soll.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Aktuelles Dokument ersetzen</term
> <listitem
><para
>Ersetzt die komplette Datei. Es wird nicht die Datei auf der Festplatte überschreiben aber es wird ihre aktuelle Sitzung vernichten. Benutzen Sie es mit Vorsicht. Wir werden es nicht für tidy benutzen.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Neues Dokument erstellen</term
> <listitem
><para
>Gibt die Ausgabe in ein neues Dokument aus. Das ist die beste Lösung für tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Nachrichtenfenster</term
> <listitem
><para
>Gibt die Ausgabe in das Nachrichtenfenster <menuchoice
><shortcut
><keycombo action="simul"
>&Ctrl; <keycap
>M</keycap
> </keycombo
></shortcut
><guimenu
></guimenu
></menuchoice
>. Das ist nützlich für die Fehlerbereinigung und den Reiter "Fehler", aber nicht für unsere Ausgabe.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
> Für Reiter "Fehler" sind die Einstellungen dieselben wie auf dem Reiter "Ausgabe". Normalerweise werden Sie das Nachrichtenfenster benutzen um Ihnen eine Hilfe zu geben oder die Einstellung "Keine".</para>
</sect1>
</chapter>

