You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1626 lines
44 KiB
1626 lines
44 KiB
<?xml version="1.0" encoding="UTF-8" ?>
|
|
|
|
<chapter id="extending-quanta-3-2">
|
|
<chapterinfo>
|
|
<title>Extending &quantaplus;</title>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Christopher</firstname>
|
|
<surname>Hornbaker</surname>
|
|
<affiliation>
|
|
<address><email>chrishornbaker@earthlink.net</email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
|
|
</authorgroup>
|
|
</chapterinfo>
|
|
|
|
<title>Extending &quantaplus;</title>
|
|
|
|
<para>
|
|
This chapter describes how to customize &quantaplus; to your particular
|
|
needs and how you can help &quantaplus; become better.
|
|
</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>
|
|
Document Type Editing Packages (&DTEP;s) are used in &quantaplus; to add
|
|
support for markup, scripting languages, and &CSS;. They allow
|
|
&quantaplus; to provide features like auto-completion and node trees.
|
|
Their simplicity and flexibility are what make &quantaplus; a fast,
|
|
developer friendly &IDE; for web developers. They are what make &quantaplus;
|
|
an easy-to-use, productive environment.
|
|
</para>
|
|
|
|
<para>
|
|
&DTEP;s come in two flavors, Family 1, which are markups, and Family 2,
|
|
which are scripting and &CSS;. &DTEP;s are made up of two parts, the Tag
|
|
Folder and the Toolbars. Tag Folders are composed of two types of files,
|
|
the description.rc and TagXML files, which carry the extension .tag.
|
|
Toolbars are the handy, icon-oriented tabs of buttons (above the editing
|
|
window) which place text into a document faster than the user can type.
|
|
</para>
|
|
|
|
<para>
|
|
This document describes how to make TagXML files, the description.rc, and
|
|
toolbars. In short, a &DTEP;.
|
|
</para>
|
|
|
|
<para>
|
|
TagXML files (.tag) define both the attributes specific to a tag and the
|
|
layout and contents of the properties dialog &quantaplus; shows for the tag.
|
|
The description.rc file provides rules and information on the &DTEP;
|
|
itself. Toolbars provide a quick means for adding tags into a document
|
|
without worry of mis-spellings and such.
|
|
</para>
|
|
|
|
<sect2 id="dtep-packaging-3-2">
|
|
<title>Packaging</title>
|
|
|
|
<para>
|
|
Tag Folders are just that, folders. They are composed only of the
|
|
description.rc and TagXML files. Tag Folders carry the name of the mark-up
|
|
language and version, if applicable. (For example, html-4.01-strict)
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="tagxml-3-2">
|
|
<title>TagXML</title>
|
|
|
|
<para>
|
|
The table below lists the elements defined in TagXML and declares whether
|
|
they are required or not. While not all are required, it is recommended
|
|
that you use as many as you can so that other users can have a better
|
|
experience and more information to work with.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Element</entry>
|
|
<entry>Default Usage</entry>
|
|
<entry>Case Usage</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>required to create a properties dialog</entry>
|
|
</row>
|
|
<row>
|
|
<entry>attr</entry>
|
|
<entry>optional</entry>
|
|
<entry>required to define an attribute</entry>
|
|
</row>
|
|
<row>
|
|
<entry>tooltip</entry>
|
|
<entry>optional</entry>
|
|
<entry>required to have the properties dialog display a tooltip</entry>
|
|
</row>
|
|
<row>
|
|
<entry>whatsthis</entry>
|
|
<entry>optional</entry>
|
|
<entry>required to have the properties dialog display a <quote>What's This
|
|
</quote></entry>
|
|
</row>
|
|
<row>
|
|
<entry>list</entry>
|
|
<entry>optional</entry>
|
|
<entry>required when an attr is of the type <quote>list</quote></entry>
|
|
</row>
|
|
<row>
|
|
<entry>item</entry>
|
|
<entry>optional</entry>
|
|
<entry>required when <list> is used</entry>
|
|
</row>
|
|
<row>
|
|
<entry>textlocation</entry>
|
|
<entry>optional</entry>
|
|
<entry>always</entry>
|
|
</row>
|
|
<row>
|
|
<entry>location</entry>
|
|
<entry>optional</entry>
|
|
<entry>required when label is used</entry>
|
|
</row>
|
|
<row>
|
|
<entry>text</entry>
|
|
<entry>optional</entry>
|
|
<entry>required when label is used</entry>
|
|
</row>
|
|
<row>
|
|
<entry>children</entry>
|
|
<entry>optional</entry>
|
|
<entry>list of tags that can appear within the tag being defined</entry>
|
|
</row>
|
|
<row>
|
|
<entry>child</entry>
|
|
<entry>required</entry>
|
|
<entry>a children entry</entry>
|
|
</row>
|
|
<row>
|
|
<entry>stoppingtags</entry>
|
|
<entry>optional</entry>
|
|
<entry>list of tags that tell another tag to end</entry>
|
|
</row>
|
|
<row>
|
|
<entry>stoppingtag</entry>
|
|
<entry>required</entry>
|
|
<entry>a stoppingtags entry</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
|
|
<sect3 id="dtep-element-descriptions-3-2">
|
|
<title>TagXML Element Descriptions</title>
|
|
|
|
<para>
|
|
The following sections will describe, in detail, each element. Everything
|
|
from where they can go to what goes in them is layed out in an
|
|
easy-to-follow manner.
|
|
</para>
|
|
|
|
<sect4 id="TAGS-3-2">
|
|
<title>TAGS</title>
|
|
|
|
<para>
|
|
This is the root element of a TagXML document. It may appear in a document
|
|
only once. It can contain the definition of multiple tags. This is an
|
|
element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis>NONE</emphasis></entry>
|
|
<entry>tag</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="tag-3-2">
|
|
<title>tag</title>
|
|
|
|
<para>
|
|
Wrapper for tag being defined. This is an element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>TAGS</entry>
|
|
<entry>label, attr, stoppingtags</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informaltable>
|
|
<tgroup cols="6">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry><entry>Type</entry><entry>Values</entry>
|
|
<entry>Default</entry><entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>name</entry><entry>string</entry><entry></entry><entry></entry>
|
|
<entry>required</entry><entry>Specifies the name of the tag being defined.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>single</entry><entry>boolean</entry><entry></entry><entry></entry>
|
|
<entry>optional</entry><entry>Specifies whether or not the tag requires a
|
|
closing tag </(tagname)>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>type</entry><entry>string</entry><entry></entry><entry>xmltag</entry>
|
|
<entry>optional</entry><entry>Specifies the type of tag being defined.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>xmltag</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag is XML-based. (Family 1 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>property</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag is &CSS; related. (Family 2 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>function</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag is a script function. When used,
|
|
<attr> becomes arguments of the function. (Family 2 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>class</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag is a script class. (Family 2 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>returnType</entry><entry>string</entry><entry></entry><entry>void
|
|
</entry>
|
|
<entry>optional</entry><entry>Specifies the return type of tag being
|
|
defined. (Family 2 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>void</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag returns void.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>int</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag returns int.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>float</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag returns float.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>long</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag returns long.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>string</entry><entry></entry>
|
|
<entry></entry><entry>Type of tag returns string.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="label-3-2">
|
|
<title>label</title>
|
|
|
|
<para>
|
|
Place a label in the dialog. The text is specified by the <text> tag.
|
|
This is an element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</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>
|
|
Defines an attribute of the tag. This element occurs once for each
|
|
attribute. It defines the name and type of attribute. It also contains
|
|
additional tags that specify how this attribute should be displayed, et cetera.
|
|
This is an element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</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>Attribute</entry><entry>Type</entry><entry>Values</entry>
|
|
<entry>Default</entry><entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>name</entry><entry>string</entry><entry></entry><entry></entry>
|
|
<entry>required</entry><entry>Specifies the name of the attribute being
|
|
defined.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>type</entry><entry>string</entry><entry></entry><entry>input</entry>
|
|
<entry>required</entry><entry>Specifies the type of the attribute being
|
|
defined.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>input</entry><entry></entry>
|
|
<entry></entry><entry>Field supports free text entries (text field).</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>check</entry><entry></entry>
|
|
<entry></entry><entry>Field value is boolean (check box).</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>color</entry><entry></entry>
|
|
<entry></entry><entry>Field value is a color.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>url</entry><entry></entry>
|
|
<entry></entry><entry>Field value is a &URL;. (Local file to refer to.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>list</entry><entry></entry>
|
|
<entry></entry><entry>Field value is an item from a specified list.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>status</entry><entry>string</entry><entry></entry><entry>optional</entry>
|
|
<entry>required</entry><entry>Specifies whether or not the argument is
|
|
required. (Family 2 only.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>optional</entry><entry></entry>
|
|
<entry></entry><entry>Argument is optional.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>required</entry><entry></entry>
|
|
<entry></entry><entry>Argument is required.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry><entry></entry><entry>implied</entry><entry></entry>
|
|
<entry></entry><entry>Argument is implied.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="tooltip-3-2">
|
|
<title>tooltip</title>
|
|
|
|
<para>
|
|
Defines the tooltip for a field in the dialog. This element is text-only.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Currently only plain text is supported (you cannot use any markup).
|
|
</para>
|
|
</note>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>attr</entry>
|
|
<entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="whatsthis-3-2">
|
|
<title>whatsthis</title>
|
|
|
|
<para>
|
|
Defines the 'What's This' help for a field in the dialog. This element is
|
|
text-only.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Currently only plain text is supported (you cannot use any markup).
|
|
</para>
|
|
</note>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>attr</entry>
|
|
<entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="list-3-2">
|
|
<title>list</title>
|
|
|
|
<para>
|
|
A container tag that groups together the items in a list. It may appear
|
|
only once for each attribute description. This is an element-only type
|
|
element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</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>
|
|
Defines an item in a list. This element is text-only.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>list</entry>
|
|
<entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="textlocation-3-2">
|
|
<title>textlocation</title>
|
|
|
|
<para>
|
|
Specifies the position of a tag's attribute text within a dialog. This tag
|
|
can only occur once for each attribute in the dialog (&cad; one for each
|
|
<attr> tag). This element is empty.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry>
|
|
<entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>attr</entry>
|
|
<entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informaltable>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry><entry>Type</entry>
|
|
<entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>row</entry><entry>nonNegativeInteger</entry>
|
|
<entry>required</entry><entry>Specifies the row in the dialog layout of a
|
|
field or label.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>col</entry><entry>nonNegativeInteger</entry>
|
|
<entry>required</entry><entry>Specifies the column in the dialog layout of
|
|
a field or label.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
|
|
<entry>optional</entry><entry>Specifies the number of rows a field should
|
|
span.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>colspan</entry><entry>nonNegativeInteger</entry>
|
|
<entry>optional</entry><entry>Specifies the number of columns a field
|
|
should span.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="location-3-2">
|
|
<title>location</title>
|
|
|
|
<para>
|
|
Specifies the position and size of a field in the dialog. This tag should
|
|
occur once for each field in the dialog (&cad; one for each <attr> and
|
|
<label> tag). This element is empty.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>label, attr</entry><entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informaltable>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry><entry>Type</entry>
|
|
<entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>row</entry><entry>nonNegativeInteger</entry>
|
|
<entry>required</entry><entry>Specifies the row in the dialog layout of a
|
|
field or label.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>col</entry><entry>nonNegativeInteger</entry>
|
|
<entry>required</entry><entry>Specifies the column in the dialog layout of
|
|
a field or label.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
|
|
<entry>optional</entry><entry>Specifies the number of rows a field should
|
|
span.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>colspan</entry><entry>nonNegativeInteger</entry>
|
|
<entry>optional</entry><entry>Specifies the number of columns a field
|
|
should span.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="text-3-2">
|
|
<title>text</title>
|
|
|
|
<para>
|
|
Define the text for a label or check box. This element is text-only.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>label, attr</entry><entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="children-3-2">
|
|
<title>children</title>
|
|
|
|
<para>
|
|
Defines a list of elements that can appear within the tag being specified.
|
|
This element is an element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</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>
|
|
Defines a child tag. This element is empty.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>children</entry><entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informaltable>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry><entry>Type</entry>
|
|
<entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>name</entry><entry>string</entry>
|
|
<entry>required</entry><entry>Specifies a tag that can appear within the a
|
|
certain tag.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
|
|
<sect4 id="stoppingtags-3-2">
|
|
<title>stoppingtags</title>
|
|
|
|
<para>
|
|
Defines a list of elements that force a tag to end. This element is an
|
|
element-only type element.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</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>
|
|
Defines a stopping tag. This element is empty.
|
|
</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Parent(s)</entry><entry>Children</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>stoppingtags</entry><entry><emphasis>NONE</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<informaltable>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Attribute</entry><entry>Type</entry>
|
|
<entry>Use</entry><entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>name</entry><entry>string</entry>
|
|
<entry>required</entry><entry>Specifies which tags force the ending of
|
|
another tag.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 id="tagxml-usage-3-2">
|
|
<title>TagXML Usage</title>
|
|
|
|
<para>
|
|
All TagXML files must begin with the &XML; declaration: <?xml
|
|
version="1.0" encoding="UTF-8"?> and must be properly nested and closed.
|
|
</para>
|
|
|
|
<important>
|
|
<para>
|
|
White space does not adversely affect anything, but watch out for & and
|
|
< characters. These should likely be replaced with an &amp; and
|
|
&lt;, respectively, in elements such as <tooltip>, <whatsthis>,
|
|
and <text>. Not doing so will not cause a crash, but you will have
|
|
chunks of your work disappear if you do not.
|
|
</para>
|
|
</important>
|
|
</sect3>
|
|
|
|
<sect3 id="tagxml-validation-3-2">
|
|
<title>TagXML Validation</title>
|
|
|
|
<para>
|
|
To validate your TagXML files, simply click the <quote>Tools</quote>
|
|
pop-up dialog at the top of &quantaplus; and select <quote>Validate
|
|
TagXML.</quote> A dialog will present itself and you need only to follow
|
|
the simple directions.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
This feature is currently not present. Currently validation occurs when
|
|
the TagXML files are loaded into &quantaplus;.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
|
|
<sect3 id="tagxml-examples-3-2">
|
|
<title>TagXML Examples</title>
|
|
|
|
<sect4 id="family-one-3-2">
|
|
<title>Family 1</title>
|
|
|
|
<para>
|
|
The following will show you a valid Family 1 TagXML file. This file
|
|
happens to describe &W3C; &XML; Schema's <schema> element. The file name
|
|
for this TagXML file would be schema.tag. Simple, eh?
|
|
</para>
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
<markup>
|
|
<?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>
|
|
</markup>
|
|
</literallayout>
|
|
</informalexample>
|
|
</sect4>
|
|
|
|
<sect4 id="family-two-3-2">
|
|
<title>Family 2</title>
|
|
|
|
<para>
|
|
The following will show you a valid Family 2 TagXML file. This file
|
|
happens to describe &PHP;'s overload function. The file name for this
|
|
TagXML file would be overload.tag.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
<markup>
|
|
<?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>
|
|
</markup>
|
|
</literallayout>
|
|
</informalexample>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="descriptionrc-3-2">
|
|
<title>description.rc</title>
|
|
|
|
<para>
|
|
The description.rc file is, also, quite simple. Not all of the following
|
|
need be used. The basic structure of the description.rc file is as
|
|
follows.
|
|
</para>
|
|
|
|
<sect3 id="family-one-structure-3-2">
|
|
<title>Family 1 Structure</title>
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
<markup>
|
|
[General] - Generic information.
|
|
Version = Use 1 for &quantaplus; version <=3.1.2 and 2 for any version greater.
|
|
Name = DTD definition string. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
|
|
NickName = The beautified name of the DTD. (HTML 4.01 Transitional). If not defined, Name is
|
|
used as NickName.
|
|
&URL; = &URL; pointing to the DTD definition. (http://www.w3.org/TR/html4/loose.dtd)
|
|
DoctypeString = The string that should appear in the !DOCTYPE declaration.
|
|
(HTML PUBLIC "-//&W3C;//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
|
|
Inherits = The name of the DTD from where this DTD inherits its tags. (-//&W3C;//DTD HTML 4.01//EN)
|
|
DefaultExtension = New files are created with this extension. (html)
|
|
Groups = The list of common attribute groups, which may be present in more than one tag.
|
|
(Core, I18n, Script) See below. (Group1, Group2...)
|
|
NumOfPages = How many pages does a tag dialog have, aside of the page containing the
|
|
attributes defined in the tag file? See below. (Page1,...)
|
|
CaseSensitive = Case-sensitiveness of the DTD. (true|false)
|
|
Family = 1This type of DTEP is of family 1, since it is a markup.
|
|
|
|
[Toolbars] - Information about DTEP toolbars.
|
|
Location = The folder name inside $TDEDIR($TDEHOME)/share/apps/quanta/toolbars
|
|
where the toolbars for this DTEP are.
|
|
Names = The list of toolbar file names, minus the .toolbar.tgz extension, that
|
|
are loaded for this DTEP from the above folder.
|
|
|
|
[Group1] - Replace with one of the Groups listed below.
|
|
Attributes = The list of attributes for this group. Currently, all of the listed attributes are
|
|
treated as strings.
|
|
Example:
|
|
[Core]
|
|
Attributes = id, class, style, title
|
|
|
|
[Page1] - Description of a tag editor page.
|
|
Title = The title of this page in the tag editing dialog.
|
|
Groups = List of groups appearing on this page. (Core, I18n)
|
|
|
|
[Extra rules] - Some rules not fitted in other places.
|
|
BooleanAttributes = (simple|complex)
|
|
Example for simple: <tag booleanAttr>.
|
|
Example for complex: <tag booleanAttr="1"> or <tag booleanAttr="true">
|
|
Single Tag Style = (html|XML)
|
|
Example for html: <single_tag>
|
|
Example for XML: <single_tag />
|
|
StructGroupsCount = The number of structure groups. See below.
|
|
MinusAllowedInWords = If true "this-is-a-word" is treated like a word. Otherwise,
|
|
it is treated like 4 words.
|
|
TagAutoCompleteAfter = CHAR. The auto-completion box is brought up automatically
|
|
once this CHAR is entered or SPACE is pressed after this CHAR. For DTEP family 1,
|
|
it is usually "<" The text "none" instead of a CHAR specifies that the tag
|
|
completion box should not be brought up automatically, only if the user requests it.
|
|
AttributeSeparator = CHAR. This CHAR means that the attribute name has ended.
|
|
It is " for XML DTEPs.
|
|
TagSeparator = CHAR. Similar to the above.
|
|
|
|
[StructGroup_1] - Definition of structure group 1.
|
|
Name = The text that appears if there are tags matching this group settings.
|
|
No_Name = The text that appears if there are NO tags matching this group settings.
|
|
Icon = The name of the icon appearing before the above texts.
|
|
Tag = tagname(attribute1, attribute2, ...). Tags with name tagname will appear
|
|
under this group. The item text will be "attribute1_value | attribute2_value | ..."
|
|
Currently only one tag may be listed here.
|
|
HasFileName = (true|false) True, if the item text (above attribute values) contains a file name.
|
|
FileNameRx = Regular expression used to remove the unnecessary chars from the item text.
|
|
|
|
[Parsing rules] - Rules used when parsing the document.
|
|
SpecialAreas = The beginning and ending string of special areas, separatted by a comma.
|
|
Special areas are not parsed according to this DTEP's rules, but as their own rules.
|
|
A special area can be a DTEP of another family, a comment, or something to that effect.
|
|
Eg. <!-- -->
|
|
SpecialAreaNames = Comma separated list of the above special area names. Eg. comment
|
|
SpecialTags = tagname(attributename) - Specifies a tag which defines the start of a special area.
|
|
MayContain = Comma separated list of family 2 DTEPs that can be present in the document.
|
|
(php, css)
|
|
</markup>
|
|
</literallayout>
|
|
</informalexample>
|
|
</sect3>
|
|
|
|
<sect3 id="family-two-structure-3-2">
|
|
<title>Family 2 Structure</title>
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
<markup>
|
|
[General] - Generic information.
|
|
Version = Use 1 for &quantaplus; version <=3.1.2 and 2 for any version greater.
|
|
Name = Proper name
|
|
NickName = What every calls it. If not defined, Name is used as NickName.
|
|
Inherits = The name of the DTEP from where this DTEP inherits tags. (The Name, not NickName)
|
|
DefaultExtension = New files are created with this extension. (php)
|
|
NumOfPages = 0 Always zero because there is not a tag editing dialog for
|
|
Family 2 DTEPs.
|
|
CaseSensitive = Case-sensitiveness of the DTEP. (true|false)
|
|
Family = 2This type of DTEP is of family 2, since it is not markup.
|
|
|
|
[Toolbars] - Information about DTEP toolbars.
|
|
Location = The folder name inside $TDEDIR($TDEHOME)/share/apps/quanta/toolbars
|
|
where the toolbars for this DTEP are.
|
|
Names = The list of toolbar file names, minus the .toolbar.tgz extension, that
|
|
are loaded for this DTEP from the above folder.
|
|
|
|
[Extra rules] - Some rules not fitted in other places.
|
|
BooleanAttributes = (simple|complex)
|
|
Example for simple: <tag booleanAttr>.
|
|
Example for complex: <tag booleanAttr="1"> or <tag booleanAttr="true">
|
|
StructGroupsCount = The number of structure groups. See below.
|
|
MinusAllowedInWords = If true "this-is-a-word" is treated like a word. Otherwise,
|
|
it is treated like 4 words.
|
|
TagAutoCompleteAfter = CHAR. The auto-completion box is brought up automatically
|
|
once this CHAR is entered or SPACE is pressed after this CHAR. For DTEP family 1,
|
|
it is usually "<" The text "none" instead of a CHAR specifies that the tag
|
|
completion box should not be brought up automatically, only if the user requests it.
|
|
AttributeSeparator = CHAR. This CHAR means that the attribute name has ended.
|
|
It is " for XML DTEPs.
|
|
TagSeparator = CHAR. Similar to the above.
|
|
AttributeAutoCompletionAfter = CHAR. Similar to the TagAutoCompletionAfter, but
|
|
for tag attributes. It is "(" by default and ":" for CSS.
|
|
|
|
[StructGroup_1] - Definition of structure group 1.
|
|
Name = The text that appears if there are tags matching this group settings.
|
|
No_Name = The text that appears if there are NO tags matching this group settings.
|
|
Icon = The name of the icon appearing before the above texts.
|
|
Tag = tagname(attribute1, attribute2, ...). Tags with name tagname will appear
|
|
under this group. The item text will be "attribute1_value | attribute2_value | ..."
|
|
Currently only one tag may be listed here.
|
|
HasFileName = (true|false) True, if the item text (above attribute values) contains a file name.
|
|
FileNameRx = Regular expression used to remove the unnecessary chars from the item text.
|
|
SearchRx = regular expression used to find text areas in the Family 2 DTEP, which
|
|
will belong to this group
|
|
ClearRx = regular expression used to clear unwanted text/chars from the above
|
|
search result. The cleaned string will appear in the structure tree.
|
|
|
|
[Parsing rules] - Rules used when parsing the document.
|
|
SpecialAreas = The beginning and ending string of special areas, separated by a comma.
|
|
Special areas are not parsed according to this DTEP's rules, but as their own rules.
|
|
A special area can be a DTEP of another family, a comment, or something to that effect.
|
|
Eg. <!-- -->
|
|
SpecialAreaNames = Comma separated list of the above special area names. Eg. comment
|
|
SpecialTags = tagname(attributename) - Specifies a tag which defines the start of a special area.
|
|
AreaBorders = Comma separated list of the area borders encapsulating this Family 2 DTEP. In the
|
|
case of PHP, it is: <? ?>, <* *>, <% %>
|
|
Tags = tagname(attribute). If the parent(real) DTD has a tag with tagname and
|
|
the attribute value of this tag is equal with the DTD name, the tag area
|
|
is parsed according to the rules of this DTD.
|
|
Comments = comma separated list of area borders for comments. EOL means end-of-line.
|
|
Eg: // EOL, /* */
|
|
StructKeywords = Semicolon separated list of structure keywords. Structures are treated
|
|
as new nodes in the structure tree.
|
|
StructBeginStr = A string specifying the beginning of a structure (like {)
|
|
StructEndStr = A string specifying the beginning of a structure (like })
|
|
StructRx = Regular expression containing the beginning or the end of the structure
|
|
area. Eg. \\{ | \\} (structure area border can be { or })
|
|
</markup>
|
|
</literallayout>
|
|
</informalexample>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="creating-toolbars-3-2">
|
|
<title>Creating Toolbars</title>
|
|
|
|
<para>
|
|
The following will show you how to create toolbars for a &DTEP;. Toolbars
|
|
are graphical elements that are assigned to actions. Actions, in
|
|
&quantaplus;, are the basis for nearly all the extensions that
|
|
&quantaplus; has and will acquire in the future. The same mechanism that
|
|
defines an action in &quantaplus; also enables auto-completion and tag
|
|
dialogs. With actions, the limit of what you can do is virtually
|
|
limitless. For means of an example, we will use <ulink
|
|
url="http://tidy.sf.net">&HTML; tidy</ulink> on our web pages.
|
|
</para>
|
|
|
|
<sect2 id="from-scratch-to-complete-3-2">
|
|
<title>From Scratch to Complete</title>
|
|
|
|
<para>
|
|
To begin, you will need to create a user toolbar. Select
|
|
<menuchoice>
|
|
<guimenu>Toolbars</guimenu>
|
|
<guimenuitem>Add User Toolbar</guimenuitem>
|
|
</menuchoice>.
|
|
</para>
|
|
|
|
<para>
|
|
If there are many tags for the markup language, it is recommended that you
|
|
split up the tags into logical groups. You will need to create a new user
|
|
toolbar for each group. In this case, there are not many, so we will be
|
|
making one toolbar and naming it with the name of the markup.
|
|
</para>
|
|
|
|
<para>
|
|
Once all your toolbars are created, you must add and configure the
|
|
actions. To do this, select
|
|
<menuchoice>
|
|
<guimenu>Settings</guimenu>
|
|
<guimenuitem>Configure Actions</guimenuitem>
|
|
</menuchoice>
|
|
<emphasis>
|
|
</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
The parts of this window are pretty straight forward. Press the
|
|
<guibutton>New action</guibutton> button at the bottom of the window to
|
|
enter the editing mode.
|
|
</para>
|
|
|
|
<para>
|
|
Fill in all of the necessary fields and add the tag to the appropriate
|
|
toolbar(s).
|
|
</para>
|
|
|
|
<para>
|
|
Complete the rest and, if the tag has attributes and you always plan to
|
|
use them, check the <guilabel>Run "Edit tag" dialog if available
|
|
</guilabel> box so that you will be prompted every time the action is used.
|
|
</para>
|
|
|
|
<para>
|
|
You should now have something much like the following.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img7.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Press the <guibutton>Apply</guibutton> button and you will see the action
|
|
added to the toolbar(s) you have selected.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img8.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Egad! That's an awful icon. How will yourself and others remember that
|
|
icon goes with that action? Let's replace it before trouble arises.
|
|
</para>
|
|
|
|
<para>
|
|
To create an icon that more accurately describes that action, we will be
|
|
using &tdeiconedit;. Select it from the &menuk;, <menuchoice>
|
|
<guisubmenu>Graphics</guisubmenu>
|
|
<guisubmenu>More Programs</guisubmenu>
|
|
</menuchoice> (or where ever your distribution placed it).
|
|
</para>
|
|
|
|
<para>
|
|
&tdeiconedit; defaults to the size 32x32 pixels, but we need 22x22. To
|
|
change this, select
|
|
<menuchoice>
|
|
<guimenu>Edit</guimenu>
|
|
<guimenuitem>Resize</guimenuitem>
|
|
</menuchoice>.
|
|
</para>
|
|
|
|
<para>
|
|
Keep in mind that you are creating an icon that will assist in helping not
|
|
only yourself to remember which action does what, but also other users of
|
|
the &DTEP;.
|
|
</para>
|
|
|
|
<para>
|
|
Since the tag I am creating the icon for is called <quote>start,</quote>
|
|
I have decided to create a <quote>Start sign.</quote> Using the color green
|
|
(green often interpreted as <quote>go,</quote> <quote>start,</quote> or
|
|
<quote>proceed</quote>) will, or, at least, should, convey a message
|
|
to the user that clicking this action will place the <start> tag in the
|
|
current document.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img15.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Now that I am finished with the creation of the icon, I will save it.
|
|
</para>
|
|
|
|
<para>
|
|
Once you are done with creating the icon(s), you must associate the icon
|
|
with the action. To do this, open
|
|
<menuchoice>
|
|
<guimenu>Settings</guimenu>
|
|
<guimenuitem>Configure Actions</guimenuitem>
|
|
</menuchoice> again (in &quantaplus;) and select the action you made
|
|
the icon for. Beside the <guilabel>Text</guilabel> field, you will see a
|
|
button, click it.
|
|
</para>
|
|
|
|
<para>
|
|
Select <guilabel>Other Icons</guilabel> and then click the <guibutton>
|
|
Browse</guibutton> button.
|
|
</para>
|
|
|
|
<para>
|
|
Goto the folder in which you saved the icon, select the icon, and click
|
|
<guibutton>OK</guibutton>.
|
|
</para>
|
|
|
|
<para>
|
|
Press the <guibutton>Apply</guibutton> button and either continue to do the
|
|
same with the other tags, if any, or click <guibutton>OK</guibutton> to
|
|
finish.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img18.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Let us say you would like to add some common &quantaplus; functions to your
|
|
toolbar or maybe you think the toolbar would be better off organized in a
|
|
different manner with some separators to group the actions. Open the
|
|
<guilabel>Configure Toolbars</guilabel> dialog by going
|
|
<menuchoice>
|
|
<guimenu>Settings</guimenu>
|
|
<guimenuitem>Configure Toolbars</guimenuitem>
|
|
</menuchoice>. Make sure your toolbar is selected.
|
|
</para>
|
|
|
|
<para>
|
|
I will be choosing the separator (top of the left column) for my toolbar.
|
|
Once you have selected the item you wish to add to your toolbar, press the
|
|
right arrow button. This will add it to your toolbar.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img21.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
I think I would like a quick way to access the <guilabel>Konqueror
|
|
Preview</guilabel>. I will select it and add it to the toolbar.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img22.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Note how the separator helps in grouping. Someone new to my toolbar might
|
|
have thought that the &konqueror; button was like or the opposite of the
|
|
start button.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img23.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Apply your changes and, when you are done, press <guibutton>OK</guibutton>
|
|
to finish.
|
|
</para>
|
|
|
|
<para>
|
|
Ah, look at the fantastic new toolbar! Much more handy now.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img24.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Remember to test your toolbar, by clicking all the buttons, so that you
|
|
know the output is correct.
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="dtep_doc_img25.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Now to save the toolbar, we will select
|
|
<menuchoice>
|
|
<guimenu>Toolbars</guimenu>
|
|
<guisubmenu>Save Toolbars</guisubmenu>
|
|
<guimenuitem>Save as Local Toolbar</guimenuitem>
|
|
</menuchoice>.
|
|
</para>
|
|
|
|
<para>
|
|
Save it to the correct folder. Since NeXML does not exist, I will just
|
|
have it to the top-level folder, but your toolbar(s) should be saved to
|
|
the correct folder. Make sure to adjust your description.rc to have it
|
|
load your toolbar(s) when a new file of that type is created.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="creating-quanta-docs-3-2">
|
|
<sect1info>
|
|
<title>Creating Your Own Documentation</title>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Robert</firstname>
|
|
<surname>Nickel</surname>
|
|
<affiliation>
|
|
<address><email>robert@artnickel.com</email></address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
|
|
</authorgroup>
|
|
</sect1info>
|
|
|
|
<title>Creating Your Own Documentation</title>
|
|
|
|
<para>
|
|
Probably the most notable additions to &quantaplus; for the general user
|
|
will be the addition of documentation for the markup or scripting language
|
|
that you like best. To that end, this chapter will explain how I create
|
|
the &PHP; documentation tree for my personal use.
|
|
</para>
|
|
|
|
<para>
|
|
Before starting on creating your own documentation, you may wish to check
|
|
out the <ulink url="http://quanta.sf.net/main1.php?contfile=resource">
|
|
&quantaplus; repository</ulink> to see if someone else has already done
|
|
this set.
|
|
</para>
|
|
|
|
<para>
|
|
There are two parts to this process. First, you must obtain the existing
|
|
documentation for the markup/scripting/&etc; language that you are after.
|
|
Second, you have to create the <filename>docrc</filename> file. The first
|
|
is up to you, the second is what we will cover here.
|
|
</para>
|
|
|
|
<para>
|
|
The general form of the docrc file is as follows:
|
|
</para>
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
#KDE Config File
|
|
[Tree]
|
|
Doc dir=<replaceable>path, relative to this file, of the documentation html files</replaceable> &pex; php42/
|
|
#top level elements
|
|
Top Element=<replaceable>Your description for these documentation</replaceable> &pex; &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>
|
|
The <filename>docrc</filename> is broken down into two sections: Tree and
|
|
Context.
|
|
</para>
|
|
|
|
<para>
|
|
The Tree section defines the presentation aspect of the documentation in
|
|
the documentation tab. For example, you will see that in the &PHP;
|
|
documentation you have something akin to this:
|
|
</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="doc-view1.png" format="PNG" />
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>
|
|
Relating this to the above, my &PHP; <filename>docrc</filename> looks like
|
|
this:
|
|
</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>
|
|
Notice the <literal>#</literal> in front of <quote>Getting Started</quote>
|
|
and <quote>Language Reference</quote>. This indicates that these are sub
|
|
containers in the tree and have content of their own. I do not believe that
|
|
there is a set limit to the depth here (other than that driven by sanity)
|
|
— use your judgment.
|
|
</para>
|
|
|
|
<para>
|
|
For the Table of Contents, you will notice that it is referenced directly to
|
|
a file (and consequently shows up at the bottom of the tree view —
|
|
folders first!).
|
|
</para>
|
|
|
|
<important>
|
|
<para>
|
|
Spaces do not adversely affect anything, but watch out for & and <
|
|
characters. These should likely be replaced by &amp; and &lt;
|
|
respectively in all of the &XML; based &quantaplus; resource files.
|
|
</para>
|
|
</important>
|
|
|
|
<para>
|
|
The Context section is the section of the docrc file that is used to
|
|
facilitate context sensitive help. For example, you are writing a &PHP;
|
|
script and you would like to see the documentation for the
|
|
<function>mysql_fetch_array</function> function. You simply highlight the
|
|
function and then press <keycombo action="simul">&Ctrl;<keycap>H</keycap>
|
|
</keycombo> for context help. The documentation on
|
|
<function>mysql_fetch_array</function> will immediately display. There are
|
|
only two entry types here: the ContextList and the file association lines.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>ContextList</term>
|
|
<listitem>
|
|
<para>
|
|
Really simple, this is just a comma separated list of the context items
|
|
you wish to have available (for &PHP;, these are the functions for &PHP;).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>File association lines</term>
|
|
<listitem>
|
|
<para>
|
|
These are of the form context item=html doc page. &pex;
|
|
acos=function.acos.html
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
A pared down version of my <filename>docrc</filename> Context section is
|
|
as follows:
|
|
</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>
|
|
Now you can just save your <filename>docrc</filename> file, save it in
|
|
<filename class="directory">$<envar>HOME</envar>/.trinity/share/apps/quanta/doc</filename>
|
|
or <filename class="directory">$<envar>TDEDIR</envar>/share/apps/quatna/doc</filename>
|
|
for local or global use respectively. Then create a folder (the one
|
|
specified in your <filename>docrc</filename> file) in the same folder
|
|
as your <filename>docrc</filename> file and copy your &HTML; pages in
|
|
there.
|
|
</para>
|
|
|
|
<para>
|
|
You will need to restart &quantaplus; to see your documentation.
|
|
</para>
|
|
|
|
<para>
|
|
Once you are sure that they are good and worth sharing, send the <filename>
|
|
docrc</filename> file along with a description of any pertinent
|
|
information on what documentation you used to the
|
|
<ulink url="http://quanta.sf.net/main1.php?contfile=resource">&quantaplus;
|
|
repository</ulink> for use by the &quantaplus; community. You will not get
|
|
rich, but you will feel great knowing that you contributed to the best web
|
|
development platform around.
|
|
</para>
|
|
|
|
</sect1>
|
|
</chapter>
|