<?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 % Russian "INCLUDE">
]>
<book lang="&language;">

<bookinfo>
<title
>Руководство &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
>Алексей</firstname
><surname
>Субач</surname
><affiliation
><address
><email
>alexey.subach@gmail.com</email
></address
></affiliation
><contrib
>Перевод на русский</contrib
></othercredit
> 
</authorgroup>

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

<date
>04.12.2011</date>
<releaseinfo
>1.1 &kde; 4.8</releaseinfo>

<legalnotice
>&FDLNotice;</legalnotice>

<abstract>
<para
>&rocs; — это инструмент KDE для работы с теорией графов. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>математика</keyword>
<keyword
>граф</keyword>
<keyword
>графы</keyword>
<keyword
>вершина</keyword>
<keyword
>ребро</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Введение</title>
<para
>&rocs; — это среда для работы с графами для любого, кто заинтересован в разработке и анализе алгоритмов, основанных на графах. Она подойдет для</para>
<itemizedlist>
	<listitem
><para
>лекторов, которые хотят продемонстрировать алгоритмы своим студентам,</para
></listitem>
	<listitem
><para
>студентов, которые хотят понять и увидеть как работает какой-либо алгоритм,</para
></listitem>
	<listitem
><para
>и каждого, кто хочет разработать алгоритм, связанный с теорией графов, и нуждается в инструменте для тестирования.</para
></listitem>
</itemizedlist>
<para
>Для всех этих пользователей &rocs; предоставляет легкий в использовании инструмент для создания и редактирования графов, мощный скриптовой движок Qt Script для выполнения алгоритмов, и несколько вспомогательных инструментов для создания графов и структур данных для любых экспериментов. Так что обычная последовательность действий включает в себя написание алгоритма, создание графа, и наблюдение в реальном времени как алгоритм работает на конкретном примере.</para>

<screenshot>
<screeninfo
>Снимок окна &rocs;.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Снимок окна &rocs;.</phrase>
</textobject>
</mediaobject>
</screenshot>
</chapter>

<chapter id="user-interface">
<title
>Интерфейс &rocs;</title>

<sect1 id="user-interface-all">
<title
>Общие части интерфейса</title>
<para
>Пользовательский интерфейс разделен на несколько логических частей как показано на снимке окна ниже. </para>
<screenshot>
	<screeninfo
>Элементы интерфейса &rocs;</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="rocs-interfaces.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase
>Элементы интерфейса &rocs;</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
	<term
>Панель инструментов визуального редактора графов</term>
	<listitem
><para
>чтобы иметь возможность рисовать или редактировать графы на белой панели визуального редактора графов, сначала вам нужно выбрать инструмент здесь</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Визуальный редактор графов</term>
	<listitem
><para
>Это рабочая панель, где вы можете рисовать графы. Нажмите правой кнопкой на белой поверхности, элементах графа или выбранных элементах графа, и откроется нужное контекстное меню.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Свойства графа</term>
	<listitem
><para
>Вам предоставляется полный список всех графов, открытых в визуальном редакторе. Вы можете изменить, имя графа, его видимые свойства, такие как имена и значения узлов. Также вы можете изменить цвета элементов графа, и многое другое.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Редактор скриптов</term>
	<listitem
><para
>В этом текстовом редакторе вы можете писать алгоритмы на скриптовом языке Qt Script (его синтаксис точно такой же, как JavaScript). Вы можете работать над несколькими алгоритмами одновременно, открывая или создавая вкладки с новыми скриптами в главном меню. Если текущие изменения в скрипте не сохранены, на вкладке появится небольшой значок диска.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Отладочная информация и выходные данные скрипта</term>
	<listitem
><para
>Это текстовое поле выводит отладочную информацию или выходные данные вашего скрипта, в зависимости от параметров. Если в скрипте происходит ошибка, автоматически выбирается вывод отладочной информации. Далее, в текстовое поле записываются также выходные сообщения скрипта.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Выполнение скриптов</term>
	<listitem
