From f7e7a923aca8be643f9ae6f7252f9fb27b3d2c3b Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sat, 3 Dec 2011 11:05:10 -0600 Subject: Second part of prior commit --- .../docs/tdewebdev/quanta/extending-quanta.docbook | 1625 ++++++++++++++++++++ 1 file changed, 1625 insertions(+) create mode 100644 tde-i18n-fr/docs/tdewebdev/quanta/extending-quanta.docbook (limited to 'tde-i18n-fr/docs/tdewebdev/quanta/extending-quanta.docbook') diff --git a/tde-i18n-fr/docs/tdewebdev/quanta/extending-quanta.docbook b/tde-i18n-fr/docs/tdewebdev/quanta/extending-quanta.docbook new file mode 100644 index 00000000000..c3a9c0c9782 --- /dev/null +++ b/tde-i18n-fr/docs/tdewebdev/quanta/extending-quanta.docbook @@ -0,0 +1,1625 @@ + + + + +Extending &quantaplus; + + +Christopher +Hornbaker + +
chrishornbaker@earthlink.net
+ + + + + + + + +Extending &quantaplus; + + +This chapter describes how to customize &quantaplus; to your particular +needs and how you can help &quantaplus; become better. + + + + + +Document Type Editing Package (&DTEP;) + + +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. + + + +&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. + + + +This document describes how to make TagXML files, the description.rc, and +toolbars. In short, a &DTEP;. + + + +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. + + + +Packaging + + +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) + + + + +TagXML + + +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. + + + + + + +Element +Default Usage +Case Usage + + + + +TAGS +required +always + + +tag +required +always + + +label +optional +required to create a properties dialog + + +attr +optional +required to define an attribute + + +tooltip +optional +required to have the properties dialog display a tooltip + + +whatsthis +optional +required to have the properties dialog display a What's This + + + +list +optional +required when an attr is of the type list + + +item +optional +required when <list> is used + + +textlocation +optional +always + + +location +optional +required when label is used + + +text +optional +required when label is used + + +children +optional +list of tags that can appear within the tag being defined + + +child +required +a children entry + + +stoppingtags +optional +list of tags that tell another tag to end + + +stoppingtag +required +a stoppingtags entry + + + + + + + +TagXML Element Descriptions + + +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. + + + +TAGS + + +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. + + + + + + +Parent(s) +Children + + + + +NONE +tag + + + + + + + +tag + + +Wrapper for tag being defined. This is an element-only type element. + + + + + + +Parent(s) +Children + + + + +TAGS +label, attr, stoppingtags + + + + + + + + + +AttributeTypeValues +DefaultUseDescription + + + + +namestring +requiredSpecifies the name of the tag being defined. + + +singleboolean +optionalSpecifies whether or not the tag requires a +closing tag </(tagname)>. + + +typestringxmltag +optionalSpecifies the type of tag being defined. + + +xmltag +Type of tag is XML-based. (Family 1 only.) + + +property +Type of tag is &CSS; related. (Family 2 only.) + + +function +Type of tag is a script function. When used, +<attr> becomes arguments of the function. (Family 2 only.) + + +class +Type of tag is a script class. (Family 2 only.) + + +returnTypestringvoid + +optionalSpecifies the return type of tag being +defined. (Family 2 only.) + + +void +Type of tag returns void. + + +int +Type of tag returns int. + + +float +Type of tag returns float. + + +long +Type of tag returns long. + + +string +Type of tag returns string. + + + + + + + +label + + +Place a label in the dialog. The text is specified by the <text> tag. +This is an element-only type element. + + + + + + +Parent(s) +Children + + + + +tag +text, location + + + + + + + +attr + + +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. + + + + + + +Parent(s) +Children + + + + +tag +location, list, tooltip, whatsthis, textlocation + + + + + + + + + +AttributeTypeValues +DefaultUseDescription + + + + +namestring +requiredSpecifies the name of the attribute being +defined. + + +typestringinput +requiredSpecifies the type of the attribute being +defined. + + +input +Field supports free text entries (text field). + + +check +Field value is boolean (check box). + + +color +Field value is a color. + + +url +Field value is a &URL;. (Local file to refer to.) + + +list +Field value is an item from a specified list. + + +statusstringoptional +requiredSpecifies whether or not the argument is +required. (Family 2 only.) + + +optional +Argument is optional. + + +required +Argument is required. + + +implied +Argument is implied. + + + + + + + +tooltip + + +Defines the tooltip for a field in the dialog. This element is text-only. + + + + +Currently only plain text is supported (you cannot use any markup). + + + + + + + +Parent(s) +Children + + + + +attr +NONE + + + + + + + +whatsthis + + +Defines the 'What's This' help for a field in the dialog. This element is +text-only. + + + + +Currently only plain text is supported (you cannot use any markup). + + + + + + + +Parent(s) +Children + + + + +attr +NONE + + + + + + + +list + + +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. + + + + + + +Parent(s) +Children + + + + +attr +item + + + + + + + +item + + +Defines an item in a list. This element is text-only. + + + + + + +Parent(s) +Children + + + + +list +NONE + + + + + + + +textlocation + + +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. + + + + + + +Parent(s) +Children + + + + +attr +NONE + + + + + + + + + +AttributeType +UseDescription + + + + +rownonNegativeInteger +requiredSpecifies the row in the dialog layout of a +field or label. + + +colnonNegativeInteger +requiredSpecifies the column in the dialog layout of +a field or label. + + +rowspannonNegativeInteger +optionalSpecifies the number of rows a field should +span. + + +colspannonNegativeInteger +optionalSpecifies the number of columns a field +should span. + + + + + + + +location + + +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. + + + + + + +Parent(s)Children + + + + +label, attrNONE + + + + + + + + + +AttributeType +UseDescription + + + + +rownonNegativeInteger +requiredSpecifies the row in the dialog layout of a +field or label. + + +colnonNegativeInteger +requiredSpecifies the column in the dialog layout of +a field or label. + + +rowspannonNegativeInteger +optionalSpecifies the number of rows a field should +span. + + +colspannonNegativeInteger +optionalSpecifies the number of columns a field +should span. + + + + + + + +text + + +Define the text for a label or check box. This element is text-only. + + + + + + +Parent(s)Children + + + + +label, attrNONE + + + + + + + +children + + +Defines a list of elements that can appear within the tag being specified. +This element is an element-only type element. + + + + + + +Parent(s)Children + + + + +tagchild + + + + + + + +child + + +Defines a child tag. This element is empty. + + + + + + +Parent(s)Children + + + + +childrenNONE + + + + + + + + + +AttributeType +UseDescription + + + + +namestring +requiredSpecifies a tag that can appear within the a +certain tag. + + + + + + + +stoppingtags + + +Defines a list of elements that force a tag to end. This element is an +element-only type element. + + + + + + +Parent(s)Children + + + + +tagstoppingtag + + + + + + + +stoppingtag + + +Defines a stopping tag. This element is empty. + + + + + + +Parent(s)Children + + + + +stoppingtagsNONE + + + + + + + + + +AttributeType +UseDescription + + + + +namestring +requiredSpecifies which tags force the ending of +another tag. + + + + + + + + +TagXML Usage + + +All TagXML files must begin with the &XML; declaration: <?xml +version="1.0" encoding="UTF-8"?> and must be properly nested and closed. + + + + +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. + + + + + +TagXML Validation + + +To validate your TagXML files, simply click the Tools +pop-up dialog at the top of &quantaplus; and select Validate +TagXML. A dialog will present itself and you need only to follow +the simple directions. + + + + +This feature is currently not present. Currently validation occurs when +the TagXML files are loaded into &quantaplus;. + + + + + +TagXML Examples + + +Family 1 + + +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? + + + + + +<?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> + + + + + + +Family 2 + + +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. + + + + + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE tags> +<tags> + <tag name="overload" type="function" returnType="void"> +<attr name="class_name" type="string" status="optional"/> + </tag> +</tags> + + + + + + + + +description.rc + + +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. + + + +Family 1 Structure + + + + +[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) + + + + + + +Family 2 Structure + + + + +[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 }) + + + + + + + + +Creating Toolbars + + +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 &HTML; tidy on our web pages. + + + +From Scratch to Complete + + +To begin, you will need to create a user toolbar. Select + +Toolbars +Add User Toolbar +. + + + +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. + + + +Once all your toolbars are created, you must add and configure the +actions. To do this, select + +Settings +Configure Actions + + +. + + + +The parts of this window are pretty straight forward. Press the +New action button at the bottom of the window to +enter the editing mode. + + + +Fill in all of the necessary fields and add the tag to the appropriate +toolbar(s). + + + +Complete the rest and, if the tag has attributes and you always plan to +use them, check the Run "Edit tag" dialog if available + box so that you will be prompted every time the action is used. + + + +You should now have something much like the following. + + + + + + + + + +Press the Apply button and you will see the action +added to the toolbar(s) you have selected. + + + + + + + + + +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. + + + +To create an icon that more accurately describes that action, we will be +using &kiconedit;. Select it from the &menuk;, +Graphics +More Programs + (or where ever your distribution placed it). + + + +&kiconedit; defaults to the size 32x32 pixels, but we need 22x22. To +change this, select + +Edit +Resize +. + + + +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;. + + + +Since the tag I am creating the icon for is called start, +I have decided to create a Start sign. Using the color green +(green often interpreted as go, start, or +proceed) will, or, at least, should, convey a message +to the user that clicking this action will place the <start> tag in the +current document. + + + + + + + + + +Now that I am finished with the creation of the icon, I will save it. + + + +Once you are done with creating the icon(s), you must associate the icon +with the action. To do this, open + +Settings +Configure Actions + again (in &quantaplus;) and select the action you made +the icon for. Beside the Text field, you will see a +button, click it. + + + +Select Other Icons and then click the +Browse button. + + + +Goto the folder in which you saved the icon, select the icon, and click +OK. + + + +Press the Apply button and either continue to do the +same with the other tags, if any, or click OK to +finish. + + + + + + + + + +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 +Configure Toolbars dialog by going + +Settings +Configure Toolbars +. Make sure your toolbar is selected. + + + +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. + + + + + + + + + +I think I would like a quick way to access the Konqueror +Preview. I will select it and add it to the toolbar. + + + + + + + + + +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. + + + + + + + + + +Apply your changes and, when you are done, press OK +to finish. + + + +Ah, look at the fantastic new toolbar! Much more handy now. + + + + + + + + + +Remember to test your toolbar, by clicking all the buttons, so that you +know the output is correct. + + + + + + + + + +Now to save the toolbar, we will select + +Toolbars +Save Toolbars +Save as Local Toolbar +. + + + +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. + + + + + + + +Creating Your Own Documentation + + +Robert +Nickel + +
robert@artnickel.com
+ + + + + + + + +Creating Your Own Documentation + + +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. + + + +Before starting on creating your own documentation, you may wish to check +out the +&quantaplus; repository to see if someone else has already done +this set. + + + +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 docrc file. The first +is up to you, the second is what we will cover here. + + + +The general form of the docrc file is as follows: + + + + +#KDE Config File +[Tree] +Doc dir=path, relative to this file, of the documentation html files &pex; php42/ +#top level elements +Top Element=Your description for these documentation &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 + + + + +The docrc is broken down into two sections: Tree and +Context. + + + +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: + + + + + + + + + +Relating this to the above, my &PHP; docrc looks like +this: + + + + +#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 +... + + + + + +Notice the # in front of Getting Started +and Language Reference. 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. + + + +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!). + + + + +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. + + + + +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 +mysql_fetch_array function. You simply highlight the +function and then press &Ctrl;H + for context help. The documentation on +mysql_fetch_array will immediately display. There are +only two entry types here: the ContextList and the file association lines. + + + + +ContextList + + +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;). + + + + +File association lines + + +These are of the form context item=html doc page. &pex; +acos=function.acos.html + + + + + + +A pared down version of my docrc Context section is +as follows: + + + + +#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 +... + + + + +Now you can just save your docrc file, save it in +$HOME/.kde/share/apps/quanta/doc +or $KDEDIR/share/apps/quatna/doc +for local or global use respectively. Then create a folder (the one +specified in your docrc file) in the same folder +as your docrc file and copy your &HTML; pages in +there. + + + +You will need to restart &quantaplus; to see your documentation. + + + +Once you are sure that they are good and worth sharing, send the +docrc file along with a description of any pertinent +information on what documentation you used to the +&quantaplus; +repository 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. + + + + -- cgit v1.2.1