<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [

  <!ENTITY kappname "&rocs;">
  <!ENTITY package "kdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % German "INCLUDE">
]>
<book lang="&language;">

<bookinfo>
<title
>Das Handbuch zu &rocs;</title>
<authorgroup>
<author
><personname
> <firstname
>Tomaz</firstname
> <surname
>Canabrava</surname
> </personname
> <email
>tomaz.canabrava@gmail.com</email
> </author>
<author
><personname
> <firstname
>Andreas</firstname
> <surname
>Cord-Landwehr</surname
> </personname
> <email
>cordlandwehr@googlemail.com</email
> </author>

<othercredit role="translator"
><firstname
>Burkhard</firstname
><surname
>Lück</surname
><affiliation
><address
><email
>lueck@hube-lueck.de</email
></address
></affiliation
><contrib
>Übersetzung</contrib
></othercredit
> 
</authorgroup>

<copyright
><year
>2009</year
><holder
>Tomaz Canabrava</holder
></copyright>
<copyright
><year
>2011</year
><holder
>Andreas Cord-Landwehr</holder
></copyright>

<date
>2011-12-04</date>
<releaseinfo
>1.1 &kde; 4.8</releaseinfo>

<legalnotice
>&FDLNotice;</legalnotice>

<abstract>
<para
>&rocs; ist ein Graphentheorie-Werkzeug für &kde;. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>Mathematik</keyword>
<keyword
>Mathe</keyword>
<keyword
>Graphen</keyword>
<keyword
>Knoten</keyword>
<keyword
>Kante</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Einführung</title>
<para
>&rocs; ist eine Entwicklungsumgebung für Graphen-Theorie für Alle, die an der Entwicklung und Analyse von Graphen-Algorithmen arbeiten, unter anderem:</para>
<itemizedlist>
	<listitem
><para
>Lehrer, die Ihren Studenten Algorithmen demonstrieren möchten,</para
></listitem>
	<listitem
><para
>Studenten, die verstehen und sehen möchten, wie ein Algorithmus funktioniert,</para
></listitem>
	<listitem
><para
>und für Alle, die Graphen-Algorithmen entwickeln und ein Werkzeug zum Testen von Prototypen brauchen.</para
></listitem>
</itemizedlist>
<para
>Für alle diese Benutzer stellt &rocs; einen einfach zu bedienenden grafischen Editor für die Erstellung von Graphen, ein leistungsfähiges Skriptmodul für Qt Script zur Ausführung von Algorithmen und mehrere Hilfswerkzeuge zur Einrichtung von Graphen und Datenstrukturen für Ihre Experimente bereit. Der normale Arbeitsablauf beginnt mit dem Schreiben eines Algorithmus, dann folgt die Erstellung eines Graphen. Jetzt können Sie in Echtzeit sehen, wie der Algorithmus mit diesem Graphen funktioniert.</para>

<screenshot>
<screeninfo
>Bildschirmphoto von &rocs;</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Bildschirmphoto von &rocs;</phrase>
</textobject>
</mediaobject>
</screenshot>
</chapter>

<chapter id="user-interface">
<title
>Die Benutzerschnittstelle von &rocs;</title>

<sect1 id="user-interface-all">
<title
>Standardelemente der Benutzeroberfläche</title>
<para
>Die Benutzerschnittstelle besteht aus mehreren logischen Teilen, die im folgenden Bildschirmfoto gezeigt werden. </para>
<screenshot>
	<screeninfo
>Bedienungselemente der &rocs;-Benutzeroberfläche</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="rocs-interfaces.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase
>Bedienungselemente der &rocs;-Benutzeroberfläche</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
	<term
>Werkzeugleiste für den visuellen Graphen-Editor</term>
	<listitem
><para
>Um Graphen im Zeichenfläche des visuellen Graphen-Editors zeichnen und bearbeiten zu können, müssen Sie zuerst ein Werkzeug auswählen.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Visueller Graphen-Editor</term>
	<listitem
