# Расширение &quantaplus;

Christopher
Hornbaker

    chrishornbaker@earthlink.net

Николай
Шафоростов

    shafff@ukr.net

перевод на русский

# Расширение &quantaplus;

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

## Пакеты типов документов (Document Type Editing Package, &DTEP;)

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

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

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

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

### Создание пакетов

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

### TagXML

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

Элемент | Использование по умолчанию | Частное использование
--- | --- | ---
TAGS | required | always
tag | required | always
label | optional | обязательно для диалога "Свойства"
attr | optional | обязательно для определения атрибута
tooltip | optional | обязательно для подсказок в диалоге "Свойства"
whatsthis | optional | обязательно для возможности отображения краткой справки Что это?
list | optional | обязательно если attr имеет тип list
item | optional | обязательно если используется <list >
textlocation | optional | always
location | optional | обязательно если используется метка
text | optional | обязательно если используется метка
children | optional | список тегов, которые могут использоваться в определяемом
child | required | дочерний элемент
stoppingtags | optional | список тегов, которые приводят к окончанию действия другого тега
stoppingtag | required | тег, который приводит к окончанию действия другого тега

#### Описания элементов TagXML

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

##### TAGS

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

Родительские элементы | Дочерние элементы
--- | ---
НЕТ | tag

##### tag

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

Родительские элементы | Дочерние элементы
--- | ---
TAGS | label, attr, stoppingtags

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

##### label

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

Родительские элементы | Дочерние элементы
--- | ---
tag | text, location

##### attr

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

Родительские элементы | Дочерние элементы
--- | ---
tag | location, list, tooltip, whatsthis, textlocation

Атрибут | Тип | Значения | По умолчанию | Use | Описание
--- | --- | --- | --- | --- | ---
name | string |  |  | required | Имя определяемого атрибута.
type | string |  | input | required | Тип определяемого атрибута.
|  | input |  |  | Поте текстового ввода (text field).
|  | check |  |  | Логическое поле (check box).
|  | color |  |  | Значение поля - цвет
|  | url |  |  | Значение поля - &URL; (или локальный файл)
|  | list |  |  | Значение поля - запись указанного списка.
status | string |  | optional | required | Обязательность аргумента (только семья 2).
|  | optional |  |  | Аргумент необязателен
|  | required |  |  | Аргумент обязателен
|  | implied |  |  | Аргумент есть неявный.

##### tooltip

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

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

Родительские элементы | Дочерние элементы
--- | ---
attr | НЕТ

##### whatsthis

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

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

Родительские элементы | Дочерние элементы
--- | ---
attr | НЕТ

##### list

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

Родительские элементы | Дочерние элементы
--- | ---
attr | item

##### item

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

Родительские элементы | Дочерние элементы
--- | ---
list | НЕТ

##### textlocation

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

Родительские элементы | Дочерние элементы
--- | ---
attr | НЕТ

Атрибут | Тип | Use | Описание
--- | --- | --- | ---
row | неотрицательное число | required | Ряд поля или метки при отображении в окне.
col | неотрицательное число | required | Столбец поля или метки при отображении в окне.
rowspan | неотрицательное число | optional | Число рядов, отводимых полю.
colspan | неотрицательное число | optional | Число столбцов, отводимых полю.

##### location

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

Родительские элементы | Дочерние элементы
--- | ---
label, attr | НЕТ

Атрибут | Тип | Use | Описание
--- | --- | --- | ---
row | неотрицательное число | required | Ряд поля или метки при отображении в окне.
col | неотрицательное число | required | Столбец поля или метки при отображении в окне.
rowspan | неотрицательное число | optional | Число рядов, отводимых полю.
colspan | неотрицательное число | optional | Число столбцов, отводимых полю.

##### text

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

Родительские элементы | Дочерние элементы
--- | ---
label, attr | НЕТ

##### children

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

Родительские элементы | Дочерние элементы
--- | ---
tag | child

##### child

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

Родительские элементы | Дочерние элементы
--- | ---
children | НЕТ

Атрибут | Тип | Use | Описание
--- | --- | --- | ---
name | string | required | Тег, который может употребляться в некотором другом теге.

##### stoppingtags

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

Родительские элементы | Дочерние элементы
--- | ---
tag | stoppingtag

##### stoppingtag

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

Родительские элементы | Дочерние элементы
--- | ---
stoppingtags | НЕТ

Атрибут | Тип | Use | Описание
--- | --- | --- | ---
name | string | required | Теги, приводящие к окончанию действия другого тега.

#### Использование TagXML

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

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

#### Проверка TagXML

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

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

#### Примеры TagXML

##### Семья 1

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

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

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

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

      <label>
       <text
    >xmlns</text>
       <location col="0" row="3"/>
      </label>
      <attr name="xmlns" type="input">
       <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.</tooltip>
       <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.</whatsthis>
       <location col="1" row="3"/>
      </attr>

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

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

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

      <label>
       <text
    >finalDefault</text>
       <location col="0" row="7"/>
      </label>
      <attr name="finalDefault" type="input">
       <location col="1" row="7"/>
      </attr>
     </tag>
    </TAGS>

