The Kaspaliste Handbook

Jan Müller

Revision 0.91.00

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This Handbook describes Kaspaliste Version 0.91


Table of Contents

1. Introduction
Kaspaliste Revision History
2. Using Kaspaliste
Publications And Notes
The User Interface In General
The Publication View
The Bibliography View
The Chapter View
The Data View
The Note View
The Author View
The Overview Widgets
Searching
BibTex Support
3. Questions and Answers
4. Credits and License
A. Installation
How to obtain Kaspaliste
Requirements
Upgrade - Important, if you upgrade from a version earlier than v0.34!
Compilation and installation
Upgrading to a new postgres version (from Kaspaliste v0.42 and earlier)

Chapter 1. Introduction

Work in progress. The documentation is still incomplete and needs proofreading.

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.

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.

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.

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.

Another feature is the automatic generation of BibTex files.

Whats new in version 0.92?

  • The search now works like a search machine for the internet.
  • Printing support.

Whats new in version 0.91?

  • 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
  • Import/export for files is done via drag'n drop. External references are possible.
  • Hierarchical notes.
  • Define the order of authors (important for BibTex).
  • Many minor changes like improved documentation, reworked user interface and bugfixes
  • Improved documentation.

Kaspaliste Revision History

  • Aug. 2000 - The first public version.

  • v0.31 - minor bugfixes and improvements, libpg++ is obsolete.

  • v0.32 - simplified installation, libg++ is obsolete, the user_lock patch is no longer needed.

  • v0.33 - cleanups, bugfixes, export of files, complete cut/copy/paste - support

  • v0.34 - bugfix

  • v0.4 - port to KDE 2.1, works with mimetypes and kparts

  • v0.41 - bugfixes and improvements

  • v0.42 - bugfixes

  • v0.90 - port to KDE 3, many improvements

  • v0.91 - improved documentation, fixed a packaging error

  • v0.92 - improved search, printing support

Chapter 2. Using Kaspaliste

Publications And Notes

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.

There are two basic concepts:

  • Publications
  • Notes

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.

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.

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.

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.

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.

The general structure of the tables and the relations is shown in the figure:



The following sections describe the elements in detail.

The User Interface In General

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.

The following figure explains some elements of the user interface.



The Publication View

A "publication" holds general information about books, collections, articles, reports such as...

  • the title
  • the year of the publication
  • the publisher or journal (included from a list)
  • the BibTex type like article, incollections
  • links to authors and chapters
  • annotated links

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.



Clicking the bibliography button leads to the...

The Bibliography View



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.

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.

The Chapter View

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.

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.

Some fields of the chapter view may be disabled, depending on the chosen BibTex-type. See section Bibliography.

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.



The Data View

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.

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.



The Note View

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.



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.

The Author View

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.



The Overview Widgets

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.

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.



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".

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.

Searching

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).



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.

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.

BibTex Support

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.

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.



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).

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.

Chapter 3. Questions and Answers

3.1. Any questions?
3.1.

Any questions?

Feel free to contact me. I try to answer any mails I get. It may take hours, days or even weeks. If you think it takes too long send the mail again. Thanks.

Chapter 4. Credits and License

Kaspaliste

Program copyright 1998-2002 Jan Müller<janmueller7@hotmail.com>

Documentation copyright 1998-2002 Jan Müller<janmueller7@hotmail.com>

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.

Appendix A. Installation

How to obtain Kaspaliste

Kaspaliste is part of the KDE project. Kaspaliste can be found on the main ftp server of the kde project or on a mirror.

The homepage of Kaspaliste is located at http://site.voila.fr/janmueller/ Check this site for information and updates.

Requirements

The program needs postgresql as server. It has been tested with KDE v3.0 and postgresql v7.2. Postgresql can be found on the postgresql homepage.

Upgrade - Important, if you upgrade from a version earlier than v0.34!

The version 0.34 introduced a timestamp feature. It is necessary to update the underlying table structure of the earlier versions:

%psql kaspaliste -f kaspaliste/data/update.sql

Compilation and installation

In order to compile and install Kaspaliste on your system, type the following in the base directory of the Kaspaliste distribution:

%./configure
%make
%make install

Since Kaspaliste uses autoconf you should have not trouble compiling it.

Kaspaliste needs postgresql as server. For installation details look at the postgresql documentation. You have to initialize the postgresql manager if you don't have already an existing postgresql installation. Parameters are the directory where the database should live (e.g. /home/xyz/pgdata) and the username (e.g. your login).

%initdb --username=MY_USERNAME MY_PGSQL_DATADIR

Start the postmaster (Read the postmaster manpage for a more sophisticated command line):

%postmaster -DMY_PGSQL_DATADIR

First you have to create a database named kaspaliste:

%createdb kaspaliste

Read the file kaspaliste/data/create.tables.sql from the kaspaliste directory with the command:

%psql kaspaliste -f create.tables.sql

Now you are ready to start the frontend. Should you run into problems please report them to the author at Jan Mueller

Upgrading to a new postgres version (from Kaspaliste v0.42 and earlier)

BACKUP YOUR OLD DATABASE! Depending on the version the conversion process might be quite complex! When upgrading to a new postgres version a dump/reload of the database might be necessary (check the postgresql documentation). The pg_dump utility of the postgres distribution does not dump large objects. There are two little programs named loadlo and unloadlo. They read/write all large objects from/in a directory. The directory has to be accessible by the server. To make them work correctly it is important to preserve the oids while dumping with the -o option of pg_dump. loadlo has to be run after loading the dumped script with psql by the postgres superuser.:

dump old database...

%md /tmp/dump
%pg_dump kaspaliste -ov /tmp/dump/dump.sql
%unloadlo -o /tmp/dump

...upgrade database and reload...

%psql kaspaliste -f /tmp/dump/dump.sql
%loadlo -i /tmp/dump

From v0.43 on Kaspaliste does not use large objects anymore. So upgrading will be easier in the future.