diff options
Diffstat (limited to 'tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook')
| -rw-r--r-- | tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook | 1625 |
1 files changed, 1625 insertions, 0 deletions
diff --git a/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook b/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook new file mode 100644 index 00000000000..c3a9c0c9782 --- /dev/null +++ b/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook @@ -0,0 +1,1625 @@ +<?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 $KDEDIR($KDEHOME)/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 $KDEDIR($KDEHOME)/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 &kiconedit;. Select it from the &menuk;, <menuchoice> +<guisubmenu>Graphics</guisubmenu> +<guisubmenu>More Programs</guisubmenu> +</menuchoice> (or where ever your distribution placed it). +</para> + +<para> +&kiconedit; 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>/.kde/share/apps/quanta/doc</filename> +or <filename class="directory">$<envar>KDEDIR</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> |