<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY knoda '<application><emphasis>Knoda</emphasis></application>'>
  <!ENTITY hk_classes '<application><emphasis>hk_classes</emphasis></application>'>
  <!ENTITY kapp "&knoda;">
  <!ENTITY kapp "&hk_classes;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->


  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001   -->

<!--
This template was designed by: David Rugge davidrugge@mindspring.com
with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
of the KDE DocBook team.

You may freely use this template for writing any sort of KDE documentation.
If you have any changes or improvements, please let us know.

In the future, we may want to change from SGML-based DocBook to XML-based
DocBook. To make this change easier, please be careful :
- in XML, the case of the <tags> and attributes is relevant ;
- also, quote all attributes.

Please don't forget to remove all these comments in your final documentation,
thanks ;-).
-->

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The Knoda Handbook</title>

<authorgroup>
<author>
<firstname>Horst</firstname>
<surname>Knorr</surname>
<affiliation>
<address><email>hk_classes@knoda.org</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2004</year>
<holder>Horst Knorr</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>11/22/2004</date>
<releaseinfo>0.00.02</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>DBMS</keyword>
<keyword>Kapp</keyword>
<keyword>database</keyword>
<keyword>frontend</keyword>
<keyword>mysql</keyword>
<keyword>odbc</keyword>
<keyword>postgres</keyword>
<keyword>postgresql</keyword>
<keyword>sqlite</keyword>
<keyword>sqlite2</keyword>
<keyword>sqlite3</keyword>
<keyword>knoda</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&knoda; is a database frontend and comprises queries, forms and reports, which scriptable via Python.
There are tutorials and API references available at <ulink
url="http://hk-classes.sourceforge.net">http://hk-classes.sourceforge.net</ulink>. Please see the &knoda; tutorial for further information.
</para>
<para>
Drivers for the following backends are available:
<itemizedlist>
<listitem><para><ulink url="http://www.mysql.com/">Mysql</ulink></para></listitem>
<listitem><para><ulink url="http://www.postgresql.org">Postgres</ulink></para></listitem>
<listitem><para><ulink url="http://www.unixodbc.org">ODBC</ulink></para></listitem>
<listitem><para><ulink url="http://www.sqlite.org">SQLite</ulink> (local file format)</para></listitem>
</itemizedlist>

</para>
</chapter>


<chapter id="options">
<title>The Options dialog</title>
<para>
&knoda; can be highly configured to fit your needs.To do so press the "Options"-button in the main window.
</para>

 <sect1 id="generaloptions">
 <title>General options</title>
 <para>
In the 'General'- options menu you can set:
<itemizedlist>
<listitem><para>the <emphasis>driverpath</emphasis>: the directory where the database drivers are located</para></listitem>
<listitem><para>the <emphasis>default driver</emphasis>: the driver which is displayed in the &knoda; main window as default</para></listitem>
<listitem><para><emphasis>show maximised</emphasis>: Tables, queries, forms and reports can either be shown in their construction size
or maximized</para></listitem>
<listitem><para>Show all questions:Per default &knoda; asks questions like "Are you sure?" before executing actions</para></listitem>
</itemizedlist>
 </para>

 </sect1>


<sect1 id="defaultsoptions">
<title>Defaults options</title>
<para>
The 'Defaults'- section allows you to define the look of your data.
<itemizedlist>
<listitem><para><emphasis>Default font</emphasis>: the font which is used to display grids, forms and reports</para></listitem>
<listitem><para><emphasis>Text alignment</emphasis>: the alignment of text data</para></listitem>
<listitem><para><emphasis>Number alignment</emphasis>: the alignment of numeric data</para></listitem>
<listitem><para><emphasis>Separator</emphasis>: whether numbers should include the thousands separator (only valid if this is supported by locale)</para></listitem>
<listitem><para><emphasis>Precision</emphasis>: the numeric precision of floating data</para></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="regionaloptions">
<title>Regional options</title>
<para>
&knoda; uses the German format for displaying the date and time.  If you want or need to change it,
 no problem.
If you are not happy with the date "31.12.2001" and prefer "2001-12-31", enter Y-M-D in the date
 field.  The 'Date &amp; Time format' is needed for fields which have both, date and time data.
<itemizedlist>
<listitem><para>D - Day</para></listitem>
<listitem><para>M - Month</para></listitem>
<listitem><para>Y - Year</para></listitem>
<listitem><para>h - hour</para></listitem>
<listitem><para>m - minute</para></listitem>
<listitem><para>s - second</para></listitem>
</itemizedlist>

</para>
</sect1>


<sect1 id="reportoptions">
<title>Report options</title>
<para>
There are some options you should set before using reports.  First is your character set encoding.  If
 you are using unicode, set the encoding to that which comes closest to your requirements.
If you want to use KDE's new kprinter dialog, change the printer command from 'lpr' to 'kprinter'.
</para>
</sect1>




</chapter>

<chapter id="driverspecific">
<title>Driver specific information</title>

<sect1 id="mysql">
<title>Mysql</title>
<para>
The password dialog has an entry called "Emulate boolean". Mysql itself does not support internally a boolean field type (even if you can use boolean  in CREATE TABLE statements). If "Emulate boolean" is set to 'yes', &knoda; interpretes the Mysql specific field type TINYINT as a boolean field. 
</para>
</sect1>

