README
1-------------------------------------------------
2swiggle - le's simple web image gallery generator
3-------------------------------------------------
4$Id: README,v 1.2 2003/01/10 19:27:42 le Exp $
5
6Homepage: <http://mailbox.univie.ac.at/~le/swiggle/>
7
8* About swiggle
9---------------
10swiggle is a small command line tool that generates HTML pages, including
11thumbnail indexes, for given images (a so called "web gallery"). It's
12intended to be easy to use, and since it is written in C, it's quite
13speedy. It uses libjpeg for decompression and compression of images,
14libexif for getting EXIF information contained in the images, and it
15caches scaled images so that subsequent runs don't need to scale images
16again and are faster. Of course, the original images aren't changed.
17
18Currently, it only processes JPEG images, and it's thought to be used
19primarily with images taken with digital cameras.
20
21swiggle was developed and runs on FreeBSD. It may run on other Un*x
22variants, too, but that wasn't tested yet.
23
24swiggle is Open Source software.
25
26
27* How to use it
28---------------
29As the name says it, swiggle is simple. It takes one argument on the
30command line: the 'main gallery' directory, which in turn contains
31subdirectories meant to be the 'albums'. It descends into every 'album
32directory' and processes every JPEG file in there. It creates
33thumbnails, scaled images and index pages for every album, and of course a
34gallery index in the 'main gallery' directory.
35
36There are several options that you can pass to swiggle to change the
37way swiggle generates images and HTML pages. Just run swiggle without
38any arguments to get the list of available options.
39
40
41* Example usage
42---------------
43Start with an empty directory, for example ~/gallery. Now create one
44or more subdirectories in ~/gallery and copy your desired images into
45each of the subdirectories. You might end up with a directory structure
46like this one:
47
48 ~/
49 |- gallery/
50 |- album1/
51 | |- IMG_001.JPG
52 | |- IMG_002.JPG
53 | |- IMG_003.JPG
54 | | ....
55 |- album2/
56 | |- IMG_011.JPG
57 | |- IMG_022.JPG
58 | |- IMG_033.JPG
59 | | ....
60 |- album3/
61 |- IMG_111.JPG
62 |- IMG_221.JPG
63 |- IMG_331.JPG
64 | ....
65
66Now just run "swiggle ~/gallery" and wait until it completes. That's
67all: copy over the whole ~/gallery directory to your webspace and
68enjoy :-). Don't delete ~/gallery if you intend to add or change
69images later: you need to re-run swiggle, and it will take less time if
70it can use the already created images and thumbnails.
71
72
73* Image descriptions
74--------------------
75By default, swiggle displays just the filenames or directory names on
76the HTML pages. If you want to give some or all images a specific
77description, just create a file called '.description' in the directory
78that contains the image. This file should contain one entry per line,
79the first word of each record is the image filename (without directory
80prefix) and the rest of the line is the desired description. An entry
81for the filename '.' is treated specially as the description for the
82current album.
83
