diff options
author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-12-03 11:05:10 -0600 |
---|---|---|
committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-12-03 11:05:10 -0600 |
commit | f7e7a923aca8be643f9ae6f7252f9fb27b3d2c3b (patch) | |
tree | 1f78ef53b206c6b4e4efc88c4849aa9f686a094d /tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook | |
parent | 85ca18776aa487b06b9d5ab7459b8f837ba637f3 (diff) | |
download | tde-i18n-f7e7a923aca8be643f9ae6f7252f9fb27b3d2c3b.tar.gz tde-i18n-f7e7a923aca8be643f9ae6f7252f9fb27b3d2c3b.zip |
Second part of prior commit
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, 0 insertions, 1625 deletions
diff --git a/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook b/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook deleted file mode 100644 index c3a9c0c9782..00000000000 --- a/tde-i18n-fr/docs/kdewebdev/quanta/extending-quanta.docbook +++ /dev/null @@ -1,1625 +0,0 @@ -<?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> |