dTk - README
============
last modified by JaWi on 20/02/02

CONTENTS
--------
1.  Introduction
2.  Purpose
3.  Installation
4.  Usage
5.  Contact
6.  References


1. INTRODUCTION
---------------
You are reading the main readme file. This file will handle several 
general topics on the purpose, installation and usage of dTk. This 
document is yet far from being complete and may be subject of massive re-
work in the following releases of dTk.


2. PURPOSE
----------
dTk was written with the intention of easing the access to remote SMB
hosts on ``campusnet'' from Linux. Although you can access each host with
the ``smbclient'' program provided with each Samba[1] installation, this
is text-based only. Added that some directories are having very creative
names with lots of punctuation characters, entering such a directory can
be a pain. With the help of the widely known search engine ``Dance''[2],
dTk helps you to download your favorite music, programs or whatever!


3. INSTALLATION
---------------
The installation of dTk is quite easy: just copy both the `dtk' and
'smbbrowser' script to a well-known location. If you haven't got a clue
where this might be, try one of the following directories:

  *   the current directory (if you launched dTk from an xterm),
  *   the `bin' directory in your $HOME,
  *   the /usr/bin directory, or,
  *   the /usr/local/bin directory.

Make sure you've got read/write access to the place of installation and
that both scripts are marked executable. If you need a clue: 
``chmod 755 dtk smbbrowser'' should do the trick.
You can verify the installation by simply starting dtk (see section 4),
if the main script can't find the other, it croaks with a message and
stops.


4. USAGE
--------
To start dTk, simply enter the command `dtk' in an xterm, or create a
suitable short-cut (depending on your window manager).
You will now be presented with the main window of dTk: the search window.
This window is divided into three parts (from top to bottom):

  1.  A menubar, with all (familiar?) menu items.
  2.  A search entry field.
  3.  The result box.

All search queries must be entered in the search entry field. A search
will be performed either by pressing <enter> right after your query, or
by clicking the ``search''-button at the end of the entry field.
The results of your query are presented in the result box. The usage of
these results has much resemblance with the dance website[2]. Moving your
mouse over a result will highlight it and a simple click is enough to 
move to the next part of dTk: the share browser.

4.1. SHARE BROWSER
------------------
After you selected a result of your query, a new window is presented: the
share browser. This is more or less a graphical front-end to `smbclient',
with one major advance: you can browse on different shares on the remote 
host without re-issueing a query!
The share browser is divided (again) into three different parts:

  1.  At the top, several ``action''-buttons are presented.
  2.  At the left, you'll see the share-tree: with this tree you can
      browse the shares and their directories.
  3.  At the right, the directory contents are presented.

You can navigate through the shares by selecting directories in the 
share-tree. The contents will automagically appear in the file list. This
brings us to the subject downloading.

4.2. DOWNLOADING
----------------
dTk can grab both loose files as well complete directories. To download a
complete directory, simply select it and press the ``Copy multi'' button
at the top of the window. You can see the progress of the download at the
bottom of the window in the status bar.
If you want to download just one or several loose files, simply select
them by holding <shift> while selecting them one by one. Again to start
the download, press the ``Copy multi'' button.


5. CONTACT
----------
If you feel you are missing stuff in dTk, feel free to contact the author
about this! Also bug reports are more than welcome. If you submit a bug,
_please_ give me at least the following items:

  *  The version of dTk you're using,
  *  The output of dTk stating the problem,
  *  Either the query you were searching on, or the host/ip of 
     the connection to remote host.

The author can be reached at: janwillem.janssen@lxtreme.nl (see also the
AUTHOR file).


6. REFERENCES
-------------
[1] http://www.samba.org, or http://samba.nip.nl/samba/samba.html
[2] http://dance.student.utwente.nl