Christopher Hornbaker

chrishornbaker@earthlink.net

András Mantia

amantia@kde.org

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

shafff@ukr.net

Перевод на русский Эта глава описывает процесс расширения базовых возможностей &quantaplus; для ваших нужд и как вы можете содействовать её развитию. &DTEP; используются в &quantaplus; для поддержки языков разметки, сценариев и &CSS;. Они позволяют обеспечить такие функции как автозавершение, редактирование тегов. Их простота и надёжность делает &quantaplus; быстрой, дружественной средой для веб-разработчиков. &DTEP; делятся на две семьи - разметочную (далее - семья 1) и сценарную с &CSS; (далее - семья 2). &DTEP; состоит из двух частей - каталога тегов и панелей инструментов. Каталог тегов состоит из файла описания description.rc и файла TagXML с расширением .tag. Панель инструментов - это набор кнопок со значками (над окном редактирования), каждая из которых соответствует какому-либо тексту, вставляемому в документ при нажатии на неё (часто это шаблон тега). &DTEP; можно создать самому вручную (см. ниже), загрузить или создать автоматически из DTD. Такое преобразование описано в . В этой части описывается создание файлов TagXML, &descriptionrc; и панелей инструментов. В общем, &DTEP;. Файлы TagXML (.tag) определяют атрибуты, специфичные для данного тега и содержимое диалога "Свойства тега". Файл &descriptionrc; содержит правила и данные о &DTEP;. Панели инструментов позволяют быстро обратиться к тому или иному тегу для вставки его в документ. Каталоги тегов - это обычные каталоги, содержащие файлы &descriptionrc; и TagXML. В их названии отражается название языка разметки с его версией (например, html-4.01-strict) Таблица содержит список элементов, определённых в 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. Может встречаться только один раз. Содержит определение нескольких тегов. Родительские элементы Дочерние элементы НЕТ tag Название определяемого тега. Родительские элементы Дочерние элементы TAGS label, attr, stoppingtags АтрибутТипЗначения По умолчаниюUseОписание namestring requiredНазвание определяемого тега. singleboolean optionalТребуется ли закрывающий тег </имя_тега >. typestringxmltag optionalТип определяемого тега. xmltag Тип тега основывается на XML (только семья 1). entity Тип тега основывается на сущности (только семья 1). property Тип тега основывается на &CSS; (только семья 2). function Тип тега - функция сценария. Если это так, <attr > становится аргументами функции (только семья 2). class Тип тега - класс сценария (только семья 2). method Тип тега - метод класса (только семья 2). returnTypestringvoid optionalТип возвращаемого значения определяемой функции (только семья 2) void Возвращаемое значение игнорируется (void). int Возвращается число (integer). float Возвращается число с плавающей точкой (floating point). long Возвращается длинное целочисленное (long integer). string Возвращается строка versionstring optionalВерсия языка, для которой тег разрешён extendsstring optionalРазрешено только если тип атрибута - "class". Имя базового класса (только семья 2). classstring optionalРазрешено только если тип атрибута - "method". Имя класса, к которому принадлежит метод (только семья 2). commonboolean optionalЕсли "yes", тег указывает группу общих атрибутов и они могут быть добавлены в любой другой тег (только семья 1). commentstring optionalстрока, выводящаяся возле имени тега в списке автозавершения Добавить в диалог метку. Её текст указывается тегом <text >. Родительские элементы Дочерние элементы tag text, location Определяет один атрибут тега. Содержит имя, тип атрибута, информацию о его отображении. Родительские элементы Дочерние элементы tag location, list, tooltip, whatsthis, textlocation АтрибутТипЗначения По умолчаниюUseОписание namestring requiredИмя определяемого атрибута. typestringinput requiredТип определяемого атрибута. input Поте текстового ввода (text field). check Логическое поле (check box). color Значение поля - цвет url Значение поля - &URL; (или локальный файл) list Значение поля - запись указанного списка. statusstringoptional requiredОбязательность аргумента (только семья 2). optional Аргумент необязателен required Аргумент обязателен implied Аргумент есть неявный. sourcestring optionalУказывает источники вариантов значений атрибута в редакторе тегов и дереве атрибутов selection Выделенный текст dcop Вывод метода dcop interfacestring optionalТребует source="dcop". Интерфейс dcop из &quantaplus;. methodstring optionalТребует source="dcop" и имени интерфейса. Имя метода, предоставляемого интерфейсом &quantaplus;. argumentsstring optionalТребует source="dcop" имени интерфейса и метода. Аргументы, передаваемые методу. Может быть пустым или "%tagname%" (имя текущего тега). Текст подсказки поля (отображается при наведении курсора на него). Поддерживается только обычный текст (т.е. нельзя использовать никакие теги). Родительские элементы Дочерние элементы attr НЕТ Текст "Что это?" для данного поля. Поддерживается только обычный текст (т.е. нельзя использовать никакие теги). Родительские элементы Дочерние элементы attr НЕТ Тег, сводящий вместе записи в списке. Может употребляться только один раз для каждого описания атрибута. Родительские элементы Дочерние элементы attr item Определяет запись в списке. Родительские элементы Дочерние элементы list НЕТ Позиция в окне свойств параметра, отвечающего атрибуту тега. Может употребляться только один раз для каждого атрибута диалога (т.е. для каждого <attr >). Не может содержать подэлементы. Родительские элементы Дочерние элементы attr НЕТ АтрибутТип UseОписание rowнеотрицательное целое requiredРяд поля или метки при отображении в окне. colнеотрицательное целое requiredСтолбец поля или метки при отображении в окне. rowspanнеотрицательное целое optionalЧисло рядов, отводимых полю. colspanнеотрицательное целое optionalЧисло столбцов, отводимых полю. Положение и размер поля в окне свойств. Может употребляться только один раз для каждого поля в диалоге (т.е. для каждого <attr > и <label >). Не может содержать подэлементы. Родительские элементыДочерние элементы label, attrНЕТ АтрибутТип UseОписание rowнеотрицательное целое requiredРяд поля или метки при отображении в окне. colнеотрицательное целое requiredСтолбец поля или метки при отображении в окне. rowspanнеотрицательное целое optionalЧисло рядов, отводимых полю. colspanнеотрицательное целое optionalЧисло столбцов, отводимых полю. Текст метки или флажка (check box). Родительские элементыДочерние элементы label, attrНЕТ Список элементов, которые могут использоваться в определяемом теге. Родительские элементыДочерние элементы tagchild Дочерний тег. Не может содержать подэлементы. Родительские элементыДочерние элементы childrenНЕТ АтрибутТипЗначения UseОписание namestring requiredТег, который может употребляться в некотором другом теге. использованиеstring optionalОтношение к родителю. required Родитель должен иметь как минимум одного потомка с этим именем. Список элементов, которые приводят к окончанию действия тега. Родительские элементыДочерние элементы tagstoppingtag Тег, приводящий к окончанию действия другого тега. Не может содержать подэлементы. Родительские элементыДочерние элементы stoppingtagsНЕТ АтрибутТип UseОписание namestring requiredТеги, приводящие к окончанию действия другого тега. Все файлы TagXML должны начинаться с декларации &XML;: <?xml version="1.0" encoding="UTF-8"?>, правильно структурированными и закрытыми. Пробелы не играют роли, однако следите за символами & и <. В элементах <tooltip >, <whatsthis >, <text >, их лучше заменить на &amp; и &lt; соответственно. Невыполнение этого не приведёт к краху, но ваша работа может пропасть. Чтобы выполнить проверку файлов TagXML, выберите Сервис, Проверить TagXML.. Эта функция пока что не реализована и проверка происходит при загрузке файлов TagXML в &quantaplus;. Ниже следует файл 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> Ниже следует файл 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> Файл &descriptionrc; также имеет простую структуру, для него есть редактор, который можно вызвать из DTDПараметры DTD.... Чтобы изменить &descriptionrc; вновь созданного &DTEP;, создайте файл &descriptionrc; со следующими параметрами: [General] Version = Пишите 1 для &quantaplus; версии <=3.1.2 и 2 - для любой более поздней версии. Name = Строка определения DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN) NickName = Красивое имя DTD. (HTML 4.01 Transitional). если не указано, будет использоваться Name. После того, как вы создали такой файл и сохранили его в папку с файлами тегов, загрузите новый &DTEP; через DTDЗагрузить пакет DTD (DTEP)..., теперь вы можете продолжить правку &DTEP;. Воспользуйтесь контекстной справкой (всплывающими подсказки и "что это?") панели инструментов редактора, или прочтите файлquanta/data/dtep/dtd-description.txt из исходного архива, в котором подробно описан формат. В &quantaplus; можно настраивать и создавать свои действия, выполняемые при нажатии на кнопку панели инструментов, выборе пункта меню или нажатии комбинации клавиш. Существует три типа действий, определяемых пользователем: Операции с текстом Операции с тегами Операции на основе сценариев Создать действие можно с помощью пункт менюНастройкаНастроить действия: Тип Текст, Тег или Сценарий. Текст Имя действия, видимое пользователю. Кнопка рядом с текстовой меткой Значок, присвоенный данному действию. Щёлкните на нём чтобы его изменить. Всплывающая подсказка Краткое описание действия. Комбинация клавиш Комбинация клавиш, присвоенная действию. Панели инструментов Панели инструментов, содержащие действие. Для подробностей см. . Расширенные настройки Параметры, специфичные для каждого типа действий. См. далее Самые простые действия. Вы можете ввести текст в области Расширенные настройки, который будет вставлен в документ при выполнении действия. Используется для вставки XML-тегов в текст. <tag> Имя тега. </tag> Если флажок отмечен, нужен также закрывающий тег. Если при вызове действия в документе будет присутствовать выделенный текст, то начальный тег будет вставлен перед ним, а закрывающий - после. Запустить диалог "Изменить тег", если он доступен Если для данного тега будет найден файл tagXML с описанием его атрибутов, перед вставкой тега будет предложено ввести их в диалоговом окне. Символы <, > и / не будут автоматически добавлены и вы должны ввести их сами. Этот тип действий - самый мощный. С помощью него можно запускать внешние приложения (в основном это сценарии), которым будет передаваться документ или его часть. Примером такого типа служит стандартный диалог &quantaplus; Быстрый запуск, различные действия, связанные с (X)HTML. Сначала нужно ввести строку запуска сценария, например: sh /home/myHome/myScript.sh. Для указания пути рекомендуется использовать %scriptdir (например: sh %scriptdir/myScript.sh). Тогда сценарий будет искаться в нескольких папках, а именно: глобальная папка сценариев: $TDEDIR/share/apps/quanta/scripts локальная папка сценариев: $TDEHOME/share/apps/quanta/scripts список путей пользователя: $PATH Есть также другие переменные: %f: адрес текущего документа. Последовательность символов "file:/" будет удалена из имени файла. %input: выделенный текст (см. далее). %projectbase: адрес текущего проекта. Если нет открытых проектов, возвращает пустую строку. %pid: PID процесса &quantaplus;. Если запущен один экземпляр &quantaplus; перед PID будет добавлено "unique ". Это может быть использовано для работы через DCOP. %userarguments: используется при событиях. Будет заменено свойствами события в следующем порядке: Первый аргумент Дескриптор (id) сценария Второй аргумент имя события Третий аргумент параметры события, обычно имя текущего файла, или путь к файлу проекта. Также сценарий может получить исходные данные напрямую от &quantaplus; через стандартный вход. В выпадающем списке Ввод вы можете выбрать данные, которые будут посылаться: Ничего. Текущий документ: весь документ. Выделенный текст. Только когда выбран этот вариант, %input имеет смысл. Аналогично, можно получить вывод сценария через конфейеры. Существует два типа вывода: обычный (stdout); ошибки (stderr). Вы можете выбрать, что делать с выводом, возможные варианты: Ничего. Вставить в позицию курсора. Заменить выделение. Заменить выделение. Создать новый документ. Заменить текущий документ. Окно сообщений: вывод сценарий будет помещён на служебную вкладку Сообщения. Варианты для вывода сообщений об ошибках такие же. Ниже следует описание создания панелей инструментов для &DTEP;. По сути, это - графические элементы, отвечающие определённому действию. Последнее - основа почти всех расширений, которые есть или будут появляться в будущем в &quantaplus;. Схема определения действия в &quantaplus; также годится для автозавершения и диалогов свойств тегов. Начнём с создания пользовательской панели инструментов: Панели инструментовДобавить пользовательскую панель инструментов. Если в языке разметки много тегов, лучше разделить их по группам. Для каждой группы создайте отдельную панель инструментов. В нашем случае тегов не много, поэтому обойдёмся одной. Далее следует добавить и настроить действия - НастройкаНастроить действия.... Нажмите кнопку Создать (внизу окна). Заполните все необходимые поля и добавьте тег в соответствующую панель инструментов. Если у тега есть атрибуты (и вы будете часто их использовать), отметьте Запустить диалог "Изменить тег", если он доступен, и каждый раз при использовании данного действия, будет предложено заполнить свойства добавляемого тега. Теперь у вас должно быть что-то вроде этого. Нажмите кнопку Применить. Но что же получилось?! Как вы запомните, какой значок к какому действию относится? Давайте заменим его на свой (покрасивее). Для создания значка можно использовать &kiconedit;. Запустите её из &kmenu;, ГрафикаДополнительные приложения) &kiconedit; создаёт значки с расширением 32x32, однако нам нужно 22x22 - Правка Изменить размер . Помните, что вы создаёте значок, который поможет вспомнить вам (и не только вам) действие, которому он отвечает, а не просто красивую картинку. В нашем случае создаётся значок для тега <start >,поэтому для него будет использоваться зелёный цвет. Сохраним значок. После создания значка нужно ассоциировать его с действием. Откройте окно Настроить действия и выберите нужное действие. Слева от поля Текст есть кнопка - нажмите её. Выберите Прочие пиктограммы и нажмите кнопку Обзор. Перейдите в папку, в которой вы сохранили значок, выберите его и нажмите OK. Нажмите кнопку Применить > или OK. Чтобы добавить какие-то общие для &quantaplus; функции на панель инструментов, или разделители кнопок, в окне Настроить панели инструментов выделите нужную панель инструментов и выберите в списке слева действие (или разделитель). Например, можно добавить Просмотр в Konqueror. Обратите внимание на то, что разделитель способствует группированию. Один человек подумал, что кнопка &konqueror;, стоящая рядом с зелёной кнопкой "Старт", имеет противоположное значение ("Стоп"). После внесения изменений, нажмите кнопку OK. Посмотрите на новую панель инструментов! Фантастика! Не забудьте протестировать вашу новую панель инструментов нажатием всех расположенных на ней кнопок. Панели инструментов Сохранить Сохранить как локальную панель инструментов. Сохраните её в правильной папке. Убедитесь, что вы заполнили &descriptionrc; так, чтобы при открытии документа данного типа, загружались соответствующие панели инструментов. Robert Nickel