><para
>Dies ist der Bereich, in dem Sie Ihre Graphen zeichnen können. Ein Klick mit der &RMB; auf die Zeichenfläche, ein Graphenelement oder ausgewählte Graphenelemente öffnet ein Kontextmenü mit passenden Aktionen für das Objekt.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Eigenschaften eines Graphen</term>
	<listitem
><para
>Hier wird eine vollständige Liste aller verschiedenen Graphen auf der Zeichenfläche angezeigt. Es kann &eg; der Name des Graphen, sichtbare Eigenschaften wie Namen oder Werte von Knoten geändert und die Standardfarbe der Elemente eines Graphen eingestellt werden.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Skripteditor</term>
	<listitem
><para
>In diesem Texteditor können Sie Algorithmen in Qt-Script schreiben, was sich für diese Anwendung im wesentlichen kaum von JavaScript unterscheidet. Sie können gleichzeitig an mehreren Algorithmen arbeiten, indem Sie neue Skript-Unterfenster mit <guimenuitem
>Neue Skriptdatei</guimenuitem
> im Menü <guimenu
>Projekt</guimenu
> verwenden. Enthält eine Karteikarte noch nicht gespeicherte Änderungen, dann wird ein kleines Diskettensymbol auf dem Karteireiter angezeigt.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Fehler- und Skriptausgabe</term>
	<listitem
><para
>In diesem Textfeld werden Fehlermeldungen oder Skriptausgaben Ihres Algorithmus angezeigt, abhängig von der gewählten Ausgabeeinstellung. Tritt ein Fehler in Ihrem Skript auf, wird automatisch die Fehlerausgabe gewählt. Zusätzlich werden in der Fehlerausgabe alle Meldungen des Programms angezeigt.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Skriptausführung</term>
	<listitem
><para
>In diesem Bereich können Sie die Ausführung der Algorithmen steuern. Mit dem Knopf <guibutton
>Ausführen</guibutton
> starten Sie den Algorithmus und führen das Skript aus, das gerade im Skripteditor für den Graphen auf der Zeichenfläche des visuellen Graphen-Editors geöffnet ist. Wird ein Skript ausgeführt, können Sie es mit <guibutton
>Anhalten</guibutton
> stoppen.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title
>Werkzeugleisten</title>
<para
>Es gibt mehrere verschiedene Werkzeugleisten für den visuellen Graphen-Editor, die den Zugriff auf alle Aktion mit einem Mausklick ermöglichen. In der Voreinstellung werden folgende Werkzeugleisten angezeigt:</para>
<itemizedlist>
	<listitem
><para
>Haupt-Werkzeugleiste</para
></listitem>
	<listitem
><para
>Layout-Werkzeugleiste</para
></listitem>
</itemizedlist>

