<chapter id="using-quanta">
<title>Using &quanta;</title>

<sect1 id="intro">
<title>Introduction</title>
<para>While striving to become the best HTML editor, the developers of &quanta; began to kick about a
rather intruiging idea.  <quote>What if &quanta; was a generic, extensible, markup language editor?</quote></para>
<para>Well, this is the start of the answer.  No longer bound to HTML, &quanta; is now well on its way
to becoming DTD agnostic.  Essentially, if you can define it in XML or SGML, &quanta; should be able to serve
as an IDE for it.</para>
<para>Now, that said, it must be noted that &quanta; is an outgrowth of the outstanding efforts that have been
put forth by the entire KDE development community.  &quanta;, in celebration of open source uses the model of
<quote>Why rewrite something somebody already did and maintains already?</quote></para>
<para>&quanta; provides web developers with an intuitive and powerful multiple document interface
<acronym>MDI</acronym> that can dramatically increase your effectiveness as a web developer.  Through
the use of custom actions, scripting and toolbar creation you can automate almost any task.  With the use
of <application>Kaptain</application>, you can extend &quanta;, so that you never have to remember scripting command syntax again
(More on that in the <link linkend="advanced-quanta">Advanced Features section</link>.).</para>
<sect2 id="quanta-workspaces">
<title>The &quanta; workspace</title>
<para>&quanta; divides workspace files into three areas; Global, Local and Project.  These distinctions affect
the scope or visibility of the various components in the &quanta; IDE.</para>
<variablelist>
<varlistentry>
<term>Global</term>
<listitem><para>Global items are available to anyone who uses &quanta;.  From toolbars to actions, everything
marked as global is stored in the common &quanta; directory structure.  This has the effect of allowing a group
of admins to save certain toolbars, actions and templates in the global tree that can then be used to keep a
multi-user installation of &quanta; common to everyone on the system.</para></listitem>
</varlistentry>
<varlistentry>
<term>Local</term>
<listitem><para>Local items are items that are part of an individual users collection of resources.  These are
stored in the individual users home directory tree as part of the kde environment information.  This exposes all
of the items stored as Local for use in any editing that the individual user wishes to work on.  This allows
you to save your most useful templates and toolbars into your home directory and use them on any
documents.</para></listitem>
</varlistentry>
<varlistentry>
<term>Project</term>
<listitem><para>Project items are those items that are of use only to a particular project.  These could be anything
from a CSS template to a toolbar with a custom action that performs a special magic trick on this project's
files.  Simply put, this is the most limited scope.  All of the items saved in the project workspace be saved
in the project's directory tree.</para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="mdi-interface">
<title>&quanta;'s <acronym>MDI</acronym> Interface</title>
<screenshot>
<screeninfo>&quanta; editing this document!!</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="quantamdi.png" format="PNG" />
</imageobject>
<caption><para>The &quanta; MDI editing this document</para></caption>
</mediaobject>
</screenshot>
<para>&quanta;'s MDI is broken down to three main parts: the <link linkend="editor">editor</link> window, the
<link linkend="tree-views">tree view</link> window and the <link linkend="toolbars">toolbar</link>.</para>
</sect1>

<sect1 id="editor">
<title>The &quanta; Editor Window</title>
<para>
<screenshot>
<screeninfo>Zoom in on the editor window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="quantamdi-editor.png" format="PNG" />
</imageobject>
<caption><para>&quanta;'s editor window</para></caption>
</mediaobject>
</screenshot>
&quanta;'s editor window allows for multiple files to be opened at the same time.  When just one file is open, the
document fills the entire editor window.  As soon as a second document is opened, a small amount of space is taken
from the bottom of the editory window to allow for tabs to be displayed with the filenames and a status icon
(this picture doesn't show it, but there is a blue floppy icon that shows up to the left of the filename when a file
has been altered indicating that a save is necessary).</para>
<para>
At the top of the editor window is the editor toolbar set.  Currently, &quanta; has a default set of toolbars that are
loaded.  These are Standard, Fonts, Tables, Lists, Forms, Other.  These are the original toolbars that have been a part
of &quanta; for some time now.  These toolbars are strictly HTML and will continue to be a part of &quanta; but will
eventually be loaded only on demand and not by default.
</para>

