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

  <!ENTITY kappname "&rocs;">
  <!ENTITY package "rocs">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">

  <!ENTITY apiConsole SYSTEM "apiConsole.docbook">
  <!ENTITY apiDatastructure SYSTEM "apiDatastructure.docbook">
  <!ENTITY apiGraphstructure SYSTEM "apiGraphstructure.docbook">

  <!ENTITY chapterImportExport SYSTEM "chapterImportExport.docbook">
]>
<book id="rocs" lang="&language;">

<bookinfo>
<title>The &rocs; Handbook</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@kde.org</email>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2015-03-13</date>
<releaseinfo>2.0.0 &kde; 15.04</releaseinfo>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>
&rocs; is a graph theory tool for &kde;.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>mathematics</keyword>
<keyword>math</keyword>
<keyword>graphs</keyword>
<keyword>node</keyword>
<keyword>edge</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>
This chapter provides an overview of the core features and the typical workflows.
The most important parts are <xref linkend="introduction-nutshell"/> and <xref linkend="scripting" />, which together should allow every new user to directly start using &rocs;.
</para>

<sect1 id="introduction-goals">
<title>Goals, Target Audience, and Workflows</title>
<para>&rocs; is a Graph Theory Tool for everybody interested in designing and studying graph algorithms. In particular, those are</para>
<itemizedlist>
    <listitem><para>lecturers, who want to demonstrate algorithms to their students,</para></listitem>
    <listitem><para>students and researchers, who want to see how their algorithm perform, and</para></listitem>
    <listitem><para>everybody who is interested in data structures and algorithms.</para></listitem>
</itemizedlist>
<para>For all them, &rocs; provides an easy to use graphical editor for creating graphs, a powerful scripting engine to execute algorithms, and several helper tools for simulations, experiments, and graph exports.
The typical way of using &rocs; is to create a graph, either by hand (i.e., dragging nodes and edges to the whiteboard), or by using one of the graph generators.
Graph algorithms then can be implemented and executed on the created graph and all changes, which the algorithm performs, are visible immediately in the graph editor.
</para>

<screenshot>
<screeninfo>A Screenshot of &rocs;.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG" />
</imageobject>
<textobject>
<phrase>A Screenshot of &rocs;.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect1>

<sect1 id="introduction-nutshell">
<title>&rocs; in a Nutshell</title>
<para>
Every &rocs; session is a project: when opening &rocs; an empty project is created, when loading some project it becomes the current project.
Hereby, a project itself consists of <emphasis>graph documents</emphasis>, <emphasis>scripts/algorithms</emphasis>, and a <emphasis>journal</emphasis>.
</para>

<sect2>
<title>Graph Documents</title>
<para>
A graph document represents the content of a whiteboard in the graph editor.
It contains information about the user defined node and edge types, their properties, and about the already created nodes and edges.
This is, &rocs; understands the set of all nodes and edges of a graph document to form a (not necessarily connected) graph.
Everything belonging to a graph document is accessible by the script engine via the global object
<userinput><command>Document</command></userinput>.
</para>
</sect2>

<sect2>
<title>Edge Types</title>
<para>
In some scenarios, graphs consist of different types of edges (e.g., an undirected graph plus the tree edges computed by a breadh-first-search algorithm) that shall be handled and displayed differently.
For this, besides a default edge type, you can define arbitrary other edge types.
Each edge type has its individual visual representation, dynamic properties, and can be set to be either undirected or directed.
The scripting interface provides convenience methods to specifically access only edges of specific types.
</para>
</sect2>

<sect2>
<title>Node Types</title>
<para>
Analog to edge types, you can define different types of nodes of a graph (e.g., to give some nodes special roles).
Each node type has its own visual representation and dynamic properties.
</para>
</sect2>

<sect2>
<title>Properties</title>
<para>
Every (node or edge) element can have properties.
Those properties must be setup at the corresponding node or edge type.
Properties are identified and accessed by their names and can contain any value.
To create new or change existing properties, use the <guilabel>Element Types</guilabel> sidebar and use the
<inlinemediaobject><imageobject><imagedata fileref="hi22-action-rocsproperties.png" format="PNG"/>
</imageobject></inlinemediaobject><guibutton>Properties</guibutton>
button to open the property dialog.
</para>
<para>
You can also use the scripting engine to access registered properties and change their values.
In the following example we assume that the property "weight" is registered for the default edge type.
<programlisting>
var nodes = Document.nodes()
for (var i = 0; i &lt; nodes.length; ++i){
    nodes[i].weight = i;
}
for (var i = 0; i &lt; nodes.length; ++i){
    Console.log("weight of node " + i + ": " + nodes[i].weight);
}
</programlisting>
</para>
</sect2>
</sect1>

