# The Kaspaliste Handbook

Jan
Müller

    janmueller7@hotmail.com

1998-2002
Jan Müller
&FDLNotice;
2002-02-27
0.91.00

This Handbook describes &kaspaliste; Version 0.91

KDE
database
literature
kaspaliste
knowledge
bibtex

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

### What is new?

Whats new in version 0.92?

- The search now works like a search machine for the internet.

- Printing support.

- Defining the postgresql connection with a commandline option, eg. to connect to a remote server.

- BibTex: Many latin1 special characters are translated to their latex pendants

- New configure/make - scripts

- Compiles with gcc 3.2 (thanks to Sebastian Pickerodt).

- Bugfixes

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

### Known Bugs

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

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

## Questions and Answers

&reporting.bugs; &updating.documentation;

How can I connect to a database on a remote server?

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.

The following will open a database connection to database "kaspaliste" on host "myhost" with the username "myuser".

    %kaspaliste -conn "dbname=kaspaliste host=myhost user=myuser"

The default is simply "dbname=kaspaliste". Have a look at the postgresql developers guide, section "2.2. How Connections are Established" for further details..

## Credits and License

&kapp;

Program copyright 1998-2002 Jan Müllerjanmueller7@hotmail.com

Documentation copyright 1998-2002 Jan Müllerjanmueller7@hotmail.com

&underFDL;

&underGPL;

## Installation

### Where to find informations about installation?

The file "INSTALL" in the kaspaliste distribution covers installation and upgrade details.

&documentation.index;