><para
>Эта зона контролирует выполнение скриптов. Вы можете выполнить скрипт, который в данный момент открыт в редакторе скриптов на графе, который в текущий момент открыт в визуальном редакторе графов нажатием кнопки <guiicon
>Запустить</guiicon
>. Во время выполнения скрипта можно его остановить нажатием кнопки <guiicon
>Стоп</guiicon
>.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title
>Панели инструментов</title>
<para
>Есть несколько панелей инструментов для визуального редактора графов, которые позволяют делать то,  что вам нужно всего в один клик. По умолчанию показываются следующие панели инструментов:</para>
<itemizedlist>
	<listitem
><para
>Главная панель инструментов</para
></listitem>
	<listitem
><para
>Панель выравниванияr</para
></listitem>
</itemizedlist>

<sect2 id="user-interface-toolbars-main">
<title
>Главная панель инструментов</title>
<para
><emphasis
>Главная панель инструментов</emphasis
> состоит из следующих действий. Выбор любого из них подразумевает, что последующее нажатие мышью на панель визуального редактирования применит выбранное действие на текущий граф:</para>
<itemizedlist>
<listitem
><para
><guilabel
>Переместить</guilabel
>: Чтобы выбрать элементы, кликните на неиспользуемом пространстве, удерживайте левую кнопку мыши нажатой и нарисуйте прямоугольник, который будет содержать нужные узлы и ребра, или просто кликните на невыбранный элемент, чтобы выбрать его. Если вы кликните по уже выбранному элементу или набору выбранных элементов, продолжая удерживать левую кнопку мыши нажатой и двигая курсор вы переместите элементы. Также перемещение выбранных элементов возможно при помощи стрелок на клавиатуре.</para
></listitem>
<listitem
><para
><guilabel
>Добавить вершину</guilabel
>: Кликните на произвольное место в визуальном редакторе, чтобы создать новый узел, который будет принадлежать текущему графу.</para
></listitem>
<listitem
><para
><guilabel
>Добавить ребро</guilabel
>: Кликните на один узел, удерживайте левую кнопку мыши нажатой и проведите линию к другому узлу, к которому данное ребро будет вести. Действие произойдет только если добавление данного ребра в текущий граф возможно (например, в неориентированном графе нельзя добавлять несколько ребер между узлами).</para
></listitem>
<listitem
><para
><guilabel
>Удалить</guilabel
>: Кликните на элемент, чтобы удалить его. Если вы удаляете узел, все смежные ребра будут также удалены.</para
></listitem>
<listitem
><para
><guilabel
>Масштаб</guilabel
>: Кликните на рабочее пространство, и, удерживая левую кнопку мыши нажатой, нарисуйте прямоугольник. Выбранная область рабочего пространства будет увеличена. Для масштабирования также можно использовать колесико мышки. Двойной щелчок левой кнопкой мыши восстановит масштаб по умолчанию.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Главная панель инструментов.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-main.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Главная панель инструментов.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="user-interface-toolbars-alignment">
<title
>Панель выравнивания</title>
<para
>Вы можете добавить <emphasis
>Панель выравнивания</emphasis
>. Нажатие на любую кнопку этой панели незамедлительно воздействует на выбранные узлы:</para>
<itemizedlist>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Вверх</guilabel
>: Выравнивание узлов на вертикальную позицию самого верхнего из выбранных.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>По центру</guilabel
>: Центрирование вертикальной позиции выбранных узлов. Вертикальная позиция выбранных узлов усреднится.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Вниз</guilabel
>: Выравнивание узлов на вертикальную позицию самого нижнего из выбранных.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Влево</guilabel
>: Выравнивание узлов на горизонтальную позицию самого левого из выбранных.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Центр</guilabel
>: Центрирование горизонтальной позиции выбранных узлов. Горизонтальная позиция выбранных узлов усреднится.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Вправо</guilabel
>: Выравнивание узлов на горизонтальную позицию самого правого из выбранных.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>По кругу</guilabel
>: Выравнивание узлов по кругу, диаметр которого равен максимальному расстоянию среди выбранных узлов. Узлы будут расположены также, как они расположены относительно их центра масс.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Минимизировать количество пересекающихся рёбер</guilabel
>: Применяется алгоритм Fruchterman-Reingold для минимизации числа пересекающихся ребер.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Панель выравнивания.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-alignment.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Панель выравнивания.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="user-interface-graph-properties">
	<title
