About DiskSearch
----------------

DiskSearch is a tool for searching for files on all your removable media
disks (e.g. CD's, ZIP disks or backup tapes). For instance you can search
for songs on your MP3-CD's or for a document on your backup DVD's. 
For advanced queries there is a regular expression search mode.
The search is based on a simple database file which needs to be filled
once by adding all your disks to it.

Since version 0.9.0 the projects has been renamed from 'CDSearch' to 
'DiskSearch' because it's possible to archive many types of removable 
media now.

Starting with version 1.0.0 DiskSearch supports internationalization, 
currently the languages english (default), french, german, italian,
polish and spanish are included. Interested users could create and send
us other translations too.


Requirements
------------

DiskSearch is written in Python using the Python bindings for the GTK+ 
toolkit. So you need: 

- Python >= 2.4 (from http://www.python.org)
- GTK+ >= 2.8.0 (from http://www.gtk.org)
- PyGTK >= 2.8.0 (from http://www.pygtk.org)
  (make sure that PyGTK contains libglade support)

DiskSearch is tested on GNU/Linux (e.g. Ubuntu 7.04) and Windows XP,
although it should work on all Unix-like and Win32 systems.


Installation on Linux or other Unix-based systems
-------------------------------------------------

To install DiskSearch extract the archive to some temporary directory and 
run 'make install' as root. This will install DiskSearch to '/usr/local'.
You can also simply uninstall DiskSearch by calling 'make uninstall'.
To start DiskSearch after installation just enter the 'disksearch' command.

The name of the Python interpreter executable can differ on some systems.
If you have problems to start DiskSearch you probably need to edit the 
Python reference in the file 'disksearch'.


Installation on Win32 systems
-----------------------------

First you need to install Win32 version of Python, GTK+ and PyGTK. 
You can download the installers from these locations:

- Python for Win32:         http://www.python.org
- GTK+ runtime for Win32:   http://gladewin32.sourceforge.net
- PyGTK for Win32:          http://www.pcpm.ucl.ac.be/~gustin/win32_ports

Please don't use space characters in the installation directories. I've 
tested DiskSearch with Python 2.3.4, GTK+ 2.4.11 and PyGTK 2.4.0 on Windows
2000 and XP without any problems.

Then extract the DiskSearch archive and you can start it with run-win32.bat.
But it's more comfortable to create a shortcut on the desktop or in your start 
menu.


Usage
-----

At the first usage of DiskSearch the user should add all the disks he wants to
be able to search at to the archive. 
This is done by the 'Add disk' command. In the dialog the user needs to enter
the mount point of the disk (usually '/media/cdrom' on Unix-based or e.g.
'D:\' on Win32 based systems). Then the user needs to select a disk type 
and enter an unique name. It's also possible to add an comment (e.g. where 
the disk is located). On Unix-based system the user can check the 'mount and
unmount' option, so the disk will be mounted and unmounted automatically.

All the added disks will be displayed in the disk list table of the main 
window, which can be sorted by each column. The 'Edit disk' command (or 
double-click) shows the content of the selected disk in a dialog. The user can
also change the disk name, the type and the comment there. 
The command 'Remove disk' deletes the selected disk from the archive.
The user will be asked to save the changes of the disk list at application 
exit.

The command 'Search for files' starts the dialog where the user can search for
files or directories on all disks of his archive. It's possible to perform a
normal search (which can optionally be case sensitive) or to use regular 
expressions (always case sensitive) for the search.
When files for the search string has been found, then the user can easy locate 
the appropriate disks by the displayed disk name in the result list.

DiskSearch is able to prepare XML files for printing of the content of the
selected disk (suitable for CD cover). The user then prints the content from
the web browser if the browser supports XSL tranformation (MS IExplorer, 
Gecko based browsers, Opera, ... do so).
The generated HTML page also includes layout editor where user can change
layout od the printed page (size, colors, labels).
The command 'Print the selected Disk' starts the dialog where the user selects
format of the output and browser to display with. Then the browser is opened
with the file. It has linked an XSL template. The XML file is created in 
system temporary directory and should be deleted during next boot. 
Printing from the browser was tested in the following browsers:
IExplorer 6 and 7 (WinXP), Firefox 2.0 and 1.5 (Linux and WinXP), and Opera 9.21
(Linux and WinXP).


Command line options
--------------------

Usage: disksearch.py [-a file] [-V] [-h]
-a, --archive file    use specified archive file
-V, --version         show program version
-h, --help            show this usage information


Archive format
--------------

All the informations of the archived disks are stored in the hidden text file
'.disksearchdb' in users home directory. Each line is one entry, the first
character defines the content of the line. These are the possible characters:

  C - start of a new disk
  T - type of disk, e.g. 'DVD' (optional, disk type will be 'CD' then)
  R - remark (comment) of the user to the disk (optional)
  A - timestamp (python format) when the disk has been added (optional)
  D - start of a new directory in the current disk (full qualified pathname)
  F - a file in the current directory (only the filename in this directory)
  S - the size of the current file in bytes (optional)

Example:

  CArchive 20021108
  TCD
  RLinux archives only.
  A1094266571
  D/linux/canon-s30
  Fcanon-s30-config.zip
  S12688
  Fgphoto2_2.1.1-cvs-1_i386.deb
  S1645231
  D/linux/csharp
  Fgtk-sharp-0.5.tar.gz
  S653864
  CArchive 20021209
  ...


Unit testing
------------

DiskSearch contains a set of untit tests for all relevant application
parts. These are located in the directory 'unittests'. All test can be
started by the command 'python unittests/allTests.py' in the project 
root directory.


Contact
-------

You can use the forum and the bug system on the Sourceforge project page 
(http://sourceforge.net/projects/disksearch) when you have comments,
suggestions or problems with bugs.
The most recent version of this tool can also be found there. If you're 
interested in the current development version you can get it from CVS.

For direct email contact you can use the address: projects@saring.de 


License
-------

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.


Authors
-------

Developers:
    Stefan Saring <projects@saring.de>
    Mathias Obst <luettfite@users.sourceforge.net>
    Tomas Penicka <tom dot penicka at centrum dot cz>

Translators:
    German : Mathias Obst <luettfite@users.sourceforge.net>
    Italian: Davide Milazzo and Flavia Guadagnino <sum90@libero.it>
    French : Starcrasher <starcrasher1@free.fr>
    Polish : Wojciech Myrda <vojcek@tlen.pl>
    Spanish: Marcelo Fernández <fernandezm22@yahoo.com.ar>


Stefan Saring
2007/08/28