<sect1 id="introduction-tutorial">
<title>Tutorial</title>
<para>
In this section we want to create an example project to explore some of the most important functions of &rocs;.
The goal is to create a graph and a script that illustrates a simple 2-approximate algorithm for the <emphasis>minimum vertex cover</emphasis> problem.
The minimum vertex cover problem is the problem to find a subset of graph nodes C of minimal size such that each graph edge is connected to at least one node in C.
This problem is known to be NP-hard and we want to illustrate how to find an approximation of factor 2 by computing a matching in the given graph.
</para>
<para>
Our goal is to visualize the relationship of the matching and the minimum vertex cover.
For this, we want to specify two edge types, one to display matching edges and one type to display "ordinary" edges, as well as two node types that we use to distinguish nodes contained in C and those not contained in C.
</para>

<sect2>
<title>Generating the Graph</title>
<para>
For creating the graph, we use a default graph generator provided by &rocs;.
This can be found in the main menu at <menuchoice><guimenu>Graph Document</guimenu> <guisubmenu>Tools</guisubmenu> <guimenuitem>Generate Graph</guimenuitem></menuchoice>.
There, we select a <guilabel>Random Graph</guilabel> with 30 nodes, 90 edges, and with seed 1 (the seed is the starting seed for the random graph generator; using the same seed multiple times results in same and reproducible graphs).
</para>
</sect2>

<sect2>
<title>Creating the Element Types</title>
<para>
We use the <guilabel>Element Types</guilabel> and create a second node type as well as a second edge type.
For both new types we open the the properties dialog by using the respective <guibutton>Properties</guibutton> buttons and set the IDs to <literal>2</literal>.
Furthermore, we change the colors of elements of these two new types (to distinguish them from the default types).
Finally, we set all edge types to be bidirectional, and the IDs of the default types to <literal>1</literal>.
</para>
</sect2>

<sect2>
<title>The Algorithm</title>
<para>
At last we have to implement the approximation algorithm. For this we use the following implementation:
</para>
<programlisting>
for (var i=0; i &lt; Document.nodes.length; i++) {
    Document.nodes[i].type = 1;
}
for (var i=0; i &lt; Document.edges.length; i++) {
    Document.edges[i].type = 1;
}

var E = Document.edges(); // set of unprocessed edges
var C = new Array();      // matching edges
while (E.length > 0) {
    var e = E[0];         // we take first edge e={u,v}
    var u = e.from();
    var v = e.to();
    e.type = 2;           // set edge to be a matching edge
    E.shift();            // remove e (i.e., E[0]) from edge list
    C.push(u);            // add u to C
    C.push(v);            // add v to C

    // mark u,v as nodes in C
    u.type = 2;
    v.type = 2;

    // remove from E all edges incident to u or v
    var adjacent = u.edges();
    for (var i=0; i &lt; adjacent.length; i++) {
        var index = E.indexOf(adjacent[i]); // find the index
        if (index != -1) {
            E.splice(index, 1); // remove it if really found
        }
    }
    var adjacent = v.edges();
    for (var i=0; i &lt; adjacent.length; i++) {
        var index = E.indexOf(adjacent[i]); // find the index
        if (index != -1) {
            E.splice(index, 1); // remove it if really found
        }
    }
}
Console.log("Vertex Cover contains " + C.length + " nodes.");
</programlisting>
</sect2>

<sect2>
<title>Execute the Algorithm</title>
<para>
The algorithm can be executed by the <guibutton>Run</guibutton> button at the script control panel.
</para>
</sect2>
</sect1>
</chapter>

<chapter id="user-interface">
<title>The &rocs; User Interface</title>

<sect1 id="user-interface-all">
<title>Main Elements of the User Interface</title>
<para>
The user interface is divided into several logical parts as presented at the screenshot below.
</para>
<screenshot>
    <screeninfo>&GUI; elements of the &rocs; interface.</screeninfo>
    <mediaobject>
    <imageobject>
    <imagedata fileref="rocs-interfaces.png" format="PNG" />
    </imageobject>
    <textobject>
    <phrase>&GUI; elements of the &rocs; interface.</phrase>
    </textobject>
    </mediaobject>
</screenshot>
<variablelist>
<varlistentry>
    <term>Graph Editor</term>
    <listitem><para>
    The editor provides a whiteboard at that nodes and edges can be placed.
    Double-clicking at any of its elements opens a corresponding property menu.
    You can use the tools from the <emphasis>Graph Editor Toolbar</emphasis> to create and modify graphs.</para></listitem>