>Свойства графа</title>
	<para
>Слева вы можете настроить каждый открытый граф. Все настройки являются глобальными для каждого графа, а чтобы настроить конкретный узел или конкретное ребро, используйте диалоги Свойства Ребра и Свойства Узла.</para>

	<itemizedlist>
	<listitem
><para
><guilabel
>Имя</guilabel
>: Имя, по которому ваш алгоритм будет иметь доступ к графу. </para
></listitem>
	<listitem
><para
><guilabel
>Цвет данных</guilabel
> для вновь созданных узлов. Вы можете поменять цвет всех узлов, нажав кнопку <guilabel
>Все</guilabel
> </para
></listitem>
	<listitem
><para>
	  <guilabel
>Цвет указателей</guilabel
> <!--FIXME color of edges?-->
	</para
></listitem>
	</itemizedlist>
	<para
>Последний ряд настроек состоит из переключаемых кнопок:</para>
	<itemizedlist>
	<listitem
><para
><guilabel
>Показывать имена на:</guilabel
> <guilabel
>Данных</guilabel
> или <guilabel
>Указателях</guilabel
>. </para
></listitem>
	<listitem
><para
><guilabel
>Показывать значения на:</guilabel
> <guilabel
>Вершинах</guilabel
> или <guilabel
>Ребрах</guilabel
>. </para
></listitem>
	<!-- FIXME missing Graph Type Undirected Graph, Directed Graph, Multigraph -->
	</itemizedlist>
</sect1>
</chapter>

<chapter id="using-rocs">
<title
>Использование &rocs;</title>
<para
>Обычно первый шаг — это создать граф с помощью визуального редактора. Вы можете это сделать либо вручную, добавляю новые узлы и соединяя их ребрами, либо используя один из вспомогательных алгоритмов, которые могут быть найдены в  <menuchoice
><guimenu
>Инструменты</guimenu
> <guimenuitem
>Генерирование графа</guimenuitem
></menuchoice
>. Возможно, вы также захотите использовать <menuchoice
><guimenu
>Инструменты</guimenu
> <guimenuitem
>Сопоставить значения</guimenuitem
></menuchoice
> для сопоставления начальных значений узлам и ребрам графа. В конце, вы должны дать графу имя. Имя будет идентификатором, который вы в дальнейшем будете использовать для доступа к графе через скриптовой движок.</para>

<sect1 id="using-rocs-scripting">
<title
>Написание скриптов</title>
<para
>&rocs; в качестве скриптового языка использует язык, похожий на JavaScript. Создание переменных и функций и их использование реализованы точно так же, как в JavaScript. Сверх того, &rocs; предоставляет функции, позволяющие вам иметь доступ к открытым графам и их элементам. </para>

<sect2
><title
>Доступ к графу</title>
<para
>При написании скрипта вы можете обращаться к графу просто введя его имя, и используя его как объект со следующими функциями. Чтобы обратиться к узлу или ребру, вы должны получить их идентификатор от объекта графа</para>
<variablelist>
<varlistentry>
<term
>Объекты графа</term>
<listitem>
<programlisting
>// функции
     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();

