[kde-doc-english] [rocs] doc: Major 1.9 handbook updated.
Andreas Cord-Landwehr
cordlandwehr at kde.org
Wed Jul 3 20:12:52 UTC 2013
Git commit 484b879c06b3e7f675c2c7ed56ff7b9d60d427bf by Andreas Cord-Landwehr.
Committed on 03/07/2013 at 20:11.
Pushed by cordlandwehr into branch 'master'.
Major 1.9 handbook updated.
The scripting API is updated in a semi-automated way (next time it
will be hopefully fully automated). Else, only copyright information
are updated.
R +0 -4 doc/apiConsole.docbook [from: doc/scripting-api.docbook - 095% similarity]
A +162 -0 doc/apiDatastructure.docbook
A +391 -0 doc/apiGraphstructure.docbook
A +141 -0 doc/apiLinkedListstructure.docbook
A +62 -0 doc/apiRootedTreestructure.docbook
A +82 -0 doc/chapterImportExport.docbook
M +31 -378 doc/index.docbook
http://commits.kde.org/rocs/484b879c06b3e7f675c2c7ed56ff7b9d60d427bf
diff --git a/doc/scripting-api.docbook b/doc/apiConsole.docbook
similarity index 95%
rename from doc/scripting-api.docbook
rename to doc/apiConsole.docbook
index fe79921..aea7e5b 100644
--- a/doc/scripting-api.docbook
+++ b/doc/apiConsole.docbook
@@ -1,6 +1,3 @@
-<chapter id="scripting-api">
-<title>The Scripting API</title>
-
<sect1 id="include-scripting-interface">
<title>Scripting Interfaces</title>
<sect2>
@@ -59,4 +56,3 @@ Console.debug("A debug message."); // print a debug message
</sect3>
</sect2>
</sect1>
-</chapter>
diff --git a/doc/apiDatastructure.docbook b/doc/apiDatastructure.docbook
new file mode 100644
index 0000000..1967365
--- /dev/null
+++ b/doc/apiDatastructure.docbook
@@ -0,0 +1,162 @@
+<sect1 id="scripting-data-structure">
+<title>Scripting API for every Data Structure</title>
+<sect2>
+<title>Abstract Data Structure Object</title>
+<para>
+The abstract data structure defines a set of data elements and possible connections between them, this is the prototype for every other data structure.
+Data structures are identified by their names.
+Assuming you created a data structure with name <literal>testgraph</literal>, then you can access the data structure simply by writing this identifier.
+For example, to get an array with all data elements in the given data structure, you can write <literal>testgraph.list_nodes();</literal> in the script.
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>name</emphasis> :
+ </para>
+ <para>The unique name of this data structure.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+</sect2>
+
+<sect2>
+<title>Abstract Data</title>
+<para>
+An abstract data element is a unit of information that belongs to an abstract data structure and possibly is connected to other data elements by pointers.
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>width</emphasis> :
+ </para>
+ <para>The size of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>x</emphasis> :
+ </para>
+ <para>The x-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>y</emphasis> :
+ </para>
+ <para>The y-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>id</emphasis> :
+ </para>
+ <para>The unique identifier of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>color</emphasis> :
+ </para>
+ <para>The color of this data element stated as hexadecimal value.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+</sect2>
+
+
+<sect2>
+<title>Abstract Pointer</title>
+<para>
+A pointer connects two data elements and can itself hold information by its properties.
+</para>
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>width</emphasis> :
+ </para>
+ <para>The width of the connection.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>directed</emphasis> :
+ </para>
+ <para>If true, the connection is directed. Otherwise is connection is undirected.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>from</emphasis> :
+ </para>
+ <para>Start of the connection.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>to</emphasis> :
+ </para>
+ <para>End of the connection</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>color</emphasis> :
+ </para>
+ <para>ID of the connection type.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+
+ <varlistentry>
+ <term>remove()</term>
+ <listitem>
+ <para>Remove this connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>remove()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>add_property(name, value)</term>
+ <listitem>
+ <para>Add a new property to the connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>add_property(name, value)</function></funcdef>
+ <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef>
+ <paramdef>string <parameter><replaceable>value</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>remove_property(name)</term>
+ <listitem>
+ <para>Remove an existing property from the connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>remove_property(name)</function></funcdef>
+ <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+
+</sect2>
+</sect1>
diff --git a/doc/apiGraphstructure.docbook b/doc/apiGraphstructure.docbook
new file mode 100644
index 0000000..cfc93b4
--- /dev/null
+++ b/doc/apiGraphstructure.docbook
@@ -0,0 +1,391 @@
+<sect1>
+<title>Scripting API for Graph Backend</title>
+
+<para>
+ The data structure properties dialog allows access to configure settings specific to the Graph backend.
+ There, with <guilabel>Graph Type</guilabel> you can select the type of the graph. The meaning of these types is as follows:
+</para>
+<itemizedlist>
+ <listitem><para>
+ <guilabel>Graph</guilabel>: Graph at which same edges (with respect to start and end points) may not exist multiple times.
+ </para></listitem>
+ <listitem><para>
+ <guilabel>Multigraph</guilabel>: Graph at which same edges (with respect to start and end points) may exist multiple times.
+ </para></listitem>
+</itemizedlist>
+
+<sect2>
+<title>Graph Data Structure</title>
+<para>
+A graph objects holds the information of a data structure of type "Graph".
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>name</emphasis> :
+ </para>
+ <para>The unique name of this data structure.</para>
+ </listitem>
+
+</itemizedlist>
+</sect3>
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+
+ <varlistentry>
+ <term>nodes()</term>
+ <listitem>
+ <para>Return list all nodes in the graph.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>nodes()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nodes(type)</term>
+ <listitem>
+ <para>Return list all nodes in the graph of specified type.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>nodes(type)</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edges()</term>
+ <listitem>
+ <para>Return list all edges in the graph.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>edges()</function></funcdef>
+
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edges(type)</term>
+ <listitem>
+ <para>Return list all edges in the graph of specified type.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>edges(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createNode(type)</term>
+ <listitem>
+ <para>Create a new node of the specified type and return the created node. If the type is not registered, no node is created.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>GraphNode <function>createNode(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createNode()</term>
+ <listitem>
+ <para>Create a new node of default type and return the created node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>GraphNode <function>createNode()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createEdge(from, to, type)</term>
+ <listitem>
+ <para>Create an edge from node "from" to node "to" of the specified type and return the created edge. If the type is not registered, no edge is created.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>GraphEdge <function>createEdge(from, to, type)</function></funcdef>
+ <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef>
+ <paramdef>GraphNode <parameter><replaceable>to</replaceable></parameter></paramdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createEdge(from, to)</term>
+ <listitem>
+ <para>Create an edge from node "from" to node "to" of default type and return the created edge.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>GraphEdge <function>createEdge(from, to)</function></funcdef>
+ <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef>
+ <paramdef>GraphNode <parameter><replaceable>to</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>distances(from)</term>
+ <listitem>
+ <para>Returns an array of shortest path lengths from this node to every other node in the graph.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>Array <function>distances(from)</function></funcdef>
+ <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+</sect2>
+
+<sect2>
+<title>Graph Node</title>
+<para>
+A node is the data element of a graph.
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>width</emphasis> :
+ </para>
+ <para>The size of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>x</emphasis> :
+ </para>
+ <para>The x-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>y</emphasis> :
+ </para>
+ <para>The y-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>id</emphasis> :
+ </para>
+ <para>The unique identifier of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>color</emphasis> :
+ </para>
+ <para>The color of this data element stated as hexadecimal value.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+
+ <varlistentry>
+ <term>neighbors()</term>
+ <listitem>
+ <para>Return list all nodes connected to this node. This method respects if edges are directed.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>neighbors()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edges()</term>
+ <listitem>
+ <para>Return a list of all edges (incoming and outgoing) of this node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>edges()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edges(type)</term>
+ <listitem>
+ <para>Return a list of all edges (incoming and outgoing) of this node of a specified type.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>edges(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>inEdges()</term>
+ <listitem>
+ <para>Return a list of incoming edges of this node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>inEdges()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>inEdges(type)</term>
+ <listitem>
+ <para>Return a list of all incoming edges of this node of a specified type.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>inEdges(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>outEdges()</term>
+ <listitem>
+ <para>Return a list of all outgoing edges of this node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>outEdges()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>outEdges(type)</term>
+ <listitem>
+ <para>Return a list of all outgoing edges of this node of a specified type.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>outEdges(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>edgesTo(target)</term>
+ <listitem>
+ <para>Return a list of all edges of this node to the specified node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>array <function>edgesTo(target)</function></funcdef>
+ <paramdef>GraphNode <parameter><replaceable>target</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+
+<sect2>
+<title>Graph Edge</title>
+<para>
+An Edge is the connection of two GraphNodes. Edges can be directed or undirected, depending on their type.
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>width</emphasis> :
+ </para>
+ <para>The width of the connection.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>directed</emphasis> :
+ </para>
+ <para>If true, the connection is directed. Otherwise is connection is undirected.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>from</emphasis> :
+ </para>
+ <para>Start of the connection.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>to</emphasis> :
+ </para>
+ <para>End of the connection</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>color</emphasis> :
+ </para>
+ <para>ID of the connection type.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+
+ <varlistentry>
+ <term>remove()</term>
+ <listitem>
+ <para>Remove this connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>remove()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>add_property(name, value)</term>
+ <listitem>
+ <para>Add a new property to the connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>add_property(name, value)</function></funcdef>
+ <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef>
+ <paramdef>string <parameter><replaceable>value</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>remove_property(name)</term>
+ <listitem>
+ <para>Remove an existing property from the connection.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>remove_property(name)</function></funcdef>
+ <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+</variablelist>
+</sect3>
+</sect2>
+
+</sect1>
diff --git a/doc/apiLinkedListstructure.docbook b/doc/apiLinkedListstructure.docbook
new file mode 100644
index 0000000..4320295
--- /dev/null
+++ b/doc/apiLinkedListstructure.docbook
@@ -0,0 +1,141 @@
+<sect1>
+<title>Scripting API for Linked List Backend</title>
+<sect2>
+<title>Linked List Data Structure</title>
+<para>
+A list objects holds the information of a data structure of type "Linked List".
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>name</emphasis> :
+ </para>
+ <para>The unique name of this data structure.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+
+ <varlistentry>
+ <term>head()</term>
+ <listitem>
+ <para>Return head node of the list.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>ListNode <function>head()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>setHead(node)</term>
+ <listitem>
+ <para>Set the head of the list.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>setHead(node)</function></funcdef>
+ <paramdef>ListNode <parameter><replaceable>node</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createNode(type)</term>
+ <listitem>
+ <para>Create a new node of the specified type and return the created node. If the type is not registered, no node is created.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>ListNode <function>createNode(type)</function></funcdef>
+ <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>createNode()</term>
+ <listitem>
+ <para>Create a new node of default type and return the created node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>ListNode <function>createNode()</function></funcdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+
+<sect2>
+<title>List Node</title>
+<para>
+A node is the data element of a linked list.
+</para>
+
+<sect3>
+<title>Properties</title>
+<itemizedlist>
+
+ <listitem>
+ <para>
+ <emphasis>width</emphasis> :
+ </para>
+ <para>The size of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>x</emphasis> :
+ </para>
+ <para>The x-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>y</emphasis> :
+ </para>
+ <para>The y-coordinate of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>id</emphasis> :
+ </para>
+ <para>The unique identifier of this data element.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>color</emphasis> :
+ </para>
+ <para>The color of this data element stated as hexadecimal value.</para>
+ </listitem>
+</itemizedlist>
+</sect3>
+
+
+<sect3>
+<title>Methods</title>
+<variablelist>
+ <varlistentry>
+ <term>pointTo(target)</term>
+ <listitem>
+ <para>Set pointer of this list node to the target node.</para>
+ <funcsynopsis><funcprototype>
+ <funcdef>void <function>pointTo(target)</function></funcdef>
+ <paramdef>ListNode <parameter><replaceable>target</replaceable></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+</sect1>
diff --git a/doc/apiRootedTreestructure.docbook b/doc/apiRootedTreestructure.docbook
new file mode 100644
index 0000000..957b5d6
--- /dev/null
+++ b/doc/apiRootedTreestructure.docbook
@@ -0,0 +1,62 @@
+<sect1 id="scripting-backend-rootedtree">
+<title>Scripting API for Rooted Tree Backend</title>
+<sect2>
+<title>Rooted Tree Data Structure</title>
+<para>
+ The data structure properties dialog allows access to configure settings specific to the Graph backend.
+ There, by checking the <guilabel>Show all pointers</guilabel> property, all pointers between the tree nodes are shown.
+ If unchecked, multiple pointers between same nodes are collapsed to one.
+</para>
+</sect2>
+
+<sect2>
+<title>The Rooted Tree Structure</title>
+<para>
+Given a data structure object of type "Rooted Tree", the following properties can be read or written:
+</para>
+<programlisting>
+ ShowAllPointers // set to true if show all edges, set to false if multiple edges shall be compressed
+</programlisting>
+<para>
+Given a data structure object of type "Rooted Tree", you can call the following member functions:
+</para>
+<programlisting>
+ node add_data(string name); // add a node to tree with given name
+ void set_root_node(node root); // set root as root node of the tree
+ node root_node(); // return root node of the tree
+</programlisting>
+</sect2>
+
+<sect2>
+<title>Rooted Tree Nodes</title>
+<para>
+Given a node object of type "Rooted Tree", the following properties can be read or written:
+</para>
+<programlisting>
+ int numberOfChilds // set the number of (allowed) children for this node
+ node left_child // read only: node that is the left child
+ node right_child // read only: node that is the right child
+ node node_parent // read only: node that is the parent
+</programlisting>
+<para>
+Given a node object of type "Rooted Tree", you can call the following member functions:
+</para>
+<programlisting>
+ node add_left_child(node child); // add left child
+ node add_right_child(node child); // add right child
+ node add_child(node child, int i); // add a child as the i-th child of the node
+ node add_node_parent(node child); // add parent (only successful if no parent set, yet)
+ node left_child(); // return right child
+ node right_child(); // return left child
+ node child_at(int i); // return the i-th child of the node
+ node node_parent(); // return the node's parent
+</programlisting>
+</sect2>
+
+<sect2>
+<title>Rooted Tree Edges</title>
+<para>
+Given edges of a data structure of type "Rooted Tree", only the properties of the base data structure are available.
+</para>
+</sect2>
+</sect1>
diff --git a/doc/chapterImportExport.docbook b/doc/chapterImportExport.docbook
new file mode 100644
index 0000000..bb940c5
--- /dev/null
+++ b/doc/chapterImportExport.docbook
@@ -0,0 +1,82 @@
+<title>Import and Export</title>
+<sect1 id="import-export-projects">
+ <title>Exchange &rocs; Projects</title>
+ <para>
+ &rocs; projects can be imported and exported as archived <literal>.tar.gz</literal> files.
+ These archives can be used to exchange projects.
+ Import and Export can be done with <menuchoice><guimenu>File</guimenu> <guimenuitem>Import Project</guimenuitem></menuchoice> and <menuchoice><guimenu>File</guimenu> <guimenuitem>Export Project</guimenuitem></menuchoice>, respectively.
+ </para>
+</sect1>
+
+<sect1 id="import-export-graphs">
+ <title>Import and Export of Graph Documents</title>
+ <para>&rocs; currently supports import and export of the following file formats:</para>
+ <itemizedlist>
+ <listitem><para>DOT files, also known as Graphviz files</para></listitem>
+ <listitem><para>GML files</para></listitem>
+ <listitem><para>Trivial Graph Format files</para></listitem>
+ </itemizedlist>
+
+<sect2 id="format-specification-tgf">
+<title>Trivial Graph File Format</title>
+<para>
+ The <emphasis>Trivial Graph Format</emphasis> (TGF) is a simple text-based file format for describing graphs.
+ A TGF file consists of a list of node definitions, that map the node IDs to labels, followed by a list of the edges.
+ In this format it is only possible to have one label per node and one value per edge.
+ &rocs; interprets imported graphs as undirected graphs.
+ Exported graphs will contain two edges per connection if connections are bidirectional.
+</para>
+
+<sect3>
+<title>Format Specification</title>
+ <itemizedlist>
+ <listitem><para>The file starts with a list of nodes (one node per line), followed by a line with the only character "#", followed by a list of edges (one edge per line).</para></listitem>
+ <listitem><para>A node consists of an integer (identifier), followed by a space, followed by an arbitrary string.</para></listitem>
+ <listitem><para>An edge consists of two integers (identifiers) separated by a space, followed by a space, followed by an arbitrary string. It is assumed that the directed edge points from the first identifier to the second identifier.</para></listitem>
+ </itemizedlist>
+</sect3>
+<sect3>
+<title>Example</title>
+<programlisting>
+1 starting node
+2 transmitter
+3 sink
+#
+1 2 blue
+2 1 red
+2 3 green
+</programlisting>
+</sect3>
+</sect2>
+
+<sect2 id="format-specification-dot">
+<title>DOT Language / Graphviz Graph File Format</title>
+<para>
+ The DOT language is a plain text graph description language that allows both,a good human readable representation of graphs as well as an efficient processing by graph layout programs.
+ DOT is the default file format for the Graphviz graph visualization suite, but is also widely used by other graph tools.
+ The usual file endings for DOT are <emphasis>.gv</emphasis> and <emphasis>.dot</emphasis>.
+</para>
+
+<sect3>
+<title>Unsupported Features</title>
+<para>
+ &rocs; can parse every graph file that contains a graph specified according to the DOT language specification<footnote><para>http://www.graphviz.org/content/dot-language</para></footnote>.
+ The support of language features is complete, despite of the following exceptions:
+</para>
+ <itemizedlist>
+ <listitem><para>subgraph: Due to the lack of a subgraph concept in &rocs;, subgraphs are only imported as a set of date elements and connections. Especially, connections to or from subgraphs are not imported.</para></listitem>
+ <listitem><para>&HTML; and &XML; attributes: Attributes (like labels) that contain &HTML; or &XML; syntax are read unchanged. Especially, not adjustment of fonts and styles are read from those attributes.</para></listitem>
+ </itemizedlist>
+</sect3>
+<sect3>
+<title>Example</title>
+<programlisting>
+digraph myGraph {
+ a -> b -> c;
+ b -> d;
+}
+</programlisting>
+</sect3>
+</sect2>
+
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index 706f571..e6e1b67 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -5,7 +5,14 @@
<!ENTITY package "kdeedu">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
- <!ENTITY scriptingapi SYSTEM "scripting-api.docbook">
+
+ <!ENTITY apiConsole SYSTEM "apiConsole.docbook">
+ <!ENTITY apiDatastructure SYSTEM "apiDatastructure.docbook">
+ <!ENTITY apiGraphstructure SYSTEM "apiGraphstructure.docbook">
+ <!ENTITY apiLinkedListstructure SYSTEM "apiLinkedListstructure.docbook">
+ <!ENTITY apiRootedTreestructure SYSTEM "apiRootedTreestructure.docbook">
+
+ <!ENTITY chapterImportExport SYSTEM "chapterImportExport.docbook">
]>
<book id="rocs" lang="&language;">
@@ -245,7 +252,7 @@ while (E.length > 0) {
}
}
}
-output("Vertex Cover contains " + C.length + " nodes.");
+Console.log("Vertex Cover contains " + C.length + " nodes.");
</programlisting>
</sect2>
@@ -496,6 +503,7 @@ The created data structure is added to the currently selected graph document.
</sect1>
</chapter>
+
<chapter id="scripting">
<title>Writing and Executing Algorithms in &rocs;</title>
@@ -511,299 +519,6 @@ It is important to know that changes done by the scripting engine are directly r
Hence, the scripts actually modify the data structures.
</para>
-<sect1 id="scripting-data-structure">
-<title>The Base Data Structure Elements</title>
-<para>
-Every backend provides a special set of functions and properties for its data structures and their elements.
-But also every backend provides the properties and functions that are defined for the base data structure.
-Hence, everything explained in this sections is available for every data structure backend.
-</para>
-<sect2><title>Base Data Structures Properties</title>
-<para>
-Data structures are identified by their names.
-Assuming you created a data structure with name <literal>testgraph</literal>, then you can access the data structure simply by writing this identifier.
-For example, to get an array with all data elements in the given data structure, you can write <literal>testgraph.list_nodes();</literal> in the script.
-</para>
-
-<sect3>
-<title>Base Data Structure Properties and Functions</title>
-<para>
-Each data structure <literal>testgraph</literal> has the following properties that can be read or written by <literal>testgraph.property</literal>:
-</para>
-<programlisting>
- string name // identification of the data structure
-</programlisting>
-</sect3>
-</sect2>
-
-<sect2>
-<title>Base Data Element Properties and Functions</title>
-<para>
-Each data element has the following properties that can be read or written:
-</para>
-<programlisting>
- double x // x coordinate of current position
- double y // y coordinate of current position
- double width // size
- string value // value
- int id // unique identifier for data element
- string name // name
- string color // color in HEXA
-</programlisting>
-<para>
-Further, every dynamic property of a data element can be accessed by its name.
-</para>
-
-<para>
-Each data element object provides the following methods:
-</para>
-<programlisting>
- int type(); // data type of data element
- int set_type(int); // set data type of the data element
- void add_property(string name, // add dynamic property to data element with specified name and value
- string value);
- array adj_data(); // list of adjacent data
- array adj_pointers(); // list of adjacent pointers
- array input_pointers(); // list of input pointers
- array output_pointers(); // list of output pointers
- array loop_pointers(); // list of pointers forming a self-loop
- array connected_pointers(target); // list of pointers pointing to 'target'
- void remove(); // remove this data element
-</programlisting>
-</sect2>
-
-<sect2>
-<title>Base Pointer Properties and Functions</title>
-<para>
-Each pointer has the following properties that can be read or written:
-</para>
-<programlisting>
- string color // color in HEXA
- string value // value
- string name // name
- double width // width
- string style // value out of: dot, dash, dash dot, solid
-</programlisting>
-<para>
-Further, every dynamic property of a pointer can be accessed by its name.
-</para>
-
-<para>
-Each pointer object provides the following methods:
-</para>
-<programlisting>
- int type(); // pointer type of pointer
- int set_type(int); // set pointer type of the pointer
- void add_property(string name, // add dynamic property to data element with specified name and value
- string value);
- node start(); // start node of the pointer
- node end(); // target node of the pointer
- void remove(); // remove this pointer
-</programlisting>
-</sect2>
-</sect1>
-
-<sect1 id="scripting-backend-graph">
-<title>The Graph Backend</title>
-<sect2>
-<title>Graph Properties and Functions</title>
-
-
-
-<sect3>
-<title>Graph Backend Specific Properties</title>
-<para>
- The data structure properties dialog allows access to configure settings specific to the Graph backend.
- There, with <guilabel>Graph Type</guilabel> you can select the type of the graph. The meaning of these types is as follows:
-</para>
-<itemizedlist>
- <listitem><para>
- <guilabel>Graph</guilabel>: Graph at which same edges (with respect to start and end points) may not exist multiple times.
- </para></listitem>
- <listitem><para>
- <guilabel>Multigraph</guilabel>: Graph at which same edges (with respect to start and end points) may exist multiple times.
- </para></listitem>
-</itemizedlist>
-</sect3>
-
-<sect3>
-<title>The Graph Structure</title>
-<para>
-Given a data structure object of type "Graph", you can call the following member functions:
-</para>
-<programlisting>
- array list_nodes(); // list of all nodes of the graph
- array list_nodes(int type); // list of all nodes of given type
- array list_edges(); // list of all edges of the graph
- array list_edges(int type); // list of all edges of given type
- node add_node(name); // add new node and returns it
- edge add_edge(node from, node to); // add new edge from 'from' to 'to' and returns it
- array overlay_edges(int overlayID); // list of all edges in given overlay
- edge add_overlay_edge(node from,
- node to,
- int overlayID); // add edge of given pointer type/in specified overlay
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Graph Nodes</title>
-<para>
-Given a data structure object of type "Graph", you can call the following member functions on the graph nodes additionally to the properties provided by the Data elements:
-</para>
-<programlisting>
- array adj_nodes(); // list of all adjacent nodes
- array adj_edges(); // list of connected edges
- array input_edges(); // list of input edges
- array output_edges(); // list of all output edges
- array loop_edges(); // list of all edges looping to the node
- array connected_edges(node target); // all edges that connect this node with node 'target'
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Graph Edges</title>
-<para>
-Given edges of a data structure of type "Graph", only the properties of the base data structure are available.
-</para>
-</sect3>
-</sect2>
-
-<sect2>
-<title>Graph Structure Algorithms</title>
-<para>
-The graph backend provides some special functions that can be used from the scripting engine.</para>
-<variablelist>
-<varlistentry>
-<term>Shortest Path Computation</term>
-<listitem>
- <para>Compute the shortest path between the nodes <emphasis>start</emphasis> and <emphasis>end</emphasis>. Both nodes must be of the same graph. This computation respects if the graph is directed or undirected.</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>
-<varlistentry>
-<term>Shortest Path Distances</term>
-<listitem>
- <para>Compute the shortest path distances from node <emphasis>start</emphasis> to all other nodes of the graph. This computation respects if the graph is directed or undirected.</para>
- <funcsynopsis>
- <funcprototype>
- <funcdef>array <function>distances</function></funcdef>
- <paramdef>node <parameter><replaceable>start</replaceable></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
-</listitem>
-</varlistentry>
-</variablelist>
-</sect2>
-</sect1>
-
-<sect1 id="scripting-backend-linkedlist">
-<title>The Linked List Backend</title>
-<sect2>
-<title>Linked List Properties and Functions</title>
-
-<sect3>
-<title>The Linked List Structure</title>
-<para>
-Given a data structure object of type "Linked List", you can call the following member functions:
-</para>
-<programlisting>
- node begin(); // gives the head node of the linked list
- setBegin(node begin): // set node begin as begin of list and rearrange list
- createNode(); // create a new list node
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Linked List Nodes</title>
-<para>
-Given a data structure object of type "Linked List", you can call the following member functions on the graph nodes additionally to the properties provided by the Data elements:
-</para>
-<programlisting>
- node front(); // returns the node's predecessor
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Linked List Edges</title>
-<para>
-Given edges of a data structure of type "Linked List", only the properties of the base data structure are available.
-</para>
-</sect3>
-</sect2>
-</sect1>
-
-<sect1 id="scripting-backend-rootedtree">
-<title>The Rooted Tree Backend</title>
-<sect2>
-<title>Rooted Tree Properties and Functions</title>
-
-<sect3>
-<title>Rooted Tree Backend</title>
-<para>
- The data structure properties dialog allows access to configure settings specific to the Graph backend.
- There, by checking the <guilabel>Show all pointers</guilabel> property, all pointers between the tree nodes are shown.
- If unchecked, multiple pointers between same nodes are collapsed to one.
-</para>
-</sect3>
-
-<sect3>
-<title>The Rooted Tree Structure</title>
-<para>
-Given a data structure object of type "Rooted Tree", the following properties can be read or written:
-</para>
-<programlisting>
- ShowAllPointers // set to true if show all edges, set to false if multiple edges shall be compressed
-</programlisting>
-<para>
-Given a data structure object of type "Rooted Tree", you can call the following member functions:
-</para>
-<programlisting>
- node add_data(string name); // add a node to tree with given name
- void set_root_node(node root); // set root as root node of the tree
- node root_node(); // return root node of the tree
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Rooted Tree Nodes</title>
-<para>
-Given a node object of type "Rooted Tree", the following properties can be read or written:
-</para>
-<programlisting>
- int numberOfChilds // set the number of (allowed) children for this node
- node left_child // read only: node that is the left child
- node right_child // read only: node that is the right child
- node node_parent // read only: node that is the parent
-</programlisting>
-<para>
-Given a node object of type "Rooted Tree", you can call the following member functions:
-</para>
-<programlisting>
- node add_left_child(node child); // add left child
- node add_right_child(node child); // add right child
- node add_child(node child, int i); // add a child as the i-th child of the node
- node add_node_parent(node child); // add parent (only successful if no parent set, yet)
- node left_child(); // return right child
- node right_child(); // return left child
- node child_at(int i); // return the i-th child of the node
- node node_parent(); // return the node's parent
-</programlisting>
-</sect3>
-
-<sect3>
-<title>Rooted Tree Edges</title>
-<para>
-Given edges of a data structure of type "Rooted Tree", only the properties of the base data structure are available.
-</para>
-</sect3>
-</sect2>
-</sect1>
<sect1 id="scripting-controls">
<title>Controlling the Script Execution</title>
@@ -834,8 +549,8 @@ Given edges of a data structure of type "Rooted Tree", only the properties of th
You can control the text that is displayed at the script output by the following functions:
</para>
<programlisting>
- output(string message); // displays the message as script output
- debug(string message); // displays the message as debug output
+ Console.log(string message); // displays the message as script output
+ Console.debug(string message); // displays the message as debug output
</programlisting>
</sect2>
@@ -877,92 +592,30 @@ Given edges of a data structure of type "Rooted Tree", only the properties of th
</sect1>
</chapter>
-<chapter id="import-export">
-<title>Import and Export</title>
-<sect1 id="import-export-projects">
- <title>Exchange &rocs; Projects</title>
- <para>
- &rocs; projects can be imported and exported as archived <literal>.tar.gz</literal> files.
- These archives can be used to exchange projects.
- Import and Export can be done with <menuchoice><guimenu>File</guimenu> <guimenuitem>Import Project</guimenuitem></menuchoice> and <menuchoice><guimenu>File</guimenu> <guimenuitem>Export Project</guimenuitem></menuchoice>, respectively.
- </para>
-</sect1>
-<sect1 id="import-export-graphs">
- <title>Import and Export of Graph Documents</title>
- <para>&rocs; currently supports import and export of the following file formats:</para>
- <itemizedlist>
- <listitem><para>DOT files, also known as Graphviz files</para></listitem>
- <listitem><para>GML files</para></listitem>
- <listitem><para>Trivial Graph Format files</para></listitem>
- </itemizedlist>
-
-<sect2 id="format-specification-tgf">
-<title>Trivial Graph File Format</title>
-<para>
- The <emphasis>Trivial Graph Format</emphasis> (TGF) is a simple text-based file format for describing graphs.
- A TGF file consists of a list of node definitions, that map the node IDs to labels, followed by a list of the edges.
- In this format it is only possible to have one label per node and one value per edge.
- &rocs; interprets imported graphs as undirected graphs.
- Exported graphs will contain two edges per connection if connections are bidirectional.
-</para>
-
-<sect3>
-<title>Format Specification</title>
- <itemizedlist>
- <listitem><para>The file starts with a list of nodes (one node per line), followed by a line with the only character "#", followed by a list of edges (one edge per line).</para></listitem>
- <listitem><para>A node consists of an integer (identifier), followed by a space, followed by an arbitrary string.</para></listitem>
- <listitem><para>An edge consists of two integers (identifiers) separated by a space, followed by a space, followed by an arbitrary string. It is assumed that the directed edge points from the first identifier to the second identifier.</para></listitem>
- </itemizedlist>
-</sect3>
-<sect3>
-<title>Example</title>
-<programlisting>
-1 starting node
-2 transmitter
-3 sink
-#
-1 2 blue
-2 1 red
-2 3 green
-</programlisting>
-</sect3>
-</sect2>
-
-<sect2 id="format-specification-dot">
-<title>DOT Language / Graphviz Graph File Format</title>
+<chapter id="scripting-API">
+<title>Scripting Engine API</title>
<para>
- The DOT language is a plain text graph description language that allows both,a good human readable representation of graphs as well as an efficient processing by graph layout programs.
- DOT is the default file format for the Graphviz graph visualization suite, but is also widely used by other graph tools.
- The usual file endings for DOT are <emphasis>.gv</emphasis> and <emphasis>.dot</emphasis>.
+Every backend provides a special set of functions and properties for its data structures and their elements.
+But also every backend provides the properties and functions that are defined for the base data structure.
</para>
-<sect3>
-<title>Unsupported Features</title>
-<para>
- &rocs; can parse every graph file that contains a graph specified according to the DOT language specification<footnote><para>http://www.graphviz.org/content/dot-language</para></footnote>.
- The support of language features is complete, despite of the following exceptions:
-</para>
- <itemizedlist>
- <listitem><para>subgraph: Due to the lack of a subgraph concept in &rocs;, subgraphs are only imported as a set of date elements and connections. Especially, connections to or from subgraphs are not imported.</para></listitem>
- <listitem><para>&HTML; and &XML; attributes: Attributes (like labels) that contain &HTML; or &XML; syntax are read unchanged. Especially, not adjustment of fonts and styles are read from those attributes.</para></listitem>
- </itemizedlist>
-</sect3>
-<sect3>
-<title>Example</title>
-<programlisting>
-digraph myGraph {
- a -> b -> c;
- b -> d;
-}
-</programlisting>
-</sect3>
-</sect2>
+&apiDatastructure;
-</sect1>
+&apiGraphstructure;
+
+&apiLinkedListstructure;
+
+&apiRootedTreestructure;
+
+&apiConsole;
+</chapter>
+
+
+<chapter id="import-export">
+&chapterImportExport;
</chapter>
-&scriptingapi; <!--Scripting Interface API Documentation-->
<chapter id="credits">
<title>Credits and License</title>
@@ -975,14 +628,14 @@ digraph myGraph {
<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-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem>
+ <listitem><para>Copyright 2011-2013 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-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem>
+ <listitem><para>Documentation copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)</para></listitem>
</itemizedlist>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
More information about the kde-doc-english
mailing list