</varlistentry>
<varlistentry>
    <term>Graph Editor Toolbar</term>
    <listitem><para>
    The toolbar provides the <inlinemediaobject><imageobject><imagedata fileref="hi22-actions-rocsnode.png" format="PNG"/></imageobject>
    </inlinemediaobject><guibutton>Create Node</guibutton> or <inlinemediaobject><imageobject><imagedata fileref="hi22-actions-rocsedge.png"
    format="PNG"/></imageobject></inlinemediaobject><guibutton>Create Edge</guibutton> tools, for creating new elements on the whiteboard.
    Note the extra-toolbar for selecting the respective node or edge type that becomes visible of one of these tools is selected.
    Also tools for selecting and moving as well as deleting elements are available here.
    For details see <xref linkend="user-interface-toolbars" />.
    </para></listitem>
</varlistentry>
<varlistentry>
    <term>Side Bar</term>
    <listitem><para>
        At the right, you can find the side bar that provides several tools for your workflow:
        <itemizedlist>
        <listitem><para>Element Types: This widget gives you direct access to the available edge and node types.</para></listitem>
        <listitem><para>Journal: Each project has its own journal that can be used to, &eg; note tasks, results, or observations.</para></listitem>
        <listitem><para>Handbook: To get direct access to the handbook and by this to the script documentation, you can open this widget.</para></listitem>
        <listitem><para>Scripting API: To get direct access to the script documentation, you can open this widget.</para></listitem>
        </itemizedlist>
    </para></listitem>
</varlistentry>
<varlistentry>
    <term>Script Editor</term>
    <listitem><para>
        In this text editor you can write algorithms as explained in detail in <xref linkend="scripting" />.
        You can work on several script documents simultaneously by using several tabs.
        The disk symbol at a tab appears if the script contains unsaved changes.
    </para></listitem>
</varlistentry>
<varlistentry>
    <term>Script Output</term>
    <listitem><para>
        This text area either shows debug information or the script output of your algorithm, depending on the toggled setting at the top of this widget.
        If the script throws an error, automatically the debug output is presented.
    </para></listitem>
</varlistentry>
<varlistentry>
    <term>Controls</term>
    <listitem><para>
        Here you can find the controls for executing scripts.
        You can execute the script that is currently open at the script editor by pressing <guiicon>Run</guiicon>.
        While the script is executed, it is possible to stop execution by pressing the <guiicon>Stop</guiicon> button.
    </para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title>Toolbars</title>
<para>There are different toolbars for the graph editor that allow you to access features by only one click. Per default, the following toolbars are shown:</para>
<itemizedlist>
    <listitem><para>Main Toolbar</para></listitem>
<!--     <listitem><para>Alignment Toolbar</para></listitem> -->
</itemizedlist>
<!--  -->
<sect2 id="user-interface-toolbars-main">
<title>Main Toolbar</title>
<para>The <emphasis>Main Toolbar</emphasis> consists of the following actions. Clicking at an action means that your mouse pointer applies this action at the graph editor whiteboard:</para>
<itemizedlist>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-actions-rocsselectmove.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Select and Move</guilabel>: To select elements, either click at unused space at the whiteboard, keep the mouse pressed and draw a rectangle that contains some data elements and/or edges to select these elements or otherwise directly click at an unselected element to select this element. If you click at a selected element or a set of selected elements, respectively, by keeping the mouse pressed and moving around you can move these elements. Moving selected elements is also possible with the arrow keys.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-actions-rocsnode.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Create Node</guilabel>: Click at an arbitrary position at the graph editor whiteboard to create a new data element that belongs to the currently selected data structure.
By keeping the mouse pointer pressed at the button, a menu shows up at which the data type of the new created data elements can be selected (only if different data types exist).</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-actions-rocsedge.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Create Edge</guilabel>: Click at one data element, keep the mouse pressed and draw a line to another data element to which the edge shall point. This action is only successful if the current graph allows to add this edge (&eg;, in an undirected graph you are not allowed to add multiple edges between two data elements). By keeping the mouse pointer pressed at the button, a menu shows up at which the edge type of the new created edges can be selected (only if different edge types exist).</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-actions-rocsdelete.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Delete</guilabel>: Click at an element to delete it. If you delete a node, all adjacent edges are also deleted.</para></listitem>
</itemizedlist>
</sect2>

