DocBookViewer: added some kumir keywords

Documentation: a bit progress

DocBookViewer: added some kumir keywords
Documentation: a bit progress
05041564 · Victor Yacovlev · 25568706 · 05041564 · 05041564 · 05041564
Commit 05041564 authored May 21, 2013 by Victor Yacovlev
3 changed files
--- a/src/shared/docbookviewer/contentview.cpp
+++ b/src/shared/docbookviewer/contentview.cpp
@@ -213,7 +213,7 @@ QString ContentView::programTextForLanguage(const QString &source,
                                         "целтаб,вещтаб,"
                                         "литтаб,симтаб,логтаб,"
                                         "арг,рез,аргрез,пока,для,от,до,знач,"
-                                         "да,нет,не,и,или,раз"
+                                         "да,нет,не,и,или,раз,нс,файл"
                                         ).split(",");
        inlineCommentSymbol = "|";
    }

--- a/userdocs/language/index.xml
+++ b/userdocs/language/index.xml
@@ -6,6 +6,6 @@
    <title>Язык Кумир</title>
    <xi:include href="structure.xml"/>
    <xi:include href="indentifiers.xml"/>
-    <!-- <xi:include href="simple_commands.xml"/>
-    <xi:include href="compound_commands.xml"/> -->
+    <xi:include href="simple_commands.xml"/>
+    <xi:include href="compound_commands.xml"/>
 </book>
--- a/userdocs/language/simple_commands.xml
+++ b/userdocs/language/simple_commands.xml
@@ -2,6 +2,298 @@
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                    []>
-<chapter xmlns="http://www.oasis-open.org/docbook/xml/4.5/" xmlns:xi="http://www.w3.org/2001/XInclude">
+<chapter xmlns="http://www.oasis-open.org/docbook/xml/4.5/">
    <title>Простые команды</title>
