<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kaspaliste '<application>Kaspaliste</application>'>
  <!ENTITY kapp "&kaspaliste;"><!-- replace kaspaliste here -->
  <!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   -->
<!-- ................................................................ -->

<!-- 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 Kaspaliste Handbook</title>

<authorgroup>
<author>
<firstname>Jan</firstname>
<othername></othername>
<surname>M&uuml;ller</surname>
<affiliation>
<address><email>janmueller7@hotmail.com</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>1998-2002</year>
<holder>Jan M&uuml;ller</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>2002-02-27</date>
<releaseinfo>0.91.00</releaseinfo>


<!-- Abstract about this handbook -->

<abstract>
<para>
This Handbook describes &kaspaliste; Version 0.91
</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>database</keyword>
<keyword>literature</keyword>
<keyword>kaspaliste</keyword>
<keyword>knowledge</keyword>
<keyword>bibtex</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<important><para>
Work in progress. The documentation is still incomplete and needs proofreading.
</para>
<para>
This program is BETA software! It is based on a reliable database server,
so complete data loss is not
very likely. But other (hopefully minor) problems may occur.
BACKUP YOUR DATABASE FRREQUENTLY AND KEEP OLD BACKUPS!
I think it's obvious: I'm not a native english speaker. Corrections are welcome.
</para>
</important>
<para>
&kaspaliste; is a literature database. It handles all kinds of books, articles, journals, webpages etc.
The database goes beyond storing bibliographical information. There is the possibility
to create annotated links between pieces of information (like the content of a book chapter) and to group
links into categories.
</para>
<para>
The user interface works just like a web browser: You may follow the links to open records.
You may walk back and forward through previously edited records, change fields, and create
or delete links, publication, authors etc. on the fly with just one mouseclick.
</para><para>
&kaspaliste; does not only store pieces of information about publications. It stores files as well. Kaspaliste handels
various formats like html, pdf, ps, dvi and pictures (depends on your KDE-installation since
the kpart-technology is used).
You can for example store ocr'ed parts of interesting publications. The fulltext search covers
these files.
</para><para>
Another feature is the automatic generation of BibTex files.
</para>
<sect1 id="whatsnew">
<title>What is new?</title>
<para>
Whats new in version 0.92?
<itemizedlist>
<listitem><para>The search now works like a search machine for the internet.</para></listitem>
<listitem><para>Printing support.</para></listitem>
<listitem><para>Defining the postgresql connection with a commandline option, eg. to connect to a remote server.</para></listitem>
<listitem><para>BibTex: Many latin1 special characters are translated to their latex pendants</para></listitem>
<listitem><para>New configure/make - scripts</para></listitem>
<listitem><para>Compiles with gcc 3.2 (thanks to Sebastian Pickerodt).</para></listitem>
<listitem><para>Bugfixes</para></listitem>
</itemizedlist>
</para>
<para>
Whats new in version 0.91?
<itemizedlist>
<listitem><para>Better fulltext search. The search is now done by the database and not by a subprocess.
This should be more stable. It requires postgresql 7.2. or higher</para></listitem>
<listitem><para>Import/export for files is done via drag'n drop. External references are possible.</para></listitem>
<listitem><para>Hierarchical notes.</para></listitem>
<listitem><para>Define the order of authors (important for BibTex).</para></listitem>
<listitem><para>Many minor changes like improved documentation, reworked user interface and bugfixes</para></listitem>
<listitem><para>Improved documentation.</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="kaspaliste-revhistory">
<title>Kaspaliste Revision History</title>
<para>
<itemizedlist>
<listitem><para>Aug. 2000 -	The first public version.</para></listitem>
<listitem><para>v0.31 - minor bugfixes and improvements, libpg++ is obsolete.</para></listitem>
<listitem><para>v0.32 - simplified installation, libg++ is obsolete, the user_lock patch is no longer needed.</para></listitem>
<listitem><para>v0.33 - cleanups, bugfixes, export of files, complete cut/copy/paste - support</para></listitem>
<listitem><para>v0.34 - bugfix</para></listitem>
<listitem><para>v0.4 - port to KDE 2.1, works with mimetypes and kparts</para></listitem>
<listitem><para>v0.41 - bugfixes and improvements</para></listitem>
<listitem><para>v0.42 - bugfixes</para></listitem>
<listitem><para>v0.90 - port to KDE 3, many improvements</para></listitem>
<listitem><para>v0.91 - improved documentation, fixed a packaging error</para></listitem>
<listitem><para>v0.92 - improved search, printing support</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="knownbugs">
<title>Known Bugs</title>
<para>
<itemizedlist>
<listitem><para>A very serious one: non-latin1 characters are not supported, even if the postgresql database was created with the correct character set :-(((. Not easy to fix. I'm working on a rewrite which is based on unicode, but this will take some time.</para></listitem>
</itemizedlist>
</para>
</sect1>
</chapter>


<chapter id="using-kaspaliste">
<title>Using &kaspaliste;</title>
<sect1 id="publnotes">
<title>Publications And Notes</title>
<para>
&kaspaliste; has become a quite complex application. Read the following instructions to understand
the concepts behind the database. They are not that obvious at the first glance.
</para>
<para>
There are two basic concepts:
<itemizedlist>
<listitem><para>Publications</para></listitem>
<listitem><para>Notes</para></listitem>
</itemizedlist>
</para>
<para>
&kaspaliste; was created to handle pieces of information. This is done via publications.
A publication is a piece of information like a book, an aricle from a journal, the journal itself,
a recorded interview or a website. A publication has bibliographical data like the publisher, the author(s),
the volume, an editor, a translator and so on. Moreover a publication has some kind of content.
The text itself for example or a recording. Many publications are divided into parts (like chapters of a book).
&kaspaliste; allows to create those publications, parts, authors, journals and publishers and to create the
relationsships among these items.
</para>
<para>
Example: Say there is a journal called "KDE Quarterly". The issues are available in the internet.
One may download each article as a pdf file. You are interested in two articles:
"Towards A Theory Of KDE" by R. Miller and "Foundations Of KDE" by F. Meier.
So create a new publication "Towards A Theory Of KDE".
Fill in the bibliographical information (issue, year of publication, editor etc.). Create a new journal
"KDE Quarterly" if necessary and link it to the publication. Create a part "Towards A Theory Of KDE".
Create or - if already there - insert the author "R. Miller". Download the pdf file and add it to the part.
Create a second part "Foundations of KDE" and add the author and the pdf file. Now you have a representation
of the journal and the articles and all the relevant data. You may create automatically BibTex entries for
the articles. You may read the pdf files inside &kaspaliste; and annotate them. &kaspaliste; offers a fulltext
search which covers the content of the pdf files.
</para>
<para>
The second concept is the concept of "notes". Many of the publications are related to each other.
The have the subject in common or they cover similar topics from different perspectives. It might be
very interesting to create links between related pieces of information and to group similar
or contrast different content. Often one has some ideas and interpretations and one wants to
note it together with the content itself. The ideas may lead to a certain
structure of links among the content.
</para>
<para>
&kaspaliste; offers "notes" the achieve this goal. A note may be linked to one or more authors, publications,
parts, files and other notes. One may create a note called "KDE In General" and link it to all publications,
parts, files and authors which cover this topic. In addition one may link it to similar notes.
</para>
<para>
If one would link everything to everything the whole thing would become very chaotic and difficult to handle.
So there are two types of notes: Toplevel notes and publication notes. Toplevel notes may link to other notes
(toplevel and publication notes) and authors. Publication notes may link to parts, files and to the
publication window of one publication and to toplevel notes. Use the toplevel notes to create categories
(like "KDE In General" or "Postmodern Philosophy"). Use publication notes to annotate publications.
</para>
<para>
The general structure of the tables and the relations is shown in the figure:
<mediaobject>
  <imageobject>
    <imagedata fileref="scheme.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
The following sections describe the elements in detail.
</para>
</sect1>

<sect1 id="userinterface">
<title>The User Interface In General</title>
<para>
Most elements of the user interface should be self-explanatory.
The only uncommon element is the
browser-like input line in the upper toolbar. It allows direct manipulation of the internals of the
database. The name of the view (e.g. publication) is followed by an SQL-where clause after
an '#'-character or an command (e.g. 'new') after an questionmark. Manipulating the where
clause allows very complex queries.
</para>
<para>
The following figure explains some elements of the user interface.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="navigation-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
</sect1>

<sect1 id="publication">
<title>The Publication View</title>
<para>
A "publication" holds general information about books, collections, articles, reports such as...
<itemizedlist>
<listitem><para>the title</para></listitem>
<listitem><para>the year of the publication</para></listitem>
<listitem><para>the publisher or journal (included from a list)</para></listitem>
<listitem><para>the BibTex type like article, incollections</para></listitem>
<listitem><para>links to authors and chapters</para></listitem>
<listitem><para>annotated links</para></listitem>
</itemizedlist>
</para>
<para>
The interpretation of the publisher/journal field depends on the BibTex-type. The entry is taken
as name of the journal if the BibTex is ARTICLE or JOURNAL, if not, the entry is interpreted as
publishers name. The order of the authors (important for BibTex) can be changed by clicking the right
mouse button and choosing "Move Item Up" or "Move Item Down" from the context menu.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="publication-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
Clicking the bibliography button leads to the...
</para>
</sect1>

<sect1 id="biblio">
<title>The Bibliography View</title>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="biblio-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
Bibliography holds more specific information. The fields change with the selected BibTex-Type
and represent the complete data to construct a BibTex database entry. The actual BibTex-Entry is
generated and displayed by clicking the "Generate BibTex" - button. The generated entry can be edited
for finetuning.
</para>
<para>
There are two sorts of BibTex entrys: One-level entrys like BOOK, REPORT or MANUAL on the
one hand and on the other hand entrys like INCOLLECTION, INPROCCEDING or ARTICLE.
A latter are collections of textes which are authored by different persons but altogether
published in one book. The general bibliographical information is generated in
bibliography and crossreferenced with the individual BibTex entrys. These entries are generated in
the chapter view.
</para>
</sect1>
<sect1 id="chapters">
<title>The Chapter View</title>
<para>
The concept of the chapter view does not differ much. The included files and the connected links
are shown. You may import external files via Drag'n Drop. Just drag a couple of files from Konqueror
to the files field and drop them. A popup menu shows up. Two options are possible:
Importing the whole file or creating a reference to the file. The first option loads the file
into the database. It parses the file if possible makes the content available to the
fulltext search. The second option creates a reference to an external file.
Select a file and click the right mouse button to export an internal file. A context menu
opens up. Select "Export" to export the file.
</para>
<para>
A chapter can have authors, too. Think of a journal with articles or a collection of textes. Choose
the appropriate publication type in the publication view.
The order of the authors (important for BibTex) can be changed by clicking the right
mouse button and choosing "Move Item Up" or "Move Item Down" from the context menu.
</para>
<para>
Some fields of the chapter view may be disabled, depending on the chosen BibTex-type.
See section <link linkend="biblio">Bibliography</link>.
</para>
<para>
A chapter has a second view. Click the "Show Memo" button (a book with a sheet of paper) from the toolbar.
A new view is displayed. It offers a rich text editor.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="part-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
</sect1>
<sect1 id="data">
<title>The Data View</title>
<para>
Clicking on a file in the chapter view opens the file in his own widget. Depending on the mimetype
&kaspaliste; loads the apropriate widget to display the file inside the programm.
This covers (with the kde3 installation) pdf, ps, dvi and html files, pictures and sound files.
Postgres allows the storage of object of unlimited size and even storing recorded interviews
is possible.
</para>
<para>
One may connect notes to files, too. This dialog includes a rich text editor. One may type ideas
or interesting citations from the displayed file.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="data-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
</sect1>
<sect1 id="links_categoriers">
<title>The Note View</title>
<para>
There are two types of notes available: "publication notes" and "toplevel notes".
These two kinds of notes were created to avoid the mess which results from
linking chapters, authors and publications directly together.
The solution is to allow arbitrary links via publication notes between
all elements of one publication with his decendents (chapters and data files). Direct links
between different publications are forbidden. In a second step the links can be connected to a
more general categorie: a toplevel note. Toplevel notes can connect to other toplevel and
publication notes. But they can not link directly to publications, parts or files.
</para>
<mediaobject>
  <imageobject>
    <imagedata fileref="note-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
<para>
The example shows a toplevel note bundeling all pieces of information about an author.
A note offers a rich text editor to annotate the link.
</para>
</sect1>
<sect1 id="author">
<title>The Author View</title>
<para>
After all, the author view does not introduce special features.
It holds information about the author like name, year of birth and space for annotations.
One may link more publications and parts to an author. Use the toolbar.
The publications and parts authored by this person are shown.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="author-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
</sect1>
<sect1 id="overview">
<title>The Overview Widgets</title>
<para>
The overview widgets
provide an overview over authors, publications, publishers, journals and notes.
They are sorted in alphabetical order. Click an entry to open it or open a new window
via the context menu. One may open the context menu by clicking the right mouse button.
</para>
<para>
The notes overview is more complex. Remember, there are two kinds of notes: toplevel notes
and publication notes. As the default behaviour the notes overview shows the toplevel notes.
These notes are preceded by a graphic of a sheet of paper. Publication notes are added if one
clicks on the "book" item in the widget toolbar. Publication notes are preceded by a graphic
of a book.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="noteoverview-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
Toplevel notes may be orderd hierarchically. They may form a tree: Some elements include
other elements. A note including subnotes is shown with a cross. Click the cross
to have a look at the subordered notes.
The note "philosophy" for example might be a supernote for "postmodern philosophy",
"greek philosophy" and "existensialism".
</para>
<para>
Use drag'n drop to move notes around. Each hierarchy of notes is automatically sorted in
alphabetical order. Use the context menu to insert or create subnotes. The context menu pops
up when the right mouse button is clicked.
</para>
</sect1>
<sect1 id="searching">
<title>Searching</title>
<para>
Searching includes a fulltext search over all included data files (the types of the files to be
included or excluded can be chosen from the "Search Options" dialog). If the fulltext
search is disabled (e.g. for performance reasons) the search runs over the title and name fields of the
tables. With the Exact Search checkbox checked only exactly matching records or words are
returned. If not checked, the search expression is splitted into words. The result records
include each word (like a search machine for the internet).
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="search-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
Fulltext search is easy for all kinds of plain text (like html). &kaspaliste; offers a way to
search over pdf and ps files, too. How is this done? The file is loaded into the database.
&kaspaliste; identifies the mimetype of the file and executes a filter command. This command
(if given) converts the data (pdf, html, postscript...) to plain text.
The plain text is stored and used for the fulltext search.
</para>
<para>
The search is configured by the "Setup Mimetypes" dialog. One may open this dialog via the
"Settings" menu.

There is a special dialog initializing the index of the fulltext search. The Start button
launches the parser. The parser detects the new and changed objects and includes the content in the
index. Rebuild means that the index will be rebuild from the scratch. The process can be
interrupted at any time - with the Cancel button. The parser will catch the signal and
terminate as quick as possible.
</para>
</sect1>
<sect1 id="bibtex">
<title>BibTex Support</title>
<para>
BibTex is an extension of the LaTex text processor. Publications and citations
are defined in a general format. BibTex creates automatically bibliographies in
different formats.
</para>
<para>
&kaspaliste; supports BibTex by converting the publications given in &kaspaliste; to
the BibTex format. Both the bibliography view and the part view have a button
labeled "Generate BibTex". Press the button to generate a new BibTex entry from
the bibliographical data of the publication. It is displayed in a text field for
futher editing and fine tuning. Check "Include in BibTex" to include the entry in
the BibTex file. Choose the "Generate BibTex" entry from the file menu to create the file.
</para>
<para>
<mediaobject>
  <imageobject>
    <imagedata fileref="bibtex-doc.png" format="PNG"/>
  </imageobject>
</mediaobject>
</para>
<para>
In bibliographies the order of the authors are important. They have the same order as
the authors in &kaspaliste;. In &kaspaliste; the order of the authors may be changed with
the context menu (pops up by clicking the right mouse button).
</para>
<para>
The names of the BibTex entries consist of the last name of the author followed by the year of publication
of the item. If there is more than one entry with the same name, letters ("a", "b" etc.) are added.
</para>
</sect1>
</chapter>


<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>How can I connect to a database on a remote server?</para>
</question>
<answer>
<para>You specify via the command line parameter "-conn" the
name of the database, the connection, the user name and so on.
Parameters are dbname, host, user, passwort, hostaddr and port.
They have to be separated by spaces.
</para>
<para>
The following will open a database connection to database "kaspaliste"
on host "myhost" with the username "myuser".
<screen width="40">
<prompt>%</prompt><userinput>kaspaliste -conn "dbname=kaspaliste host=myhost user=myuser"</userinput>
</screen>
The default is simply "dbname=kaspaliste".
Have a look at the postgresql developers guide,
section "2.2. How Connections are Established" for further details..
</para>
</answer>
</qandaentry>
</qandaset>
</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>

<para>
&kapp;
</para>
<para>
Program copyright 1998-2002 Jan M&uuml;ller<email>janmueller7@hotmail.com</email>
</para>
<!--
<para>
Contributors:
<itemizedlist>
<listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para></listitem>
<listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para></listitem>
</itemizedlist>
</para>
-->
<para>
Documentation copyright 1998-2002 Jan M&uuml;ller<email>janmueller7@hotmail.com</email>
</para>

<!-- 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>

<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-kaspaliste">
<title>Where to find informations about installation?</title>
<para>
The file "INSTALL" in the kaspaliste distribution covers installation and upgrade details.
</para>
</sect1>
</appendix>

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