robert@artnickel.com

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

shafff@ukr.net

Перевод на русский Самое заметное, что может сделать рядовой пользователь - дополнение документации по разметочному или скриптовому языку, который ему нравится. Далее описывается, как было создано дерево документации &PHP;. Перед началом написания проверьте репозиторий &quantaplus;. Первый шаг - получение существующей документации. Второй - создание файла docrc. Общая форма docrc: #KDE Config File [Tree] Doc dir=путь (относительно к этому файлу) к файлам html ⪚ php42/ #top level elements Top Element=Описание документации ⪚ &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 или $TDEDIR/share/apps/quanta/doc для локального или глобального использования соответственно. Затем создайте папку (как указано в файле docrc) в той же папке с docrc и скопируйте в неё страницы &HTML;. Перезапустите &quantaplus; чтобы увидеть добавленную документацию. После того, как вы убедитесь, что она годится для того, чтобы ею поделиться с другими пользователями, отправьте её с файлом docrc в репозиторий &quantaplus;. Вы не станете богатым, но вы сможете гордиться тем, что содействовали разработке самого лучшего инструмента веб-разработки в мире. С &quantaplus; вы не будете жадным одиночкой, с её помощью можно делиться разными расширениями (пакетами DTEP, панелями инструментов с действиями, сценариями, шаблонами) друг с другом. Есть два способа этого: Отправка по Email Расширения (называемые также ресурсами) можно посылать по электронной почте. Для этого в нескольких (в т.ч. контекстных) меню есть пункт Отправить по E-Mail.... Публикация на главном сервере Если вы хотите поделиться своими расширениями со всеми, опубликуйте их в центральном хранилище. Присланные ресурсы проверяются и действительно публикуются только если они могут быть полезны другим. Для публикации, ресурс нужно подписать ключом GPG/PGP. О том, как загружать расширения с центрального хранилища, обратитесь к разделу . Во время передачи вам нужно будет ввести пароль к своему ключу GPG (он не будет сохранён), выбрав его перед этим. В диалоге Опубликовать заполните все поля (URL для просмотра можно оставить пустым) и нажмите OK. Данный диалог можно открыть из DTDПередать пакет DTD (DTEP)..., Панели инструментовПередать панель инструментов..., контекстных меню файлов и папок в деревьях шаблонов и сценариев. На сайте &quantaplus; есть специальный раздел, в котором хранятся расширения, не вошедшие в основной дистрибутив из-за большого размера или редкого использования, или же они были опубликованы после выхода послежней версии программы. Такие ресурсы содержат в себе механизм автоматической установки. Чтобы получить к ним доступ, воспользуйтесь пунктом меню Загрузить, его можно найти в разных местах, например в DTDЗагрузить пакет DTD (DTEP)..., Панели инструментовЗагрузить панель инструментов..., в контекстных меню пустых областей или в корнях деревьев Шаблоны, Сценарии и Документация. Перед непосредственной установкой расширения, &quantaplus; проверяет контрольную сумму и подпись. Устанавливайте расширения, особенно панели инструментов и сценарии, только из проверенных источников! Добавление поддержки языков разметки, основанных на XML, автоматизировано, и пакет DTEP создаётся на основе DTD. DTDЗагрузить и конвертировать DTD..., выберите файл .dtd, содержащий определение DTD, после чего вы увидите следующее окно: Доступные поля: Конечная папка: папка, в которую будут записаны данные создаваемого &DTEP;, будет расположена в $TDEHOME/share/apps/quanta/dtep. Имя: строка определения DTD Отображаемое имя: имя, видимое пользователю. Строка описания !DOCTYPE: строка, которая должна присутствовать в теге !DOCTYPE, например HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd" DTD URL: Адрес файла DTD Расширение по умолчанию: расширение, которое обычно имеют файлы с данным DTD Теги и атрибуты с учётом регистра: обычно включено для языков, основанных на XML Настроить DTEP после преобразования: запустить редактор &descriptionrc; после завершения преобразования, чтобы вы могли проверить/настроить созданный &DTEP;.