<!--<sect2 id="user-interface-toolbars-alignment">
<title>Alignment Toolbar</title>
<para>You can add the optional <emphasis>Alignment Toolbar</emphasis>. Pressing an action at this toolbar has direct effect to the currently selected nodes:</para>
<itemizedlist>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Top</guilabel>: Align the data elements at the vertical position of the top-most data element. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Center</guilabel>: Align the data elements at the vertical position given by the center of all selected data elements vertical positions. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Base</guilabel>: Align the data elements at the vertical position of the bottom-most data element. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Left</guilabel>: Align the data elements at the horizontal position of the left-most data element. This only affects the horizontal positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Center</guilabel>: Align the data elements at the horizontal position of the top-most data element. This only affects the horizontal
positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Right</guilabel>: Align the data elements at the horizontal position of the right-most data element. This only affects the horizontal positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Circle</guilabel>: Aligns the data elements at a circle of diameter equals to the maximal distance of the data elements. The data elements are positioned in the same sequence as given by view from the center of gravity of these data elements.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Minimize Crossing Edges</guilabel>: Rearrange the selected data elements to minimize the number of crossing connections (application of the Fruchterman-Reingold algorithm).</para></listitem>
</itemizedlist>
</sect2>-->
</sect1>
</chapter>


<chapter id="scripting">
<title>Executing Algorithms in &rocs;</title>
<para>
&rocs; internally uses the QtScript Java Script engine
This means, all algorithms that you implement must use Java Script.
In the following, we explain how to access and change elements of a graph document from the scripting engine.
It is important to note that changes done by the scripting engine are directly reflected at the properties at the graph editor elements.
</para>

<sect1 id="scripting-controls">
<title>Control Script Execution</title>
<para>
    There are different execution modes for your algorithms:
</para>
<itemizedlist>
    <listitem><para>
        <inlinemediaobject><imageobject>
        <imagedata fileref="hi22-actions-controls-run.png" format="PNG"/></imageobject>
        </inlinemediaobject>
        <guilabel>Run</guilabel>: Execute the script until it finishes.</para></listitem>
<!--TODO not available right now -->
<!--    <listitem><para>
        <inlinemediaobject><imageobject>
        <imagedata fileref="rocs-control-engine-step.png" format="PNG"/></imageobject>
        </inlinemediaobject>
        <guilabel>One Step</guilabel>: Execute script until one step ends. A step ends when the script calls the function <literal>interrupt()</literal>:</para>
    <programlisting>
        interrupt();    // ends a step
    </programlisting>
    </listitem>
    <listitem><para>
        <inlinemediaobject><imageobject>
        <imagedata fileref="rocs-control-engine-debug.png" format="PNG"/></imageobject>
        </inlinemediaobject>
        <guilabel>Debug</guilabel>: Execute script in debug mode. This opens the QtScript debug dialog.</para></listitem>-->
    <listitem><para>
        <inlinemediaobject><imageobject>
        <imagedata fileref="hi22-actions-control-stop.png" format="PNG"/></imageobject>
        </inlinemediaobject>
        <guilabel>Stop</guilabel>: Stop script execution (only available while a script is executed).</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="scripting-output">
<title>Script Output</title>
<para>
    During the execution of an algorithm, debug and program output is displayed in the <emphasis>Debug &amp; Script Output</emphasis>.
    If the scripting engine detects a syntax error in your script, the error is also displayed as debug message.
    Note that all program messages are also displayed at the debug output (displayed as bold text).
</para>
<para>
    You can control the text that is displayed at the script output by the following functions:
</para>
<programlisting>
    Console.log(string message);            // displays the message as script output
    Console.debug(string message);          // displays the message as debug output
    Console.error(string message);          // displays the message as error output
</programlisting>
</sect1>

<sect1 id="scripting-API">
<title>Scripting Engine API</title>
<para>
The different parts of &rocs; each provide a static element that can be accessed by the scripting engine.
These are:
<itemizedlist>
    <listitem><para><userinput><command>Document</command></userinput> for the graph document</para></listitem>
    <listitem><para><userinput><command>Console</command></userinput> for the console log output</para></listitem>
</itemizedlist>
For the explicit API use and for a method reference, please see the inline help at the &rocs; side bar.
</para>
</sect1>
</chapter>


&chapterImportExport;


<chapter id="credits">
<title>Credits and License</title>

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

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

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;               <!-- FDL: do not remove -->
&underGPL;               <!-- GPL License -->

</chapter>

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

<sect1 id="getting-rocs">
<title>How to obtain &rocs;</title>

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and 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:
-->
