README for Spit
===============

Table of Contents
-----------------
1. Introduction
2. Obtaining Spit
3. Installation
4. Usage
5. Creating your own templates
6. Converting from older versions of Spit
7. Questions
8. Bugs



1. Introduction
---------------
Spit is a graphical picture indexing tool. It can be used to manage pictures,
and generate HTML pages for putting your pictures online. It is designed for
user-friendliness, portability and extensibility. It allows quick & easy 
ordering, editing and adding captions for pictures.

Spit generates thumb & slide images automatically, and feeds them to the 
HTML generator. Spit uses XSLT (http://www.w3.org/TR/xslt) stylesheets to 
transform the album into HTML pages. This means you can easily customize
Spit to generate your own HTML code: just create (or modify) an XSLT 
stylesheet.
The default template, speek.xsl, generates HTML code using CSS. This means
that the colors can also be modified easily by creating your own custom CSS.

Spit uses Qt3, a cross platform library for creating user interfaces. It 
has been compiled and ran succesfully under GNU/Linux (and other Unix 
systems), MacOS and Microsoft Windows.
 

2. Obtaining Spit
-----------------
Spit can be obtained from http://spit.sourceforge.net
You can get further instructions there.


3. Installation
---------------
See INSTALL file for more details.


4. Usage
--------
- Creating a new index:
  Start spit, click on the 'New' icon (or File->New menu), create a clean 
  directory for your index, and choose a filename for the index. Choose
  your preferred settings for the index (the defaults should be ok).
  You should now be able to edit the title & the date for your index, and
  import pictures using the 'Import' function. You can add captions for the
  pictures by clicking under the picture, and change the order by using the
  navigation buttons on top. Once you are satisfied with the captions and
  order, press the 'Save' button. You can generate the HTML pages for your
  index by pressing the HTML button.
  Be aware that the original pictures will (at the moment) always be in your
  dir. This means that, when you unchecked the option 'Include originals in
  HTML', you better upload only the HTML code, slides and thumbs dir to save
  some space. Do not remove the originals dir from the index dir, or else 
  things might go horribly wrong.

- Opening an index:
  You can start spit, and click on the 'Open' button, or you can start spit
  from command line with the file as a parameter.

- Using a different language:
  If you want to use a different language than for spit, you first have to
  download the language module from http://spit.sourceforge.net
  Put the .qm file in the i18n subdir of your datadir (e.g., under Linux
  in /usr/share/spit/i18n).
  Then, set the LANG variable to the appropriate language, and then run spit. 
  For example, if you downloaded and installed spit_nl.qm, running
        LANG=nl spit
  will start the Dutch version of spit. 
   

5. Creating your own templates
------------------------------
Creating your own templates is easy: just copy the default template to
have a template for your template, and just make your own template out of
that template. 
To test your template while making it, i suggest using an XSLT processor such 
as 'xsltproc' on your template and an index file. The processor will create
the HTML files, which you can evaluate afterwards.


6. Converting from older versions of Spit
-----------------------------------------
At the moment, support for older formats of Spit is not built-in. However,
the 'extra' dir contains an XSLT stylesheet for converting older .ind files
to the newest format. So, you can use an XSLT processor such as 'xsltproc'
for the conversion as follows:
    xsltproc /path/to/extra/convert-0_2-0_3.xsl oldindex.ind > newindex.ind
Future versions of spit will have conversion support built-in.


7. Questions
------------
- Q: What does Spit stand for ?
  A: The name is as modular as the design ;-) These are some possibilities of
     what it might stand for:
        * the | Spit     | Picture Indexing Tool
              | Sexy     |
              | Super    |
              | Sweet    |
              | Shibby   |
              | Snazzy   |
              | Swanky   |
              | Stupid   |
              | Splendid |
        * Spike's Picture Indexing Tool
        * ...


8. Bugs
-------
There are several known bugs for this version, which can be found in the
BUGS file. If you find any more bugs, please report them to me.
Feature requests are also always welcome !


Author
------
Remko Tronon <spike@kotnet.org>
Jabber ID: remko@amessage.be
URL: http://spike.studentenweb.org/