<para>
Toolbar usage is pretty straight forward.  If you're looking for a basic tag (like &lt;u&gt;), you click on that tag and
it is inserted into your document.  You then insert your information betrween (if there's a closing tag) the tags and call
it good.  If you're looking to insert something that takes more information than just you're text (like a &lt;a href...&gt;)
then you'll get a dialog box with the various fields you can fill in.
<screenshot>
<screeninfo>A dialog for creating an HTML anchor</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="taginputex.png" format="PNG" />
</imageobject>
<caption><para>HTML toolbar anchor dialog</para></caption>
</mediaobject>
</screenshot>
</para>
</sect1>

<sect1 id="tree-views">
<title>The &quanta; Tree View Window</title>
<mediaobject>
<imageobject>
<imagedata fileref="quantamdi-treeview.png" format="PNG" />
</imageobject>
<caption><para>&quanta;'s tree view window</para></caption>
</mediaobject>

<para>The tree view is the place where you will navigate and gather information in &quanta;.
It's tabbed format presents you with a Files, Project, Template, Document Structure and
Documentation Tree. </para>

<variablelist id="treeview-icon-defs">
<title>Tabs in the tree view</title>
<varlistentry>
<term></term>
<listitem><para><mediaobject>
<imageobject>
<imagedata fileref="ftab.png" format="PNG" />
</imageobject>
</mediaobject><emphasis>Files Tree: </emphasis> This is where you can browse your entire filesystem in tree format.  You
are presented with two perspectives on the filesystem.  The first is based on your home directory and the second is
the root of the file system.  Use this to find existing files on your machine that you'd like to edit or add to an active
project.  Right clicking on a file in this view gives you several options for managing the selected file and also allows
you to insert the file into the active project (if any), or toggle the view between tree and list.  Check it out!</para></listitem>
</varlistentry>

<varlistentry>
<term></term>
<listitem><para><mediaobject>
<imageobject>
<imagedata fileref="ptab.png" format="PNG" />
</imageobject>
</mediaobject>
<emphasis>Project Tree: </emphasis>Hopefully, if you use &quanta;, you'll use projects.
<link linkend="quanta-projects">Project management </link> is the single most powerful tool that &quanta;
offers.  This view gives you direct access to what that structure looks like and allows you to manage
the files in the project through right-click access.  Add, remove or upload individual files or delete
them entirely from the disk.  All with a right-mouse click.</para></listitem>
</varlistentry>

<varlistentry>
<term>
</term>
<listitem><para>
<mediaobject>
<imageobject>
<imagedata fileref="ttab.png" format="PNG" />
</imageobject>
</mediaobject>
<emphasis>Template Tree: </emphasis>One of the new features in &quanta; 3 is templates.  Templates
can be just about anything that you wish from images to code snippets to an entire web page that you change the
heading on.  Templates are sorted into three categories based on their scope, or visibility, in the current
context.  These are Global, Local and Project.  As you may have guessed, Global templates are visible all the time.
Local tamplates are visible to the user who created them and project templates are visible for a single project
only.  More on templates <link linkend="templates">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term>
</term><listitem><para>
<mediaobject>
<imageobject>
<imagedata fileref="view_sidetree.png" format="PNG" />
</imageobject>
</mediaobject>
<emphasis>Structure Tree: </emphasis>This handy little view gives you a look at how the parser sees
your document.  It's pretty straight forward and can really help with those sticky required closing tags we always seem
to neglect.
</para></listitem>
</varlistentry>

<varlistentry>
<term>
</term><listitem><para>
<mediaobject>
<imageobject>
<imagedata fileref="contents2.png" format="PNG" />
</imageobject>
</mediaobject>
<emphasis>Documentation Tree: </emphasis>Listed here is all of the documentation available for you to
browse inside of &quanta;.  You can download pre-packaged docs for &quanta; at
<ulink url="http://quanta.sourceforge.net/docs.html">http://quanta.sourceforge.net/docs.html</ulink> or you can
<link linkend="creating-quanta-docs">create your own documentation</link> for &quanta;.</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="toolbars">
<title>&quanta; Toolbars</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="toolbars.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>
<para>A major portion of &quanta;'s push to be DTD agnostic is dependent upon ease of use for each separate
DTD.  To that end, the toolbars in &quanta; have been extended a great deal.  Toolbars are easy enough to
understand.  You click onthe button and you get an associated action from that button.  The really cool part
here is that you can define your own actions in &quanta;.</para>
<para>Using toolbars in &quanta; is incredibly simple. Selecting the
<menuchoice><shortcut><keycombo action="simul">&Alt;<keycap>l</keycap></keycombo></shortcut>
<guimenu>Toolbars</guimenu></menuchoice> menu item reveals options to load, save, add and email toolbars.</para>
<para>Loading and saving toolbars is pretty straight forward.  When you choose to load a toolbar, you may
choose from one of the three <link linkend="quanta-workspaces">workspaces</link> in &quanta;.
</para>
<para>One of the most exciting new features of &quanta; toolbars is that you can email them directly from &quanta;.
When you do so, &quanta; bundles all of the actions and the toolbar information into a zipped tar archive then
pushes it out via &kmail;.  Once you receive a toolbar in email, you can save it anywhere and load it into &quanta;
like any other toolbar!</para>
<sect2 id="toolbars-howto">
<title>How to use toolbars in &quanta;</title>
<para>
As previously mentioned, toolbars in &quanta; are primarily maanged through the <menuchoice><guimenu>Toolbars</guimenu>
</menuchoice> menu item.  Usability and creation are somewhat different.  Creation is deferred to an
<!--<link linkend="adv-quanta-toolbars">advanced topic</link> -->
as there is more involved there.  Usability will be discussed
now.</para>
<para>Using toolbars is quite simple.  You click on the icon of the desired tag or
<!--<link linkend="adv-quanta-actions">action</link>-->
 and one of three possibilities occur: the tag is inserted (optionally
with a closing tag) (e.g. the bold HTML tag), a tag dialog is activated letting you fill in the multiple tag features
in a dialog box (e.g. the anchor HTML tag), and lastly, an action is activated that does something nifty for your
current file/project/whatever.  For the first, I'll give no example as it is easy enough to understand.  As to the
second and third, read on...</para>
<para>Tag dialogs are defined in XML and stored in a tags subdirectory under your .kde subdirectory or with the
&quanta; distribution wherever you put that.  I bring this up only to note that, if you find yourself doing tedious
and redundant typing for a particular tag that isn't in &quanta;, you can add it.  Anyway, a tag dialog looks just
like this:</para>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="taginputex.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>
<para>
This happens to be the anchor tag referenced above.  If you know anything about HTML, you'll notice that that's just
about all the attributes you can have for an anchor.  Notice the tabs above for i18n and Events.  Now all you do is
fill in the blanks for those items you want in your anchor, click ok and, voila!, you have a well formed anchor set
down at the current cursor position.</para>
<para>As for scripting actions, if you create two files in your home directory with the following contents,
you'll have a fun surprise.</para>
<para><emphasis>dt.actions</emphasis>
<informalexample>
<screen>
&lt;!DOCTYPE actionsconfig>
&lt;actions>
&lt;action icon=<quote>mini-book1.png</quote> type=<quote>script</quote> name=<quote>usr_1</quote> \
	text=<quote>Shell</quote> > &lt;script output=<quote>message</quote> error=<quote>message</quote> \
	input=<quote>none</quote> >xterm&lt;/script>
&lt;/action>
&lt;/actions>
</screen>
</informalexample>
</para>
<para><emphasis>dt.toolbar</emphasis>
<informalexample>
<screen>
&lt;!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
&lt;kpartgui name="quanta" version="2">
  &lt;ToolBar tabname="My1stToolbar" name="dt" >
   &lt;text>My1stToolbar&lt;/text>
   &lt;Action name="usr_1" />
  &lt;/Toolbar>
&lt;/kpartgui>
</screen>
</informalexample>
Now click on <menuchoice><guimenu>Toolbars</guimenu>
<guimenuitem>Load Toolbars</guimenuitem>
<guimenuitem>Load Local Toolbar</guimenuitem>
</menuchoice>, browse to the dt.toolbar file in your home directory (remember to change the file mask to * from
*.toolbar.gz) and the action that you created is now loaded on a toolbar called My1stToolbar which is to the right
of the others.  Clicking on the action on the toolbar will give you an xterm window.
</para>
</sect2>
</sect1>

&quanta-menus;
&quanta-projects;

<sect1 id="templates">
<title>&quanta; Templates</title>
<para>
Templates are basically skeleton documents, code snippets and files to link to. &quanta; uses
templates fundementally as a standard file system with enhanced organization and interfacing.
You can copy, move or link any repository currently on your system into the templates tree.
Think of Quanta templates as having roughly the limitations to your imagination that your file system has.
</para>
<para>
Templates exist in nested directories. There is no limit to how deep you can nest them however within any
given directory Quanta expects a consistent action for the base template type described below. Additionally
templates allow for pre and post text to be concatonated to non document type templates. This facilitates
tag creation. The next update after the introduction is scheduled to add the ability to pass variables to
the text such as image size information to assist in tag creation.
</para>
<para>Our goal with templates is to extend them to include multi file "concept" templates useful for things
like placing an order or creating an about section, Ideally this will be a tool for making your work more
productive and dynamic. An eventual goal is to have a structural template design mode to deal with site
layout and structure which you could use to design and interactively update your sites. If you would like
to be involved, check out our
<ulink url="http://quanta.sourceforge.net/main1.php?contfile=needs">help wanted</ulink> page.</para>
<para><important><para>Some of the templates that ship with &quanta; have conditions for their usage.  Please read
carefully the usage statement of conditions at the top of each template before you use it.</para></important></para>

<sect2 id="template-types">
<title>Template types</title>
<para>
Currently templates are limited to being one of the following types of objects:
<simplelist>
<member>Document</member>
<member>Text to insert in a document</member>
<member>A file to link to form a document</member>
</simplelist>
</para>
<para>
Documents can be any type of document.
Generally you would want to nest more specific or diverse documents in subdirectories.
Here you can make a basic framework for what you do and deliver it to your work in an
organized fashion and realize much better effiency. Text insertion could be anything
from a snippet of code to a script or whatever you might wish to use.
This overlaps the ability to insert text blocks as an action which can be triggered from the toolbar.
Linked files can be binary, PHP class libraries or whatever.
</para>
</sect2>
<sect2 id="template-scope">
<title>Template scope</title>
<para>Templates are accessible based upon their established <link linkend="quanta-workspaces">workspace</link>
in &quanta;</para>
</sect2>

<sect2 id="creating-templates">
<title>Creating templates</title>
<para>Create a document structure that you love (XML, HTML, DocBook, etc.) and click on <menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as Template</guimenuitem>
<guimenuitem>Save as Local/Project Template</guimenuitem>
</menuchoice>.</para>
<para>Once this is done, you'll notice that (even if it's saved as a Project template) the template does
NOT show in the project tab view. Look into the templates view to find your template under the Project
templates tab.</para>
<para>Additinoally if you look at your options with the Right Mouse Button (RMB) you will see complete
file management tools for creatind directories or copying and pasting templates from one location to
another.</para>
</sect2>
<sect2 id="using-templates-with-projects">
<title>Using templates with Projects</title>
<para>Project templates allow you to be more tightly focused. You can create headers, footers or go
dynamic with PHP include files and link them. Additionally there are some very cool things we took
into consideration when using templates in projects.</para>
<para>When creating a project you can opt to copy over all global and user templates.
Legacy project get default templating abilities so nothing is lost
You can choose where to locate your template files so they can be in your server root and easy to upload or you
can make them secure to link to below server root which is a very cool trick
When linking to a file not in the project templates you will be prompted to copy the file to the project templates
prior to linking. This will prevent broken links on upload.
You always have control where you place your templates so you can choose to move them. However Quanta does not
track this so you will need to change links. This is a good task for kfilereplace which we are setting up to
plug in as a kpart.</para>
</sect2>
<sect2 id="managing-templates">
<title>Managing Template Behavior</title>
<para>Template structure on the <link linkend="treeview-icon-defs">template tab</link> is based on 
the files found in <filename class="directory">$<envar>KDEDIR</envar>/share/apps/quanta/templates</filename> 
and <filename class="directory">$<envar>HOME</envar>/.kde/share/apps/quanta/templates</filename>.  Each of
these directories is specified as one of three types of container:</para>
<variablelist>
<varlistentry>
<term>files/all</term>
<listitem><para>binaries and such things that get inserted by their url (ie images as an
&lt;img src=/src/url></para></listitem>
</varlistentry>
<varlistentry>
<term>text/all</term>
<listitem><para>text that you can insert into the current quanta document. stuff like repetitive
blocks etc</para></listitem>
</varlistentry>
<varlistentry>
<term>template/all</term>
<listitem><para>document templates which you can create new documents from. these open a new window
in quanta.</para></listitem>
</varlistentry>
</variablelist>
<para>To set the behavior of each directory, righ-click in the template view on the directory and
choose proerties.  The folowing dialog will come up:
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="template-rmb.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term>Type</term>
<listitem><para>Drop down box with the three types discussed prefiously; files, text, template.
This box will be grayed out if you have the inheret parent attribute box checked.</para></listitem>
</varlistentry>
<varlistentry>
<term>Inherit parent attribute (&lt;blah>)</term>
<listitem><para>This is checked by default and is fine for all but the top level directories
in your templates tree.  If the top level directory has this checked, it will basically
deactivate templates for that directory and all that aren't explicitly set below it.  If this
is not a top level directory, then the &lt;blah> will say something like text/all.  If it says
nothing, then chances are that you're on a top level directory.</para></listitem>
</varlistentry>
<varlistentry>
<term>Use pre/post text</term>
<listitem><para>Enables pre and post text for templates in this directory.  This could be a common
header/footer for all of your templates for a given project and then you copy content templates
into that directory and have a complete page with the custom header/footer as a starting point.
</para></listitem>
</varlistentry>
<varlistentry>
<term>Pre-text</term>
<listitem><para>The actual text to insert before your templates content.</para></listitem>
</varlistentry>
<varlistentry>
<term>Post-text</term>
<listitem><para>The actual text to insert after your templates content.</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
</chapter>