<sect2 id="user-interface-toolbars-main">
<title
>Haupt-Werkzeugleiste</title>
<para
>Die <emphasis
>Haupt-Werkzeugleiste</emphasis
> enthält die im Folgenden genannten Aktionen. Klicken Sie auf den Knopf für eine Aktion, dann können Sie diese Aktion anschließend mit dem Mauszeiger auf die Elemente auf der Zeichenfläche anwenden.</para>
<itemizedlist>
<listitem
><para
><guilabel
>Verschieben</guilabel
>: Um Elemente auszuwählen, klicken Sie entweder mit der &LMBn; auf eine freie Stelle auf der Zeichenfläche, halten die Maustaste gedrückt und ziehen ein Rechteck um Knoten und/oder Kanten, um sie auszuwählen oder klicken Sie sonst zur Auswahl auf ein nicht ausgewähltes Element. Klicken Sie dann auf ein oder mehrere ausgewählte Elemente und verschieben sie mit gerückter Maustaste. Ausgewählte Element können auch mit den Pfeiltasten verschoben werden.</para
></listitem>
<listitem
><para
><guilabel
>Knoten hinzufügen</guilabel
>: Klicken Sie mit der &LMB; auf eine beliebige Position auf der Zeichenfläche, um einen neuen Knoten für den gerade ausgewählten Graphen zu erstellen.</para
></listitem>
<listitem
><para
><guilabel
>Kante hinzufügen</guilabel
>: Klicken Sie mit der &LMBn; auf einen Knoten, halten Sie die Maustaste gerückt und ziehen Sie eine Linie zu einem anderen Knoten. Diese Aktion kann nur dann ausgeführt werden, wenn beim aktuellen Graphen diese Kante hinzugefügt werden kann. In einem ungerichteten Graphen dürfen Sie &eg; nicht mehrere Kanten zwischen zwei Knoten einfügen.</para
></listitem>
<listitem
><para
><guilabel
>Löschen</guilabel
>: Klicken Sie auf ein Element, um es zu löschen. Löschen Sie einen Knoten, dann werden alle anliegenden Kanten ebenfalls gelöscht.</para
></listitem>
<listitem
><para
><guilabel
>Vergrößerung</guilabel
>: Klicken Sie auf die Zeichenfläche, halten Sie die &LMB; gedrückt und zeichnen Sie ein Rechteck. Die Zeichenfläche wird auf diesen gewählten Bereich vergrößert. Mit dem Mausrad können Sie die Ansicht ebenfalls vergrößern bzw. verkleinern. Doppelklicken mit der &LMBn; stellt die ursprüngliche Vergrößerung wieder her.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Die Haupt-Werkzeugleiste</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-main.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Die Haupt-Werkzeugleiste</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="user-interface-toolbars-alignment">
<title
>Layout-Werkzeugleiste</title>
<para
>Weiterhin gibt es noch die zusätzliche <emphasis
>Layout-Werkzeugleiste</emphasis
>. Drücken Sie einen Knopf in dieser Werkzeugleiste, dann wird die Aktion direkt an aktuell ausgewählten Knoten ausgeführt:</para>
<itemizedlist>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Oben</guilabel
>: Richtet die Knoten an der senkrechten Position des obersten Knotens aus. Die waagerechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Mittig</guilabel
>: Richtet die Knoten an der senkrechten Position aus, die durch die Mitte der senkrechten Positionen aller ausgewählten Knoten bestimmt wird. Die waagerechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Unten</guilabel
>: Richtet die Knoten an der senkrechten Position des untersten Knotens aus. Die waagerechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Links</guilabel
>: Richtet die Knoten an der waagerechten Position des linken Knotens aus. Die senkrechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Rechts</guilabel
>: Richtet die Knoten an der waagerechten Position des rechten Knotens aus. Die senkrechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Rechts</guilabel
>: Richtet die Knoten an der waagerechten Position des rechten Knotens aus. Die senkrechte Position bleibt unverändert.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Kreis</guilabel
>: Richtet die Knoten auf einem Kreis mit dem größten Abstand der Knoten als Durchmesser aus. Die Knoten werden in der Reihenfolge angeordnet, die sich aus der Sicht des Schwerpunkts der durch die Knoten gebildeten Fläche ergibt.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Kreuzende Kanten minimieren</guilabel
>: Verwendet den Fruchterman-Reingold-Algorithmus, um die Anzahl der kreuzenden Kanten annähernd zu minimieren.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Die Layout-Werkzeugleiste</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-alignment.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Die Layout-Werkzeugleiste</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="user-interface-graph-properties">
	<title
>Eigenschaften eines Graphen</title>
	<para
>Auf der linken Seite des Hauptfensters werden alle Einstellungen der geöffneten Graphen angezeigt. Diese Einstellungen gelten global für jeden Graphen. Die einzelnen Knoten und Kanten können in den Dialogen <guilabel
>Knoteneigenschaften</guilabel
> und <guilabel
>Kanteneigenschaften</guilabel
> geändert werden.</para>

	<itemizedlist>
	<listitem
><para
><guilabel
>Name</guilabel
>: Diesen Namen muss Ihr Algorithmus zum Zugriff auf den Graphen benutzen. </para
></listitem>
	<listitem
