<?xml version="1.0" encoding="UTF-8" ?>

<chapter id="extending-quanta-3-2">
<chapterinfo>
<title
>Расширение &quantaplus;</title>
<authorgroup>
<author
><firstname
>Christopher</firstname
> <surname
>Hornbaker</surname
> <affiliation
> <address
><email
>chrishornbaker@earthlink.net</email
></address>
</affiliation>
</author>

<othercredit role="translator"
><firstname
>Николай</firstname
><surname
>Шафоростов</surname
><affiliation
><address
><email
>shafff@ukr.net</email
></address
></affiliation
><contrib
>перевод на русский</contrib
></othercredit
> 

</authorgroup>
</chapterinfo>

<title
>Расширение &quantaplus;</title>

<para
>Эта глава описывает процесс расширения базовых возможностей &quantaplus; для ваших нужд и как вы можете содействовать её развитию. </para>

<!--<sect1 id="kommander-3-2">
<title
>Using Kommander With &quantaplus;</title>

<para>
Kommander, by Marc Britton.
</para>
</sect1
> -->

<sect1 id="dtep-intro-3-2">
<title
>Пакеты типов документов (Document Type Editing Package, &DTEP;)</title>

<para
>&DTEP; используются в &quantaplus; для поддержки языков разметки, скриптов и &CSS;. Они позволяют обеспечить такие функции как автодополнение, редактирование тегов. Их простота и надёжность делает &quantaplus; быстрой, дружественной средой для веб-разработчиков. </para>

<para
>&DTEP; разделяется на две семьи - разметочную и скриптовую с &CSS;. &DTEP; состоит из двух частей - каталога тегов и панелей инструментов. Каталог тегов состоит из файла описания description.rc и файла TagXML с расширением .tag. Панель инструментов - это набор кнопок со значками (над окном редактирования), каждая из которых соответствует какому-либо тексту, вставляемому в документ при нажатии на неё (часто это шаблон тега). </para>

<para
>В этой части описывается создание файлов TagXML, description.rc и панелей инструментов. В общем &DTEP;. </para>

<para
>Файлы TagXML (.tag) определяют атрибуты, специфичные для данного тега и содержимое диалога "Свойства тега". Файл description.rc содержит правила и данные о &DTEP;. Панели инструментов позволяют быстро обратится к тому или иному тегу для вставки его в документ. </para>

<sect2 id="dtep-packaging-3-2">
<title
>Создание пакетов</title>

<para
>Каталоги тегов - это обычные каталоги, содержащие файлы description.rc и TagXML. В их названии отражается название языка разметки с его версией (например, html-4.01-strict) </para>
</sect2>

<sect2 id="tagxml-3-2">
<title
>TagXML</title>

<para
>Таблица содержит список элементов, определённых в TagXML и говорит, обязательны они, или нет. Не смотря на то, что обязательны не все, рекомендуется всё же использовать как можно больше доступных элементов, чтобы пользователи имели больше настроек и информации. </para>

<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry
>Элемент</entry>
<entry
>Использование по умолчанию</entry>
<entry
>Частное использование</entry>
</row>
</thead>
<tbody>
<row>
<entry
>TAGS</entry>
<entry
>required</entry>
<entry
>always</entry>
</row>
<row>
<entry
>tag</entry>
<entry
>required</entry>
<entry
>always</entry>
</row>
<row>
<entry
>label</entry>
<entry
>optional</entry>
<entry
>обязательно для диалога "Свойства"</entry>
</row>
<row>
<entry
>attr</entry>
<entry
>optional</entry>
<entry
>обязательно для определения атрибута</entry>
</row>
<row>
<entry
>tooltip</entry>
<entry
>optional</entry>
<entry
>обязательно для подсказок в диалоге "Свойства"</entry>
</row>
<row>
<entry
>whatsthis</entry>
<entry
>optional</entry>
<entry
>обязательно для возможности отображения краткой справки <quote
>Что это? </quote
></entry>
</row>
<row>
<entry
>list</entry>
<entry
>optional</entry>
<entry
>обязательно если attr имеет тип <quote
>list</quote
></entry>
</row>
<row>
<entry
>item</entry>
<entry
>optional</entry>
<entry
>обязательно если используется &lt;list
></entry>
</row>
<row>
<entry
>textlocation</entry>
<entry
>optional</entry>
<entry
>always</entry>
</row>
<row>
<entry
>location</entry>
<entry
>optional</entry>
<entry
>обязательно если используется метка</entry>
</row>
<row>
<entry
>text</entry>
<entry
>optional</entry>
<entry
>обязательно если используется метка</entry>
</row>
<row>
<entry
>children</entry>
<entry
>optional</entry>
<entry
>список тегов, которые могут использоваться в определяемом</entry>
</row>
<row>
<entry
>child</entry>
<entry
>required</entry>
<entry
>дочерний элемент</entry>
</row>
<row>
<entry
>stoppingtags</entry>
<entry
>optional</entry>
<entry
>список тегов, которые приводят к окончанию действия другого тега</entry>
</row>
<row>
<entry
>stoppingtag</entry>
<entry
>required</entry>
<entry
>тег, который приводит к окончанию действия другого тега</entry>
</row>
</tbody>
</tgroup>
</informaltable>