<sect1 id="postgres">
<title>Postgres</title>
<para>
Depending on the way Postgres is configured, the login parameters differ. Try to leave "hostname" empty.
</para>
<para>
Postgres has one -well- bit strange behaviour. It needs a database name as connect parameter, even to get a list of the existing database names on a server. Per default &hk_classes; uses 'template1' as name. If you don't have permission to connect to this database, you must enter an existing  database name where you have the permission to connect. In all other cases you can leave the database name field empty.
</para>

</sect1>

<sect1 id="odbc">
<title>ODBC</title>
<para>
For those wanting to connect to M$ SQLServer the project <ulink url="http://www.freetds.org">FreeTDS</ulink> is recommended.
</para>
</sect1>

<sect1 id="sqlite">
<title>SQLite</title>
<para>
SQLite is a file based database system. Per default the files are stored in ~/.hk_classes/sqlite2/localhost (SQLite 2.x) and ~/.hk_classes/sqlite3/localhost (SQLite 3.x) respectively and have the extenstions .hk_sqlite(2|3). Knoda can handle database files in other directories. You need to enter the full path in addition to the name (Menu point 'Open local database'). 
</para>
</sect1>

</chapter>

<chapter id="tipstricks">
<title>Tips and tricks</title>

<sect1 id="tutorialdocumentation">
<title>How can I learn using &knoda;?</title>
<para>
See the <ulink url="http://hk-classes.sourceforge.net/tutorials/knoda/index.html">&knoda; tutorial</ulink>.
</para>

</sect1>


<sect1 id="development">
<title>Which database backend should I use / do you recommend?</title>
<para>
It depends totally on what you want to do. If you did use Access or if you want to exchange the whole database with others, the database should be stored in a single file. Then SQLite is your choice.
</para>
<para>
Multi user databases should prefer either Mysql or Postgres.
</para>

</sect1>


<sect1 id="installation1">
<title>Knoda does not find my database driver!</title>
<para>
Probably it is not compiled. &hk_classes; tries to autodetect the database backends. If your database
server is installed, but &hk_classes; does not find it, you probably have to install the "database devel-rpm" of your distribution. Example: For Mysql it is called mysql-devel.rpm (exact name is distribution specific). Then you can re-configure and recompile &hk_classes;.
</para>

</sect1>


<sect1 id="sql">
<title>Which SQL syntax can I use?</title>
<para>
You can use the SQL syntax of your backend server. There is one major difference you have to
take account of: only use the ANSI SQL delimiters (both textdelimiters and identifier delimiters),
which are
<itemizedlist>
<listitem><para><emphasis>textdelimiter</emphasis>: a single quote '</para></listitem>
<listitem><para><emphasis>identifier delimiter</emphasis>: a double quote "</para></listitem>
</itemizedlist>
The advantage of this is that you can copy whole databases between backends 
(e.g. from Mysql to Postgres) via drag&amp;drop and the query still works.

So a correct SQL statement would be:
<example><title>Sample SQL statement</title>
<programlisting>
SELECT "mytablealias"."fieldname" FROM "testtable" AS "mytablealias"
WHERE "myfield"='mystring'
</programlisting>
</example>
You can use all functions your SQL backend provides, but it is up to you to make sure that your
 SQL statement is compatible between backends.
Do not use TRUE or FALSE in your query statements.  Use %TRUE% and %FALSE% instead.  Some SQL database servers do not support the use of
 boolean fields, so the &hk_classes; have to simulate boolean fields.  A valid SQL statement would be:
<screen>
select * from mytable where myboolfield=%TRUE%
</screen>
</para>
</sect1>







<sect1 id="centralstorage">
<title>Where are queries, forms and reports stored?</title>
<para>
Per default all files are stored in the directory ~/.hk_classes/&lt;SQLSERVER&gt;/&lt;HOST&gt;/&lt;DATABASENAME&gt;.
</para>
<para>
Example: If you have a Mysql database named exampledb on your local host, it would be
 /home/horst/.hk_classes/mysql/localhost/exampledb
</para>
<para>
It is possible to store these objects within your database. Open the database and select 'Administration'->'Database settings'.
There you first have to create a hidden system table called 'HKCLASSES' and then you can select which objects have to be
stored where.
 
</para>
</sect1>




<sect1 id="copy">
<title>How to copy databases and tables between different database backends</title>
<para>
You want to convert a Mysql database to a Postgres database or vice versa? No problem, open the Mysql database you want to copy and any Postgres database. Drag the database name from the left window (there where you can see the tables, queries, forms and reports) and drop it in the left window of the target window, see and stun. A new database will be created and the data converted. This works from/to any backend.
</para>
</sect1>







<sect1 id="pythondocumentation">
<title>I want to write scripts!</title>
<para>
Knoda can be scripted using <ulink url="http://www.python.org">Python</ulink>. See <ulink url="http://hk-classes.sourceforge.net/tutorials/knodapython/index.html">&knoda; scripting tutorial</ulink>. If you need a reference see <ulink url="http://hk-classes.sourceforge.net/tutorials/pythonreference/index.html">&knoda; scripting reference</ulink>. 
</para>

</sect1>

</chapter>

<!--
<chapter id="dummychapter">
<title>Dummy chapter</title>

<sect1 id="dummysection">
<title>Dummy section</title>
<para>
</para>
</sect1>

</chapter>
-->


<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>


<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>



</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->