<chapter id="extending-quanta">
<title>Extending &quanta;</title>
<para>This chapter describes how to customize &quanta; to your particular needs and how you can help &quanta;
 become better.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author>
<firstname></firstname>
<surname></surname>
</author>
</sect1info>
<title>Creating Your Own Docs for &quanta;</title>
<para>Probably the most notable additions to &quanta; 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.sourceforge.net/main1.php?contfile=resource">&quanta; 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're after.  Second, you have to create the docrc file.  The first
is up to you, the second is what we'll cover here.</para>

<para>The general form of the docrc file is as follows:
<informalexample>
<literallayout>
#KDE Config File
[Tree]
Doc dir=&lt;path, relative to this file, of the documentation html files&gt; e.g. php42/
#top level elements
Top Element=&lt;Your description for these docs> e.g. 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>
The docrc 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'll see that in the php docs you have something akin to this:</para>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para><para>Relating this to the above, my php docrc looks like this:
<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>
Notice the # 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 don't
believe that there is a set limit to the depth here (other than that driven by sanity) - use your
judgement.
</para>
<para>For the Table of Contents, you'll notice that it is referenced directly to a file (and
consequently shows up at the bottom of the tree view - directories first!).</para>
<important>
<para>Spaces don't adversely affect anything, but watch out for &amp; and &lt; characters.
These should likely be replaced by &amp;amp; and &amp;lt; respectively in all of the xml
based &quanta; 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're writing a PHP script and you'd like to see the
docs for the mysql_fetch_array function.  You simply highlight the function and then press
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>H</keycap>
</keycombo>
</shortcut>
<guimenu></guimenu>
</menuchoice>
 for context help.  Woosh!  You're viewing the docs on
mysql_fetch_array.  There are only two entry types here: the ContextList and the file
association lines.
<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. e.g. acos=function.acos.html</para></listitem>
</varlistentry>
</variablelist>
A pared down version of my docrc Context section is as follows:
<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>
<para>Now you can just save your docrc 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 directory (the one specified in your docrc file) in the same directory as your docrc file
and copy your html doc pages in there.</para>
<para>You'll need to restart &quanta; and then you'll see your docs.</para>
<para>Once you're sure that they're good and worth sharing, send the docrc file along with a
description of any pertinent information on what docs you used to the
<ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource">&quanta; repository</ulink> 
for use by the &quanta; community. You won't get rich, but you'll feel great knowing that you
contributed to the best web development platform around.</para>

</sect1>

<sect1 id="creating-actions">
<sect1info>
<author>
<firstname>Robert</firstname>
<surname>Nickel</surname>
</author>
</sect1info>
<title>Creating Actions in &quanta;</title>
<para>Actions in &quanta; are the basis for nearly all the extensions that &quanta; has and will acquire in the
future.  The same mechanism that defines an action in &quanta; enables autocompletion 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://www.w3c.org/People/Raggett/tidy/">html tidy</ulink> on our web pages.</para>

<para>Let's get started:
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Actions</guimenuitem></menuchoice>
</para>
<para>
Once you start the actions dialog you'll see this window.  To the left is the list of currently known
actions.  You can select one of those and perform the same actions for an existing action that we're
going to do with our html tidy action.
</para>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para>We're going to make a new action, so let's click on the new button (lower left) and begin.</para>

<para>Now you're presented with a blank set of options to fill in:
<variablelist>
<varlistentry>
<term>Text</term>
<listitem><para>This is the name of the action</para></listitem>
</varlistentry>
<varlistentry>
<term>Tool tip</term>
<listitem><para>Not sure where this get's displayed.  It's optional!</para></listitem>
</varlistentry>
<varlistentry>
<term>Status text</term>
<listitem><para>Don't know what this is for or where it's used. It's optional!</para></listitem>
</varlistentry>
<varlistentry>
<term>Place this action onto (checkbox)</term>
<listitem><para>This enables the drop down box for selection of a toolbar to place this action onto.  If you don't
choose now, you can always add them later from <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
Toolbars</guimenuitem></menuchoice>.</para></listitem>
</varlistentry>
</variablelist>
After filling in these basics, you can select an icon for the action by clicking on the icon button to the 
left of the 'Text' input box.
</para>

<para>Now to the meat of the matter.  The actions definition.</para>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para>If we were defining a markup tag, we could use the tag tab here to input the tags parameters.</para>
<para>
To whit:
<variablelist>
<varlistentry>
<term>&lt;tag></term>
<listitem><para>This is where you enter the tag name as it will appear in your document.  e.g. &lt;div align=center&gt;</para></listitem>
</varlistentry>
<varlistentry>
<term>&lt;/tag></term>
<listitem><para>This is where you enter the closing tag, if any, or uncheck the box if none.  e.g. &lt;/div&gt;</para></listitem>
</varlistentry>
<varlistentry>
<term>Run <quote>Edit Tag</quote> dialog if available</term>
<listitem><para>This runs the dialog editor if there is a tag file defined for this item.
Check out the <link linkend="tag-files">tag files</link> section for more information
on tag files.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>And now... Back to our regularly scheduled program.  Continuing on the html tidy action creation.</para>
<para>Click on the Script tab to reveal the following:</para>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject></para>
<para>
<variablelist>
<varlistentry>
<term>Input box at top</term>
<listitem><para>This is where you place the executable that you're after.  In our case, it would be /usr/local/bin/tidy
because that's where I keep tidy.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>Now on to the Input/Output/Error tabs.</para>
<para><emphasis>Input Tab</emphasis>
<variablelist>
<varlistentry>
<term>None (radio button)</term>
<listitem><para>Don't take any input for this script.  This could be useful if you were calling a Tcl/Tk script
that popped up a window for interaction with the user and then returned its results.  We'll be choosing
something else for tidy.</para></listitem>
</varlistentry>
<varlistentry>
<term>Selected text (radio button)</term>
<listitem><para>Just what it says.  It pushes a copy of the currently selected text out to the standard in of the
script in the input box above.  We could use this for tidy, but it's no fun to select everything in a large
document.</para></listitem>
</varlistentry>
<varlistentry>
<term>Current document (radio button)</term>
<listitem><para>Pipes the contents of the editor version of the file through to the standard in of the script in
the input box above.  This is what we'll use for tidy.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>Now click on the <emphasis>Output</emphasis> tab.
This is where we decide on our redirection for your scripts output.
<variablelist>
<varlistentry>
<term>None</term>
<listitem><para>Duh.  This would be fine if you're launching an external application that only takes input but
doesn't output anything.  This is no real use for us with tidy.</para></listitem>
</varlistentry>
<varlistentry>
<term>Insert in cursor position</term>
<listitem><para>Just what it says.  Be certain you're where you want the text inserted.  No good for tidy.</para></listitem>
</varlistentry>
<varlistentry>
<term>Replace current document</term>
<listitem><para>Total file replacement here.  It won't overwrite the file on disk, but it will blast your current
edit session.  Use with caution.  We won't use this for tidy.</para></listitem>
</varlistentry>
<varlistentry>
<term>Create new document</term>
<listitem><para>Output to a new document in the edit window.  This is the best choice for tidy.</para></listitem>
</varlistentry>
<varlistentry>
<term>Message window</term>
<listitem><para>Output to the message window <menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>M</keycap>
</keycombo></shortcut><guimenu></guimenu></menuchoice>.  This is useful for debugging and the Error tab, but not much else for
Output. Not for tidy.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
For the Edit tab, the options are the same as the Output tab.  Usually, you'll use the message window,
to help in debugging, or none option.</para>
</sect1>
</chapter>