><para
><guilabel
>Datenfarbe</guilabel
> der neu erstellten Knoten. Um die Farbe für alle aktuellen Knoten zu ändern, wählen Sie den Knopf <guibutton
>Alle</guibutton
>. </para
></listitem>
	<listitem
><para>
	  <guilabel
>Zeigerfarbe</guilabel
> <!--FIXME color of edges?-->
	</para
></listitem>
	</itemizedlist>
	<para
>Die letzte Teil der Optionen besteht aus umschaltbaren Knöpfen:</para>
	<itemizedlist>
	<listitem
><para
><guilabel
>Namen anzeigen in:</guilabel
> <guilabel
>Daten</guilabel
> oder <guilabel
>Zeiger</guilabel
>. </para
></listitem>
	<listitem
><para
><guilabel
>Werte anzeigen in:</guilabel
> <guilabel
>Knoten</guilabel
> oder <guilabel
>Kanten</guilabel
>. </para
></listitem>
	<!-- FIXME missing Graph Type Undirected Graph, Directed Graph, Multigraph -->
	</itemizedlist>
</sect1>
</chapter>

<chapter id="using-rocs">
<title
>Arbeiten mit &rocs;</title>
<para
>Normalerweise erstellen Sie als erstes einen Graphen mit dem visuellen Editor. Den Graphen können Sie von Hand erstellen, indem Sie Knoten hinzufügen und sie verbinden. Alternativ können Sie einen der Hilfsalgorithmen aus dem Menu <menuchoice
><guimenu
>Extras</guimenu
> <guimenuitem
>Graphen erstellen</guimenuitem
></menuchoice
> verwenden. Mit <menuchoice
><guimenu
>Extras</guimenu
> <guimenuitem
>Werte zuweisen</guimenuitem
></menuchoice
> ist es möglich, den Knoten und Kanten eines Graphen Anfangswerte zuzuweisen. Zum Schluß müssen Sie für den Graphen einen Namen eingeben. Dieser Name dient als Bezeichner, der im Skriptmodul verwendet werden muss.</para>

<sect1 id="using-rocs-scripting">
<title
>Skriptunterstützung</title>
<para
>&rocs; benutzt eine Skriptsprache ähnlich wie JavaScript. Im Wesentlichen erfolgt die Definition von Variablen und Funktionen und deren Anwendung genauso wie in JavaScript. Zusätzlich bietet &rocs; weitere Funktionen, die den Zugriff auf den Graphen auf der Zeichenfläche und dessen Elemente ermöglicht. </para>

<sect2
><title
>Zugriff auf einen Graphen</title>
<para
>In der Skriptschnittstelle können Sie durch Angabe des Namens auf einen Graphen zugreifen und das dann als Objekt mit den folgenden Funktionen benutzen. Um auf einen Knoten oder Kante zuzugreifen, müssen Sie einen Bezeichner vom Graphen-Objekt ermitteln.</para>
<variablelist>
<varlistentry>
<term
>Graphenobjekte</term>
<listitem>
<programlisting
>// functions
     array list_nodes();
     array list_edges();
     node add_node(name);
     edge add_edge(from, to);
     node node_byname(QString&amp; name);
     node begin_node();
     array end_nodes();

// variables
     bool directed
     bool automate
     string name
     string nodeDefaultColor // in HEXA
     string edgeDefaultColor  // in HEXA
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Knotenobjekte</term>
<listitem>
<programlisting
>// functions
     array adj_nodes();
     array adj_edges();
     array input_edges();
     array output_edges();
     array loop_edges();
     array connected_edges(Node *n);
     void self_remove();