<sect3 id="dtep-element-descriptions-3-2">
<title
>Описания элементов TagXML</title>

<para
>Ниже детально описывается каждый элемент. </para>

<sect4 id="TAGS-3-2">
<title
>TAGS</title>

<para
>Корневой элемент файла TagXML. Может встречаться только один раз. Содержит определение нескольких тегов. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
><emphasis
>НЕТ</emphasis
></entry>
<entry
>tag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="tag-3-2">
<title
>tag</title>

<para
>Название определяемого тега. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>TAGS</entry>
<entry
>label, attr, stoppingtags</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry
><entry
>Значения</entry>
<entry
>По умолчанию</entry
><entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry
><entry
></entry
><entry
></entry>
<entry
>required</entry
><entry
>Название определяемого тега.</entry>
</row>
<row>
<entry
>single</entry
><entry
>boolean</entry
><entry
></entry
><entry
></entry>
<entry
>optional</entry
><entry
>Требуется ли закрывающий тег &lt;/имя_тега
>.</entry>
</row>
<row>
<entry
>type</entry
><entry
>string</entry
><entry
></entry
><entry
>xmltag</entry>
<entry
>optional</entry
><entry
>Тип определяемого тега.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>xmltag</entry
><entry
></entry>
<entry
></entry
><entry
>Тип тега основывается на XML (только семья 1).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>property</entry
><entry
></entry>
<entry
></entry
><entry
>Тип тега основывается на &CSS;. (только семья 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>function</entry
><entry
></entry>
<entry
></entry
><entry
>Тип тега - скриптовая функция. Если это так, &lt;attr
> становится аргументами функции (только семья 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>class</entry
><entry
></entry>
<entry
></entry
><entry
>Тип тега - скриптовый класс (только семья 2).</entry>
</row>
<row>
<entry
>returnType</entry
><entry
>string</entry
><entry
></entry
><entry
>void </entry>
<entry
>optional</entry
><entry
>Тип возвращаемого значения определяемой функции (только семья 2)</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>void</entry
><entry
></entry>
<entry
></entry
><entry
>Возвращаемое значение игнорируется (void).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>int</entry
><entry
></entry>
<entry
></entry
><entry
>Возвращается число (integer).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>float</entry
><entry
></entry>
<entry
></entry
><entry
>Возвращается число с плавающей точкой (floating point).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>long</entry
><entry
></entry>
<entry
></entry
><entry
>Возвращается длинное целочисленное (long integer).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>string</entry
><entry
></entry>
<entry
></entry
><entry
>Возвращается строка</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="label-3-2">
<title
>label</title>

<para
>Добавить в диалог метку. Её текст указывается  тегом &lt;text
>. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry>
<entry
>text, location</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="attr-3-2">
<title
>attr</title>

<para
>Определяет один атрибут тега. Содержит имя, тип атрибута, информацию о его отображении. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry>
<entry
>location, list, tooltip, whatsthis, textlocation</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry
><entry
>Значения</entry>
<entry
>По умолчанию</entry
><entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry
><entry
></entry
><entry
></entry>
<entry
>required</entry
><entry
>Имя определяемого атрибута.</entry>
</row>
<row>
<entry
>type</entry
><entry
>string</entry
><entry
></entry
><entry
>input</entry>
<entry
>required</entry
><entry
>Тип определяемого атрибута.</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>input</entry
><entry
></entry>
<entry
></entry
><entry
>Поте текстового ввода (text field).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>check</entry
><entry
></entry>
<entry
></entry
><entry
>Логическое поле (check box).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>color</entry
><entry
></entry>
<entry
></entry
><entry
>Значение поля - цвет</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>url</entry
><entry
></entry>
<entry
></entry
><entry
>Значение поля - &URL; (или локальный файл)</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>list</entry
><entry
></entry>
<entry
></entry
><entry
>Значение поля - запись указанного списка.</entry>
</row>
<row>
<entry
>status</entry
><entry
>string</entry
><entry
></entry
><entry
>optional</entry>
<entry
>required</entry
><entry
>Обязательность аргумента (только семья 2).</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>optional</entry
><entry
></entry>
<entry
></entry
><entry
>Аргумент необязателен</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>required</entry
><entry
></entry>
<entry
></entry
><entry
>Аргумент обязателен</entry>
</row>
<row>
<entry
></entry
><entry
></entry
><entry
>implied</entry
><entry
></entry>
<entry
></entry
><entry
>Аргумент есть неявный.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="tooltip-3-2">
<title
>tooltip</title>

<para
>Текст подсказки поля (отображается при наведении курсора на него). </para>

<note>
<para
>Поддерживается только обычный текст (т.е. нельзя использовать никакие теги). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="whatsthis-3-2">
<title
>whatsthis</title>

<para
>Текст "Что это?" для данного поля. </para>

<note>
<para
>Поддерживается только обычный текст (т.е. нельзя использовать никакие теги). </para>
</note>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="list-3-2">
<title
>list</title>

<para
>Тег, сводящий вместе записи в списке. Может употребляться только один раз для каждого описания атрибута. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
>item</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="item-3-2">
<title
>item</title>

<para
>Определяет запись в списке. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>list</entry>
<entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="textlocation-3-2">
<title
>textlocation</title>

<para
>Позиция в окне свойств параметра, отвечающего атрибуту тега. Может употребляться только один раз для каждого атрибута диалога (т.е. для каждого &lt;attr
>). Не может содержать подэлементы. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry>
<entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>attr</entry>
<entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry>
<entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>row</entry
><entry
>неотрицательное число</entry>
<entry
>required</entry
><entry
>Ряд поля или метки при отображении в окне.</entry>
</row>
<row>
<entry
>col</entry
><entry
>неотрицательное число</entry>
<entry
>required</entry
><entry
>Столбец поля или метки при отображении в окне.</entry>
</row>
<row>
<entry
>rowspan</entry
><entry
>неотрицательное число</entry>
<entry
>optional</entry
><entry
>Число рядов, отводимых полю.</entry>
</row>
<row>
<entry
>colspan</entry
><entry
>неотрицательное число</entry>
<entry
>optional</entry
><entry
>Число столбцов, отводимых полю.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="location-3-2">
<title
>location</title>

<para
>Положение и размер поля в окне свойств. Может употребляться только один раз для каждого поля в диалоге (т.е. для каждого &lt;attr
> и &lt;label
>). Не может содержать подэлементы. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>label, attr</entry
><entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry>
<entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>row</entry
><entry
>неотрицательное число</entry>
<entry
>required</entry
><entry
>Ряд поля или метки при отображении в окне.</entry>
</row>
<row>
<entry
>col</entry
><entry
>неотрицательное число</entry>
<entry
>required</entry
><entry
>Столбец поля или метки при отображении в окне.</entry>
</row>
<row>
<entry
>rowspan</entry
><entry
>неотрицательное число</entry>
<entry
>optional</entry
><entry
>Число рядов, отводимых полю.</entry>
</row>
<row>
<entry
>colspan</entry
><entry
>неотрицательное число</entry>
<entry
>optional</entry
><entry
>Число столбцов, отводимых полю.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="text-3-2">
<title
>text</title>

<para
>Текст метки или флажка (check box). </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>label, attr</entry
><entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="children-3-2">
<title
>children</title>

<para
>Список элементов, которые могут использоваться в определяемом теге. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry
><entry
>child</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="child-3-2">
<title
>child</title>

<para
>Дочерний тег. Не может содержать подэлементы. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>children</entry
><entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry>
<entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry>
<entry
>required</entry
><entry
>Тег, который может употребляться в некотором другом теге.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="stoppingtags-3-2">
<title
>stoppingtags</title>

<para
>Список элементов, которые приводят к окончанию действия тега. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>tag</entry
><entry
>stoppingtag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>

<sect4 id="stoppingtag-3-2">
<title
>stoppingtag</title>

<para
>Тег, приводящий к окончанию действия другого тега. Не может содержать подэлементы. </para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry
>Родительские элементы</entry
><entry
>Дочерние элементы</entry>
</row>
</thead>
<tbody>
<row>
<entry
>stoppingtags</entry
><entry
><emphasis
>НЕТ</emphasis
></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry
>Атрибут</entry
><entry
>Тип</entry>
<entry
>Use</entry
><entry
>Описание</entry>
</row>
</thead>
<tbody>
<row>
<entry
>name</entry
><entry
>string</entry>
<entry
>required</entry
><entry
>Теги, приводящие к окончанию действия другого тега.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
</sect3>

<sect3 id="tagxml-usage-3-2">
<title
>Использование TagXML</title>

<para
>Все файлы TagXML должны начинаться с декларации &XML;: &lt;?xml version="1.0" encoding="UTF-8"?>, правильно структурированными и закрытыми. </para>

<important>
<para
>Пробелы не играют роли, однако следите за символами &amp; и &lt;. В элементах &lt;tooltip
>, &lt;whatsthis
>, &lt;text
>, их лучше заменить на &amp;amp; и &amp;lt; соответственно. Невыполнение этого не приведёт к краху, но ваша работа может пропасть. </para>
</important>
</sect3>

<sect3 id="tagxml-validation-3-2">
<title
>Проверка TagXML</title>

<para
>Чтобы выполнить проверку файлов TagXML, выберите <quote
>Сервис</quote
>, <quote
>Проверить TagXML.</quote
>. </para>

<note>
<para
>Эта функция пока что не реализована и проверка происходит при загрузке файлов TagXML в &quantaplus;. </para>
</note>
</sect3>

<sect3 id="tagxml-examples-3-2">
<title
>Примеры TagXML</title>

<sect4 id="family-one-3-2">
<title
>Семья 1</title>

<para
>Ниже следует файл TagXML семьи 1. Он описывает элемент &W3C; &XML; &lt;schema
>. Имя такого файла будет schema.tag. Просто, не так ли? </para>

<informalexample>
<literallayout
><markup>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!DOCTYPE TAGS>
&lt;TAGS>
 &lt;tag name="schema">
  &lt;label>
   &lt;text
>id&lt;/text>
   &lt;location col="0" row="0"/>
  &lt;/label>
  &lt;attr name="id" type="input">
   &lt;tooltip
>A unique ID for the element.&lt;/tooltip>
   &lt;whatsthis
>A unique ID for the element.&lt;/whatsthis>
   &lt;location col="1" row="0"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>version&lt;/text>
   &lt;location col="0" row="1"/>
  &lt;/label>
  &lt;attr name="version" type="input">
   &lt;tooltip
>Version of the schema.&lt;/tooltip>
   &lt;whatsthis
>Version of the schema.&lt;/whatsthis>
   &lt;location col="1" row="1"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>targetNamespace&lt;/text>
   &lt;location col="0" row="2"/>
  &lt;/label>
  &lt;attr name="targetNamespace" type="input">
   &lt;tooltip
>&URI; reference of the namespace of this schema.&lt;/tooltip>
   &lt;whatsthis
>&URI; reference of the namespace of this schema.&lt;/whatsthis>
   &lt;location col="1" row="2"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>xmlns&lt;/text>
   &lt;location col="0" row="3"/>
  &lt;/label>
  &lt;attr name="xmlns" type="input">
   &lt;tooltip
>&URI; reference for one or more namespaces for use in this schema.
   If no prefix is used, then components of that namespace may be used unqualified.&lt;/tooltip>
   &lt;whatsthis
>&URI; reference for one or more namespaces for use in this schema.
   If no prefix is used, then components of that namespace may be used unqualified.&lt;/whatsthis>
   &lt;location col="1" row="3"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>attributeFormDefault&lt;/text>
   &lt;location col="0" row="4"/>
  &lt;/label>
  &lt;attr name="attributeFormDefault" type="list">
   &lt;items>
    &lt;item
>qualified&lt;/item>
    &lt;item
>unqualified&lt;/item>
   &lt;/items>
   &lt;tooltip
>Default form for all attributes within this schema.&lt;/tooltip>
   &lt;whatsthis
>Default form for all attributes within this schema.&lt;/whatsthis>
   &lt;location col="1" row="4"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>elementFormDefault&lt;/text>
   &lt;location col="0" row="5"/>
  &lt;/label>
  &lt;attr name="elementFormDefault" type="list">
   &lt;items>
    &lt;item
>qualified&lt;/item>
    &lt;item
>unqualified&lt;/item>
   &lt;/items>
   &lt;tooltip
>Default form for all elements within this schema.&lt;/tooltip>
   &lt;whatsthis
>Default form for all elements within this schema.&lt;/whatsthis>
   &lt;location col="1" row="5"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>blockDefault&lt;/text>
   &lt;location col="0" row="6"/>
  &lt;/label>
  &lt;attr name="blockDefault" type="input">
   &lt;location col="1" row="6"/>
  &lt;/attr>

  &lt;label>
   &lt;text
>finalDefault&lt;/text>
   &lt;location col="0" row="7"/>
  &lt;/label>
  &lt;attr name="finalDefault" type="input">
   &lt;location col="1" row="7"/>
  &lt;/attr>
 &lt;/tag>
&lt;/TAGS>
</markup
>
</literallayout>
</informalexample>
</sect4>

<sect4 id="family-two-3-2">
<title
>Семья 2</title>

<para
>Ниже следует  файл TagXML семьи 2. Он описывает &PHP;-функцию перегрузки (overload). Имя такого файла будет overload.tag. </para>

<informalexample>
<literallayout
><markup>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;!DOCTYPE tags>
&lt;tags>
  &lt;tag name="overload" type="function" returnType="void">
&lt;attr name="class_name" type="string" status="optional"/>
  &lt;/tag>
&lt;/tags>
</markup
>
</literallayout>
</informalexample>
</sect4>
</sect3>
</sect2>

<sect2 id="descriptionrc-3-2">
<title
>description.rc</title>

<para
>Файл description.rc также прост по структуре. Не нужно использовать всё из ниже следующего. Далее следует структура файла description.rc. </para>

<sect3 id="family-one-structure-3-2">
<title
>Структура для семьи 1</title>

<informalexample>
<literallayout
><markup>
[General] - Общая информация.
Version = Пишите 1 для &quantaplus; версии &lt;=3.1.2 и 2 &mdash; для любой более поздней версии.
Name = Строка определения DTD. (-//W3C//DTD HTML 4.01 Transitional//EN)
NickName = Красивое имя DTD. (HTML 4.01 Transitional). Если нет, используется Name.
URL = URL, указывающий на определение DTD (http://www.w3.org/TR/html4/loose.dtd)
DoctypeString = Декларация !DOCTYPE.
(HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
Inherits = DTD, от которой определяемый DTD наследует теги. (-//W3C//DTD HTML 4.01//EN)
DefaultExtension = Расширение для создаваемых файлов (html)
Groups = Список общих групп атрибутов, которые могут присутствовать в более чем одном теге.
(Core, I18n, Script) См. ниже. (Group1, Group2...)
NumOfPages = Сколько вкладок в диалоге свойств тега, за исключением страницы с атрибутами,
определёнными в файле тегов. См. ниже. (Page1,...)
CaseSensitive = Чувствительность к регистру DTD. (true|false)
Family = Номер семьи DTEP. В нашем случае - это 1, т.к. это язык разметки.

[Toolbars] - Инфо панелей инструментов DTEP.
Location = Подкаталог $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
Names = Список файлов панелей инструментов, без окончания .toolbar.tgz
[Group1] - Замените на одну из групп, изложенных ниже.
Attributes = Список атрибутов группы. Все атрибуты рассматриваются как строки
Например:
[Core]
Attributes = id, class, style, title

[Page1] - Описание вкладки диалога свойств тега.
Title = Заголовок вкладки.
Groups = Список групп, отображающихся на ней. (Core, I18n)

[Extra rules] - Дополнительные правила.
BooleanAttributes = (simple|complex)
Пример simple: &lt;tag booleanAttr
>.
Пример complex: &lt;tag booleanAttr="1"
> или &lt;tag booleanAttr="true">
Single Tag Style = (html|XML)
Пример непарного тега html: &lt;single_tag>
Пример непарного тега XML:  &lt;single_tag />
StructGroupsCount = Количествоe структурных групп. См. ниже.
MinusAllowedInWords = Если true, "this-is-a-word" рассматривается как одно слово. Иначе &mdash; как 4.
TagAutoCompleteAfter = CHAR. Раскрывать список автодополнения после ввода символа CHAR
или нажатия пробела когда курсор ввода перед ним. Для семьи 1,
это обычно "&lt;". "none" отменяет автоматическое выпадения списка, который, при 
необходимости, можно вызвать горячими клавишами.
AttributeSeparator = CHAR. Символ, говорящий об окончании названия атрибута. Для XML.
TagSeparator = CHAR. Как и выше, только для тега.

[StructGroup_1] - Определение структурной группы 1.
Name = Текст, отображаемый если есть теги, отвечающие этим параметрам группы.
No_Name = Текст, отображаемый если НЕТ тегов, отвечающих этим параметрам группы.
Icon = Название значка, отображаемого перед текстами.
Tag = имя_тега(attribute1, attribute2, ...). Теги с именем имя_тега будут в этой группе.
Текст пункта будет "значение_attribute1 | значение_attribute2 | ..."
Сейчас только один тег может быть здесь.
HasFileName = (true|false) True, если текст пункта содержит имя файла.
FileNameRx = Регулярное выражение для удаления ненужных символов из текста пункта.

[Parsing rules] - Правила, использующиеся для анализа документа.
SpecialAreas = Начальная и конечная строки специальных областей, разделённые запятой.
Специальные области не анализируются согласно правилам текущего DTEP. Это могут быть DTEP другой семьи, комментариями.
Например &lt;!-- -->
SpecialAreaNames = Разделённый запятыми список названий спец. областей (например comment)
SpecialTags = tagname(attributename) - Тег, начинающий специальную область.
MayContain = Разделённый запятыми список DTEP семьи 2, которые могут 
присутствовать в документе (php, css).
</markup
>
</literallayout>
</informalexample>
</sect3>

<sect3 id="family-two-structure-3-2">
<title
>Структура для семьи 2</title>

<informalexample>
<literallayout
>г<markup>
[General] - Общая информация.
Version = Пишите 1 для &quantaplus; версии &lt;=3.1.2 и 2 &mdash; для любой более поздней версии.
Name = Строка определения DTD. (-//W3C//DTD HTML 4.01 Transitional//EN)
NickName = Красивое имя DTD. (HTML 4.01 Transitional). Если нет, используется Name.
URL = URL, указывающий на определение DTD (http://www.w3.org/TR/html4/loose.dtd)
DoctypeString = Декларация !DOCTYPE.
(HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
Inherits = DTD, от которого определяемый DTD наследует теги. (-//W3C//DTD HTML 4.01//EN)
DefaultExtension = Расширение для создаваемых файлов (html)
Groups = Список общих групп атрибутов, которые могут присутствовать в более чем одном теге.
(Core, I18n, Script) См. ниже. (Group1, Group2...)
NumOfPages = 0  Всегда, т.к. диалог свойств не поддерживается для семьи 2.
CaseSensitive = Чувствительность к регистру DTD. (true|false)
Family = Номер семьи DTEP. В нашем случае - это 2, т.к. это не язык разметки.

[Toolbars] - Инфо панелей инструментов DTEP.
Location = Подкаталог $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
Names = Список файлов панелей инструментов, без окончания .toolbar.tgz
Extra rules] - Дополнительные правила.
BooleanAttributes = (simple|complex)
Пример simple: &lt;tag booleanAttr
>.
Пример complex: &lt;tag booleanAttr="1"
> или &lt;tag booleanAttr="true">
Single Tag Style = (html|XML)
Пример непарного тега html: &lt;single_tag>
Пример непарного тега XML:  &lt;single_tag />
StructGroupsCount = Количествоe структурных групп. См. ниже.
MinusAllowedInWords = Если true, "this-is-a-word" рассматривается как одно слово. Иначе &mdash; как 4.
TagAutoCompleteAfter = CHAR. Открывать список автодополнения после ввода символа CHAR
или нажатия пробела когда курсор ввода перед ним. Для семьи 1,
это обычно "&lt;". "none" отменяет автоматическое выпадения списка, который, при 
необходимости, можно вызвать горячими клавишами.
AttributeAutoCompletionAfter = CHAR. Как и TagAutoCompletionAfter, но
для тегов. По умолчанию - "(" и ":" - для CSS.

AttributeSeparator = CHAR. Символ, говорящий об окончании названия атрибута. Для XML.
TagSeparator = CHAR. Как и выше, только для тега.

[StructGroup_1] - Определение структурной группы 1.
Name = Текст, отображаемый если есть теги, отвечающие этим параметрам группы.
No_Name = Текст, отображаемый если НЕТ тегов, отвечающих этим параметрам группы.
Icon = Название значка, отображаемого перед текстами.
Tag = имя_тега(attribute1, attribute2, ...). Теги с именем имя_тега будут в этой группе.
Текст пункта будет "значение_attribute1 | значение_attribute2 | ..."
Сейчас только один тег может быть здесь.
HasFileName = (true|false) True, если текст пункта содержит имя файла.
FileNameRx = Регулярное выражение для удаления ненужных символов из текста пункта.
SearchRx = Регулярное выражение для поиска областей в семье 2, которые будут принадлежать этой группе.
ClearRx = Регулярное выражение для избавления от ненужного текста/символов
в результатах поиска. Очищенная строки будет отображена в структуре.

[Parsing rules] - Правила, использующиеся для анализа документа.
SpecialAreas = Начальная и конечная строки специальных областей, разделённые запятой.
Специальные области не анализируются согласно правилам текущего DTEP. Это могут быть DTEP другой семьи, комментариями.
Например &lt;!-- -->
SpecialAreaNames = Разделённый запятыми список названий спец. областей (например comment)
SpecialTags = tagname(attributename) - Тег, начинающий специальную область.
AreaBorders = Разделённый запятыми список границ областей, обрамляющих эту семью 2. В случае
PHP, это: &lt;? ?>, &lt;* *
>, &lt;% %>
Tags = имя_тега(attribute). Если (существующий) родительский DTD имеет тег имя_тега
и значение параметра attribute равно названию DTD, область тега
анализируется в соответствии с правилами этого DTD.
Comments = Разделённый запятыми список границ области комментариев. EOL означает конец строки.
Например: // EOL, /* */
StructKeywords = Разделённый точками с запятыми ключевых слов структуры.StructBeginStr = Строка, указывающая на начало структуры (например "{")
StructEndStr = Строка, указывающая на конец структуры (например })
StructRx = Регулярное выражение, содержащее начало или  конец этой структуры
Например. \\{ | \\} (границей структуры может быть { и })
</markup
>
</literallayout>
</informalexample>
</sect3>
</sect2>
</sect1>

<sect1 id="creating-toolbars-3-2">
<title
>Создание панелей инструментов</title>

<para
>Ниже следует описание создания панелей инструментов для &DTEP;. По сути, это - графические элементы, отвечающие определённому действию. Последнее - основа почти всех расширений, которые есть или будут появляться в будущем в &quantaplus;. Схема определения действия в &quantaplus; также годится для автодополнения и диалогов свойств тегов. </para>

<sect2 id="from-scratch-to-complete-3-2">
<title
>С нуля до совершенства</title>

<para
>Начнём с создания пользовательской панели инструментов: <menuchoice
><guimenu
>Панели инструментов</guimenu
><guimenuitem
>Добавить пользовательскую панель инструментов</guimenuitem
></menuchoice
>. </para>

<para
>Если в языке разметки много тегов, лучше разделить их по группам. Для каждой группы создайте отдельную панель инструментов. В нашем случае тегов не много, поэтому обойдёмся одной. </para>

<para
>Далее следует добавить и настроить действия - <menuchoice
><guimenu
>Настройка</guimenu
><guimenuitem
>Настроить действия...</guimenuitem
></menuchoice
>. </para>

<para
>Нажмите кнопку <guibutton
>Создать</guibutton
> (внизу окна). </para>

<para
>Заполните все необходимые поля и добавьте тег в соответствующую панель инструментов. </para>

<para
>Если у тега есть атрибуты (и вы будете часто их использовать), отметьте <guilabel
>Запустить диалог "Изменить тег", если он доступен</guilabel
>, и каждый раз при использовании данного действия, будет предложено заполнить свойства добавляемого тега. </para>

<para
>Теперь у вас должно быть что-то вроде этого. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img7.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Нажмите кнопку <guibutton
>Применить</guibutton
>. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img8.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Но что же получилось?! Как вы запомните, какой значок к какому действию относится? Давайте заменим его на свой (покрасивее). </para>

<para
>Для создания значка можно использовать &kiconedit;. Запустите её из &kmenu;, <menuchoice
> <guisubmenu
>Графика</guisubmenu
><guisubmenu
>Дополнительные приложения</guisubmenu
></menuchoice
>) </para>

<para
>&kiconedit; создаёт значки с расширением 32x32, однако нам нужно 22x22 - <menuchoice
> <guimenu
>Правка</guimenu
> <guimenuitem
>Изменить размер</guimenuitem
> </menuchoice
>. </para>

<para
>Помните, что вы создаёте значок, который поможет вспомнить вам (и не только вам) действие, которому он отвечает, а не просто красивую картинку. </para>

<para
>В нашем случае создаётся значок для тега &lt;start
>,поэтому для него будет использоваться зелёный цвет. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img15.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Сохраним значок. </para>

<para
>После создания значка нужно ассоциировать его с действием. Откройте окно <emphasis
>Настроить действия</emphasis
> и выберите нужное действие. Слева от поля <emphasis
>Текст</emphasis
> есть кнопка - нажмите её. </para>

<para
>Выберите <guilabel
>Прочие пиктограммы</guilabel
> и нажмите кнопку <guibutton
>Обзор</guibutton
>. </para>

<para
>Перейдите в каталог, в котором вы сохранили значок, выберите его и нажмите <guibutton
>OK</guibutton
>. </para>

<para
>Нажмите кнопку <guibutton
>Применить</guibutton
>
> или <guibutton
>OK</guibutton
>. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img18.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Чтобы добавить какие-то общие для &quantaplus; функции на панель инструментов, или разделители кнопок, в окне <guilabel
>Настроить панели инструментов</guilabel
> выделите нужную панель инструментов и выберите в списке слева действие (или разделитель). </para>

 

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img21.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Например, можно добавить <guilabel
>Просмотр в Konqueror</guilabel
>. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img22.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Обратите внимание на то, что разделитель способствует группированию. Один человек подумал, что кнопка &konqueror;, стоящая рядом с зелёной кнопкой "Старт", имеет противоположное значение ("Стоп"). </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img23.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>После внесения изменений, нажмите кнопку <guibutton
>OK</guibutton
>. </para>

<para
>Посмотрите на новую панель инструментов! Фантастика! </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img24.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>Не забудьте протестировать вашу новую панель инструментов нажатием всех расположенных на ней кнопок. </para>

<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img25.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
><menuchoice
><guimenu
>Панели инструментов</guimenu
> <guisubmenu
>Сохранить</guisubmenu
><guimenuitem
> Сохранить как локальную панель инструментов</guimenuitem
></menuchoice
>. </para>

<para
>Сохраните в правильном каталоге. Убедитесь, что вы заполнили description.rc так, чтобы при открытии документа данного типа, загружались соответствующие панели инструментов. </para>
</sect2>
</sect1>


<sect1 id="creating-quanta-docs-3-2">
<sect1info>
<title
>Написание документации</title>
<authorgroup>
<author
><firstname
>Robert</firstname
> <surname
>Nickel</surname
> <affiliation
> <address
><email
>robert@artnickel.com</email
></address>
</affiliation>
</author>

<othercredit role="translator"
><firstname
>Николай</firstname
><surname
>Шафоростов</surname
><affiliation
><address
><email
>shafff@ukr.net</email
></address
></affiliation
><contrib
>перевод на русский</contrib
></othercredit
> 

</authorgroup>
</sect1info>

<title
>Написание документации</title>

<para
>Самое заметное, что может сделать рядовой пользователь - дополнение документации по разметочному или скриптовому языку, который ему нравится. Далее описывается, как было создано дерево документации &PHP;. </para>

<para
>Перед началом написания проверьте <ulink url="http://quanta.sf.net/main1.php?contfile=resource"
>репозиторий &quantaplus;</ulink
>. </para>

<para
>Первый шаг - получение существующей документации. Второй - создание файла <filename
>docrc</filename
>. </para>

<para
>Общая форма docrc: </para>

<informalexample>
<literallayout
>#KDE Config File
[Tree]
Doc dir=<replaceable
>путь (относительно к этому файлу) к файлам html</replaceable
> &eg; php42/
#top level elements
Top Element=<replaceable
>Описание документации</replaceable
> &eg; &PHP; 4.2 documentation

Section 1=Section1.html
Section 2=#Sec2.1,#Sec2.2,#Sec2.3
Sec2.1=Sec2.1.html
Sec2.2=Sec2.2.html
Sec2.3=Sec2.3.html
...

[Context]
ContextList=func1,func2,tag1,tag2,tag3
func1=func1.html
func2=func2.html
tag1=tag1.html
tag2=tag2.html
tag3=tag3.html
</literallayout>
</informalexample>

<para
>Файл <filename
>docrc</filename
> разделён на две секции - Tree и Context. </para>

<para
>Секция Tree определяет размещение вашей документации в структуре (слева в главном окне). Например: </para>

<mediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG"/>
</imageobject>
</mediaobject>

<para
>В соответствии со структурой, описанной выше, <filename
>docrc</filename
> для &PHP; выглядит так: </para>

<informalexample>
<literallayout
>#KDE Config File

[Tree]

Doc dir=php42/

#top level elements
Top Element=PHP 4.2 documentation

PHP 4.2 documentation=Table of Contents,#Getting Started,#Language Reference

Table of Contents=index.html

Getting Started=Introduction, ...
Introduction=introduction.html
...

Language Reference=Basic syntax, ...
Basic syntax=language.basic-syntax.html
...

</literallayout>
</informalexample>

<para
>Обратите внимание на наличие <literal
>#</literal
> перед <quote
>Getting Started</quote
> и <quote
>Language Reference</quote
>. Это говорит о том, что они содержат подэлементы. </para>

<para
>Table of Contents ссылается напрямую на файл (и следовательно отображается внизу структуры &mdash; каталоги сначала!). </para>

<important>
<para
>Пробелы не влияют ни на что, но следите за символами &amp; и &lt;. Во всех файлах, основанных на &XML;, их лучше заменить на &amp;amp; и &amp;lt; соответственно. </para>
</important>

<para
>Секция Context используется контекстно зависимой справки. Например, вы пишите скрипт &PHP; и вам нужно просмотреть документацию по функции <function
>mysql_fetch_array</function
>. Для этого вам нужно будет выделить её название и нажать  <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
>. При этом отобразится сразу информация по этой функции. </para>

<variablelist>
<varlistentry>
<term
>ContextList</term>
<listitem>
<para
>Разделённый запятыми список контекстных пунктов, по которым будет доступна контекстная справка (для &PHP; - это его функции). </para>
</listitem>
</varlistentry>
<varlistentry>
<term
>Ссылки на файлы контекстной справки</term>
<listitem>
<para
>Формат: "контекстный пункт=страница html". Например: acos=function.acos.html </para>
</listitem>
</varlistentry>
</variablelist>

<para
>Готовая версия <filename
>docrc</filename
>: </para>

<informalexample>
<literallayout
>#Keywords for context help
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...

abs=function.abs.html
acos=function.acos.html
acosh=function.acosh.html
addcslashes=function.addcslashes.html
addslashes=function.addslashes.html
...
</literallayout>
</informalexample>

<para
>Теперь сохраните ваш файл <filename
>docrc</filename
> в каталоге <filename class="directory"
>$<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
> или <filename class="directory"
>$<envar
>KDEDIR</envar
>/share/apps/quanta/doc</filename
> для локального или глобального использования соответственно. Затем создайте (под)каталог (как указано в файле <filename
>docrc</filename
>) в одном каталоге с <filename
>docrc</filename
> и скопируйте в него страницы &HTML;. </para>

<para
>Перезапустите &quantaplus; чтобы увидеть добавленную документацию. </para>

<para
>После того, как вы убедитесь, что она годится для того, чтобы ею поделиться с другими пользователями, отправьте её с файлом <filename
>docrc</filename
> в <ulink url="http://quanta.sf.net/main1.php?contfile=resource"
>репозиторий &quantaplus;</ulink
>. Вы не станете богатым, но вы сможете гордиться тем, что содействовали разработке самого лучшего инструмента веб-разработки в мире. </para>

</sect1>
</chapter>