##### Семья 2

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

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE tags>
    <tags>
      <tag name="overload" type="function" returnType="void">
    <attr name="class_name" type="string" status="optional"/>
      </tag>
    </tags>

### description.rc

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

#### Структура для семьи 1

    [General] - Общая информация.
    Version = Пишите 1 для &quantaplus; версии <=3.1.2 и 2 — для любой более поздней версии.
    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: <tag booleanAttr
    >.
    Пример complex: <tag booleanAttr="1"
    > или <tag booleanAttr="true">
    Single Tag Style = (html|XML)
    Пример непарного тега html: <single_tag>
    Пример непарного тега XML:  <single_tag />
    StructGroupsCount = Количествоe структурных групп. См. ниже.
    MinusAllowedInWords = Если true, "this-is-a-word" рассматривается как одно слово. Иначе — как 4.
    TagAutoCompleteAfter = CHAR. Раскрывать список автодополнения после ввода символа CHAR
    или нажатия пробела когда курсор ввода перед ним. Для семьи 1,
    это обычно "<". "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 другой семьи, комментариями.
    Например <!-- -->
    SpecialAreaNames = Разделённый запятыми список названий спец. областей (например comment)
    SpecialTags = tagname(attributename) - Тег, начинающий специальную область.
    MayContain = Разделённый запятыми список DTEP семьи 2, которые могут
    присутствовать в документе (php, css).

#### Структура для семьи 2

    г
    [General] - Общая информация.
    Version = Пишите 1 для &quantaplus; версии <=3.1.2 и 2 — для любой более поздней версии.
    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: <tag booleanAttr
    >.
    Пример complex: <tag booleanAttr="1"
    > или <tag booleanAttr="true">
    Single Tag Style = (html|XML)
    Пример непарного тега html: <single_tag>
    Пример непарного тега XML:  <single_tag />
    StructGroupsCount = Количествоe структурных групп. См. ниже.
    MinusAllowedInWords = Если true, "this-is-a-word" рассматривается как одно слово. Иначе — как 4.
    TagAutoCompleteAfter = CHAR. Открывать список автодополнения после ввода символа CHAR
    или нажатия пробела когда курсор ввода перед ним. Для семьи 1,
    это обычно "<". "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 другой семьи, комментариями.
    Например <!-- -->
    SpecialAreaNames = Разделённый запятыми список названий спец. областей (например comment)
    SpecialTags = tagname(attributename) - Тег, начинающий специальную область.
    AreaBorders = Разделённый запятыми список границ областей, обрамляющих эту семью 2. В случае
    PHP, это: <? ?>, <* *
    >, <% %>
    Tags = имя_тега(attribute). Если (существующий) родительский DTD имеет тег имя_тега
    и значение параметра attribute равно названию DTD, область тега
    анализируется в соответствии с правилами этого DTD.
    Comments = Разделённый запятыми список границ области комментариев. EOL означает конец строки.
    Например: // EOL, /* */
    StructKeywords = Разделённый точками с запятыми ключевых слов структуры.StructBeginStr = Строка, указывающая на начало структуры (например "{")
    StructEndStr = Строка, указывающая на конец структуры (например })
    StructRx = Регулярное выражение, содержащее начало или  конец этой структуры
    Например. \\{ | \\} (границей структуры может быть { и })

## Создание панелей инструментов

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

### С нуля до совершенства

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

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

Далее следует добавить и настроить действия - Настройка Настроить действия....

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

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

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

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

Нажмите кнопку Применить.

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

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

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

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

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

Сохраним значок.

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

Выберите Прочие пиктограммы и нажмите кнопку Обзор.

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

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

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

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

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

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

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

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

Панели инструментов Сохранить Сохранить как локальную панель инструментов.

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

## Написание документации

Robert
Nickel

    robert@artnickel.com

Николай
Шафоростов

    shafff@ukr.net

перевод на русский

## Написание документации

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

Перед началом написания проверьте репозиторий &quantaplus;.

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

Общая форма docrc:

    #KDE Config File
    [Tree]
    Doc dir=путь (относительно к этому файлу) к файлам html &eg; php42/
    #top level elements
    Top Element=Описание документации &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

Файл `docrc` разделён на две секции - Tree и Context.

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

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

    #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
    ...

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

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

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

Секция Context используется контекстно зависимой справки. Например, вы пишите скрипт &PHP; и вам нужно просмотреть документацию по функции `mysql_fetch_array`. Для этого вам нужно будет выделить её название и нажать &Ctrl;H . При этом отобразится сразу информация по этой функции.

ContextList

  Разделённый запятыми список контекстных пунктов, по которым будет доступна контекстная справка (для &PHP; - это его функции).

Ссылки на файлы контекстной справки

  Формат: "контекстный пункт=страница html". Например: acos=function.acos.html

Готовая версия `docrc`:

    #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
    ...

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

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

После того, как вы убедитесь, что она годится для того, чтобы ею поделиться с другими пользователями, отправьте её с файлом `docrc` в репозиторий &quantaplus;. Вы не станете богатым, но вы сможете гордиться тем, что содействовали разработке самого лучшего инструмента веб-разработки в мире.