Gallery2: README

diff --git a/gal/README b/gal/README
new file mode 100644 (file)
index 0000000..9c0d350
--- /dev/null
+++ b/gal/README
@@ -0,0 +1,86 @@
+================================================================================
+
+                              UCW::Gallery v2.0
+
+                   (c) 2004--2012 Martin Mares <mj@ucw.cz>
+
+================================================================================
+
+This is a simple photo gallery for my web pages, or rather a set of bricks
+from which you can create one. It can be freely used and distributed according
+to the terms of the GNU GPL v2 or newer.
+
+Requirements
+~~~~~~~~~~~~
+Perl with the following non-core modules:
+
+   o  UCW::CGI (see http://www.ucw.cz/libucw/)
+   o  Image::Magick
+   o  Archive::Zip
+   o  Digest::SHA
+
+Files and directories
+~~~~~~~~~~~~~~~~~~~~~
+
+   o  gal -- a front-end script for maintenance of galleries. All other programs
+      are run as sub-commands of this script. Try "gal --help".
+
+   o  gallery.cf -- all programs expect that the current directory contains
+      a configuration file. In fact, the config file is a perl script, whose
+      sole purpose is to set up paths, construct a gallery object and set its
+      options. Also, it usually attaches an appropriate web front-end.
+
+      A simple example looks as follows:
+
+               use UCW::Gallery;
+               use UCW::Gallery::Web::Plain;
+
+               my $gal = UCW::Gallery->new;
+               UCW::Gallery::Web::Plain->attach($gal);
+
+               $gal->set(Title => 'A Gallery', SubTitle => '(an example)');
+               return $gal;
+
+   o  gallery.list -- a list of original photos together with per-photo parameters.
+      Usually created by "gal scan", then tweaked manually. See `FORMATS' for
+      description of file syntax.
+
+   o  Originals directory -- original images, from which the gallery is generated.
+
+   o  Photo directory -- keeps processed (usually down-scaled) versions of the original
+      images. These are the images shown to the user.
+
+   o  Cache directory -- keeps various cached data, like thumbnails of all photos.
+
+   o  gallery.cgi -- interfaces the gallery to your web server. E.g.:
+
+               #!/usr/bin/perl
+
+               use lib "../path/to/gallery/modules";
+               use UCW::Gallery;
+
+               my $gal = UCW::Gallery->load_config();
+               $gal->get('WebFe')->dispatch();
+
+Workflow
+~~~~~~~~
+
+   o  vi gallery.cf
+
+   o  gal scan /path/to/originals -- this creates gallery.list, populates it with
+      descriptions of all photos and reads rotation from EXIF tags.
+
+   o  vi gallery.list -- edit image descriptions and other options.
+
+   o  gal gen -- generate photos from the originals (after this, the originals are no
+      longer needed).
+
+   o  gal cache -- generate cached data.
+
+   o  Later, the gallery can be updated:
+
+       - When you edit image descriptions, re-run "gal cache".
+       - When you edit image options (rotation etc.), re-run "gal gen".
+       - When you want to add new images, re-run "gal scan". Give it the new list
+         of images and it will try to re-use as much information from the previous
+         gallery.list as possible.