+    <section>
+        <title>Присваивание</title>
+        <para>Команда присваивания предназначена для изменения значения простых переменных и элементов таблиц и имеет 
+            общий вид <code>ВЕЛИЧИНА := ВЫРАЖЕНИЕ</code>, где
+            <itemizedlist>
+                <listitem>
+                    <para>ВЕЛИЧИНА -- это имя простой величины или описание элемента таблицы;</para>
+                </listitem>
+                <listitem>
+                    <para>ВЫРАЖЕНИЕ -- это выражение, составленное из величин, констант, вызовов алгоритмов-функций
+                        и знаков операций.
+                    </para>
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>
+            Тип выражения должен быть согласован с типом величины.
+        </para>
+        <example>
+            <title>Присваивания</title>
+            <programlisting><![CDATA[
+n := 0
+m := n
+m := m+1
+m := 2*длин(t)+div(n,2)
+c := (x+y)/2
+площадь:=a*b*sin(C)/2
+d:=b**2-4*a*c
+x[1]:=(-b+sqrt(d))/(2*a)
+a[i]:=2*a[i-2]+a[i-1]
+b[i,j]:=-b[j,i]
+]]>
+            </programlisting>
+        </example>
+        <para>
+            Все переменные должны быть описаны, а их типы -- согласованы с типами операций
+            и их аргументов.
+        </para>
+    </section>
+    <section>
+        <title>Контроль выполнения</title>
+        <para>В языке Кумир существует три команды контроля выполнения: <code language="kumir">утв</code>,
+            <code language="kumir">дано</code>, <code language="kumir">надо</code>.
+        </para>
+        <para>
+            Формат вызова:
+            <programlisting role="kumir"><![CDATA[
+утв ЛОГ ВЫРАЖЕНИЕ
+дано ЛОГ ВЫРАЖЕНИЕ
+надо ЛОГ ВЫРАЖЕНИЕ
+]]>
+            </programlisting>
+        </para>
+        <para>
+            Все три команды выполняются так. Проверяется условие. Если условие не соблюдается
+            (равно <code language="kumir">нет</code>), то Кумир прекращает выполнение алгоритма и сообщает,
+            что возник отказ. Если же условие соблюдается, то выполнение алгоритма нормально продолжается так,
+            как если бы команды контроля не было вовсе.
+        </para>
+        <para>
+            Команда <code language="kumir">дано</code> проверяет условие в начале выполнения алгоритма, команда
+            <code language="kumir">надо</code> -- в конце выполнения алгоритма, а командой
+            <code language="kumir">утв</code> можно проверить условие в процессе выполнения алгоритма.
+        </para>
+        <example>
+            <title>Использование "дано" и "надо"</title>
+            <programlisting role="kumir"><![CDATA[
+алг абс (рез вещ х)
+дано х<=0
+надо х>=0
+нач
+  х := -х
+кон
+]]>
+            </programlisting>
+        </example>
+        <example>
+            <title>Использование "утв"</title>
+            <programlisting role="kumir"><![CDATA[
+алг вещ кв (вещ х)
+нач
+  вещ к
+  к := х*х
+  утв к>=0
+  знач := к
+кон
+]]>
+            </programlisting>
+        </example>
+    </section>
+    <section>
+        <title>Ввод и вывод</title>
+        <section>
+            <title>Вывод</title>
+            <para>
+                Формат вызова:
+                <programlisting role="kumir"><![CDATA[
+вывод выражение-1, ... , выражение-N
+]]>
+                </programlisting>
+                или
+                <programlisting role="kumir"><![CDATA[
+вывод величина-файлового-типа, выражение-1, ... , выражение-N
+]]>
+                </programlisting>
+            </para>
+            <para>
+                Каждое выражение может быть либо арифметическим, логическим или текстовым выражением,
+                либо командой перехода на новую строку (ключевое слово <code language="kumir">нс</code>).
+                Значения выражений выводятся последовательно в строку области ввода-вывода без разделителей.
+            </para>
+            <para>
+                Если первой величиной после команды <code language="kumir">вывод</code> является величина типа
+                <code language="kumir">файл</code>, то вместо вывода на экран, значения выражений будут записаны
+                в соответсвующий файловый объект.
+            </para>
+            <example>
+                <title>Вывод на экран</title>
+                <programlisting role="kumir"><![CDATA[
+алг
+нач
+  цел а
+  а := 3
+  вещ б
+  б := 1.3
+  нц 5 раз
+    вывод а, " ", б, "Привет!", нс
+  кц
+кон
+]]>
+                </programlisting>
+                <para>
+                    Результат вывода на экран:
+                    <programlisting><![CDATA[
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!]]>
+                    </programlisting>
+                </para>
+            </example>
+            <example>
+                <title>Вывод в файл</title>
+                <programlisting role="kumir"><![CDATA[
+использовать Файлы
+алг
+нач
+  файл ф
+  ф := открыть на запись("test.txt")
+  цел а
+  а := 3
+  вещ б
+  б := 1.3
+  нц 5 раз
+    вывод ф, а, " ", б, "Привет!", нс
+  кц
+  закрыть(ф)
+кон
+]]>
+                </programlisting>
+                <para>
+                    Содержимое файла "test.txt" после выполнения программы:
+                    <programlisting><![CDATA[
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!
+3 1.3Привет!]]>
+                    </programlisting>
+                </para>
+            </example>
+        </section>
+        <section>
+            <title>Ввод</title>
+            <para>
+                Формат вызова:
+                <programlisting role="kumir"><![CDATA[
+ввод выражение-1, ... , выражение-N
+]]>
+                </programlisting>
+                или
+                <programlisting role="kumir"><![CDATA[
+ввод величина-файлового-типа, выражение-1, ... , выражение-N
+]]>
+                </programlisting>
+            </para>
+            <para>
+                При выполнении команды <code language="kumir">ввод</code>, если первым аргументом не является
+                величина типа <code language="kumir">файл</code>, то система Кумир делает активным окно ввода-вывода
+                и ждет, пока пользователь введет соответствующие значения. По окончании введенные значения
+                присваиваются указанным величинам. В качестве имени величины можно указать имя
+                простой величины или имя элемента таблицы с указанием значений индексов.
+                Признаком конца ввода служит нажатие на клавишу Enter. При вводе нескольких значений, они
+                отделяются друг от друга пробелом.
+            </para>
+            <para>
+                Если первым аргументом является величина типа <code language="kumi">файл</code>, то производится
+                чтение данных из текстового файла.
+            </para>
+            <para>
+                TODO: описать про использование нс
+            </para>
+        </section>
+
+    </section>
+    <section>
+        <title>Вызов алгоритма</title>
+        <para>
+            Вызов алгоритма-процедуры является отдельной командой алгоритмического языка и
+            имеет вид:
+            <programlisting><![CDATA[
+имя алгоритма-процедуры
+]]>
+            </programlisting>
+            или
+            <programlisting><![CDATA[
+имя алгоритма-процедуры(список параметров вызова)
+                    ]]>
+            </programlisting>
+        </para>
+        <example>
+            <title>Вызов подпрограммы без параметров</title>
+            <programlisting role="kumir"><![CDATA[
+алг
+нач
+  подпрограмма
+кон
+
+алг подпрограмма
+нач
+  вывод "Мы в подпрограмме", нс
+кон
+]]>
+            </programlisting>
+        </example>
+        <example>
+            <title>Вызов подпрограммы с параметрами</title>
+            <programlisting role="kumir"><![CDATA[
+алг
+нач
+  сумма(2.4, 7.6)
+кон
+алг сумма(вещ а, вещ б)
+нач
+  вывод "Сумма = ", а+б, нс
+кон
+]]>
+            </programlisting>
+        </example>
+    </section>
+    <section>
+        <title>Выход</title>
+        <para>
+            Команда <code language="kumir">выход</code> используется для выхода из цикла или для окончания
+            работы текущего алгоритма. Если команда <code language="kumir">выход</code> выполняется внутри
+            цикла, то выполнение продолжается с первой команды после тела этого цикла. Если команда
+            <code language="kumir">выход</code> используется во вложенных циклах, то завершается самый внутренний
+            цикл. Если команда выход выполняется вне циклов, то она приводит к завершению выполнения текущего
+            алгоритма.
+        </para>
+        <example>
+            <title>Использование команды "выход"</title>
+            <programlisting role="kumir"><![CDATA[
+алг
+нач
+  нц
+    нц
+      вывод "–2–", нс
+      выход
+    кц
+    вывод "–1–", нс
+    выход
+  кц
+  вывод "–0–", нс
+  выход
+  вывод "–F–", нс
+кон
+]]>
+            </programlisting>
+            <para>
+                При выполнении этой программы будет выведено на экран:
+                <programlisting><![CDATA[
+–2–
+–1–
+–0–
+–F–
+]]>
+                </programlisting>
+            </para>
+        </example>
+    </section>
 </chapter>