// variables
    double x
    double y
    double width
    string value
    string name
    string color  // in HEXA
    bool begin
    bool end
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Kantenobjekte</term>
<listitem>
<programlisting
>string color ( em hexa )
    string value
    string name
    double width
    string style ( dot, dash, dash dot, solid )

    node start();
    node  end();

    void self_remove();
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="script-graph-algorithms">
<title
>Graphen-Algorithmen</title>
<para
>Manchmal ist es nützlich, Funktionen für Standardaufgaben zu benutzen, wie zum Beispiel die Berechnung des kürzesten Wegs. Zurzeit stehen die folgenden Algorithmen zu Verfügung und können vom Skriptmodul mit Knoten aus demselben Graphen aufgerufen werden.</para>
<variablelist>
<varlistentry>
<term
>Berechnung des kürzesten Wegs</term>
<listitem>
	<para
>Berechnet den kürzesten Weg zwischen dem <emphasis
>Start</emphasis
>- und <emphasis
>Endknoten</emphasis
>. Beide Knoten müssen auf demselben Graphen liegen. Bei dieser Berechnung wird berücksichtigt, ob der Graph gerichtet oder ungerichtet ist.</para>
	<funcsynopsis>
	<funcprototype
><funcdef
>array <function
>dijkstra_shortest_path</function
></funcdef
> <paramdef
>Node* <parameter
><replaceable
>start</replaceable
></parameter
></paramdef
> <paramdef
>Node* <parameter
><replaceable
>end</replaceable
></parameter
></paramdef
> </funcprototype>
	</funcsynopsis>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="script-example">
<title
>Ein Beispiel</title>
<para
>Hier ist ein einfaches Beispielskript, das die Farben der ersten 4 Knoten im ersten Graphen festlegt:</para>
<programlisting
>/* Ein einfaches Beispiel, das die Farben der ersten 4 Knoten im ersten Graphen festlegt: */
 
var colors = new Array("red", "green", "blue", "yellow");

/* graphs ist ein Feld von Graphen, Zugriff auf einen Graph ist über den Index im
Feld oder über den Namen möglich. Wenn der erste Graph Untitled0 genannt wurde,
können Sie auf folgende Art auf den Graphen zugreifen  */
var list1= graphs[0].list_nodes();   //  Erste Form.
var list2=Untitled0.list_nodes();     // Zweite Form
 
 for ( var i = 0; i &lt; colors.length; i++){
        if (i 
> list2.length) break;
        list2[i].color = colors[i]
 }
</programlisting>
</sect1>
<sect1>
	<title
>Importieren und Exportieren</title>
	<para
>&rocs; unterstützt zurzeit den Import und Export folgender Dateiformate:</para>
	<itemizedlist>
		<listitem
><para
>DOT-Dateien, auch als Graphviz-Dateien bekannt.</para
></listitem>
		<listitem
><para
>GML-Dateien</para
></listitem>
		<listitem
><para
>Einfache Textdateien.</para
></listitem>
	</itemizedlist>
	<para
>Derzeit werden nur einige wenige Werte aus diesen Dateien importiert. Knoten und die zugehörigen Verbindungen, die Namen aller Elemente, Werte und, sofern angegeben, auch Koordinaten werden importiert.</para>
</sect1>
</chapter>

<chapter id="credits">
<title
>Danksagungen und Lizenz</title>

<para
>&rocs; </para>
<para
>Copyright für das Programm:</para>
<itemizedlist>
	<listitem
><para
>Copyright 2008 Ugo Sangiori (ugorox AT gmail.com)</para
></listitem>
	<listitem
><para
>Copyright 2008-2011 Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Copyright 2008-2011 Wagner Reck (wagner.reck AT gmail.com)</para
></listitem>
	<listitem
><para
>Copyright 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Copyright der Dokumentation:</para>
<itemizedlist>
	<listitem
><para
>Dokumentation Copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; </para
></listitem>
	<listitem
><para
>Dokumentation Copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Dokumentation copyright 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Übersetzung Burkhard Lück <email
>lueck@hube-lueck.de</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Installation</title>

<sect1 id="getting-rocs">
<title
>Wie Sie &rocs; erhalten</title>
&install.intro.documentation; </sect1>

<sect1 id="compilation">
<title
>Kompilierung und Installation</title>
&install.compile.documentation; </sect1>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->