// переменные
     bool directed
     bool automate
     string name
     string nodeDefaultColor // в шестнадцатеричной системе счисления
     string edgeDefaultColor  // в шестнадцатеричной системе счисления
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Объекты узлов</term>
<listitem>
<programlisting
>// функции
     array adj_nodes();
     array adj_edges();
     array input_edges();
     array output_edges();
     array loop_edges();
     array connected_edges(Node *n);
     void self_remove();

// переменные
    double x
    double y
    double width
    string value
    string name
    string color  // в шестнадцатеричном формате
    bool begin
    bool end
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Объекты ребер</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
>Алгоритмы на графах</title>
<para
>Иногда удобно использовать функции для стандартных задач теории графов, вроде нахождения кратчайшего пути между двумя вершинами. На данный момент мы поддерживаем следующие алгоритмы, которые могут быть вызваны из скрипта.</para>
<variablelist>
<varlistentry>
<term
>Вычисление кратчайшего пути</term>
<listitem>
	<para
>Находит кратчайший путь между вершинами <emphasis
>start</emphasis
> и <emphasis
>end</emphasis
>. Обе вершины должны принадлежать одному графу. Алгоритм работает на ориентированных и неориентированных графах.</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
>Пример</title>
<para
>Здесь приведен простой пример скрипта, который задает цвета первых четырех узлов первого графа:</para>
<programlisting
>/* пример скрипта, который задает цвета первых 
четырех узлов первого графа: */

var colors = new Array("red", "green", "blue", "yellow");

/* graphs — это массив графов, вы можете обращаться к графу по его индексу
в массиве или просто по его имени, так что если имя первого графа — Untitled0, следующие
строки верны  */
var list1= graphs[0].list_nodes(); //  1-й вариант.
var list2=Untitled0.list_nodes();              // 2-й вариант

 for ( var i = 0; i &lt; colors.length; i++){
        if (i 
> list2.length) break;
        list2[i].color = colors[i]
 }
</programlisting>
</sect1>
<sect1>
	<title
>Импорт и экспорт</title>
	<para
>&rocs; на данный момент поддерживает импорт и экспорт в следующих файловых форматах:</para>
	<itemizedlist>
		<listitem
><para
>DOT файлы</para
></listitem>
		<listitem
><para
>GML файлы</para
></listitem>
		<listitem
><para
>Текстовые файлы</para
></listitem>
	</itemizedlist>
	<para
>Для большинства файловых типов экспортируется только несколько составных частей графа. Они включают узлы и ребра, имена всех элементов, их значения и координаты, если таковые заданы.</para>
</sect1>
</chapter>

<chapter id="credits">
<title
>Авторские права и лицензия</title>

<para
>&rocs; </para>
<para
>Авторские права:</para>
<itemizedlist>
	<listitem
><para
>©  Ugo Sangiori, 2008 (ugorox@gmail.com)</para
></listitem>
	<listitem
><para
>© Tomaz Canabrava, 2008-2011 (tcanabrava@ kde.org)</para
></listitem>
	<listitem
><para
>© Wagner Reck, 2008-2011 (wagner.reck@gmail.com)</para
></listitem>
	<listitem
><para
>© Andreas Cord-Landwehr, 2011 (cordlandwehr@gmail.com)</para
></listitem>
</itemizedlist>

<para
>Авторские права на документацию:</para>
<itemizedlist>
	<listitem
><para
>© Anne-Marie.Mahfouf, 2009 (annma@kde.org)</para
></listitem>
	<listitem
><para
>© Tomaz Canabrava, 2009 (tcanabrava@ kde.org)</para
></listitem>
	<listitem
><para
>© Andreas Cord-Landwehr, 2011 (cordlandwehr@gmail.com)</para
></listitem>
</itemizedlist>

<para
>Перевод на русский: Алексей Субач<email
>alexey.subach@gmail.com</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Установка</title>

<sect1 id="getting-rocs">
<title
>Как получить &rocs;</title>
&install.intro.documentation; </sect1>

<sect1 id="compilation">
<title
>Компиляция и установка</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:
-->