README

   1 ================================================================================
   2
   3                                UCW::Gallery v2.0
   4
   5                     (c) 2004--2015 Martin Mares <mj@ucw.cz>
   6
   7 ================================================================================
   8
   9 This is a simple photo gallery for my web pages, or rather a set of bricks
  10 from which you can create one. It can be freely used and distributed according
  11 to the terms of the GNU GPL v2 or newer.
  12
  13 Requirements
  14 ~~~~~~~~~~~~
  15 Perl with the following non-core modules:
  16
  17    o  UCW::CGI (see http://www.ucw.cz/libucw/)
  18    o  Image::Magick
  19    o  Image::Exif
  20    o  Archive::Zip
  21    o  Digest::SHA
  22
  23 Files and directories
  24 ~~~~~~~~~~~~~~~~~~~~~
  25
  26    o  gal -- a front-end script for maintenance of galleries. All other programs
  27       are run as sub-commands of this script. Try "gal --help".
  28
  29    o  gallery.cf -- all programs expect that the current directory contains
  30       a configuration file. In fact, the config file is a perl script, whose
  31       sole purpose is to set up paths, construct a gallery object and set its
  32       options.
  33
  34       A simple example looks as follows:
  35
  36                 use UCW::Gallery;
  37
  38                 my $gal = UCW::Gallery->new;
  39                 $gal->set(Title => 'A Gallery', SubTitle => '(an example)');
  40                 return $gal;
  41
  42    o  gallery.list -- a list of original photos together with per-photo parameters.
  43       Usually created by "gal scan", then tweaked manually. See `FORMATS' for
  44       description of file syntax.
  45
  46    o  gallery.cache -- used internally by "gal scan" to store cached image hashes.
  47
  48    o  Originals directory -- original images, from which the gallery is generated.
  49
  50    o  Photo directory -- keeps processed (usually down-scaled) versions of the original
  51       images. These are the images shown to the user.
  52
  53    o  Cache directory -- keeps various cached data, like thumbnails of all photos.
  54
  55    o  gallery.cgi -- interfaces the gallery to your web server. E.g.:
  56
  57                 #!/usr/bin/perl
  58
  59                 use lib "../path/to/gallery/modules";
  60                 use UCW::Gallery;
  61                 use UCW::Gallery::Web::Plain;
  62
  63                 my $gal = UCW::Gallery->load_config();
  64                 UCW::Gallery::Web::Plain->run($gal);
  65
  66 Workflow
  67 ~~~~~~~~
  68
  69    o  vi gallery.cf
  70
  71    o  gal scan /path/to/originals -- this creates gallery.list, populates it with
  72       descriptions of all photos and reads rotation from EXIF tags.
  73
  74    o  vi gallery.list -- edit image descriptions and other options.
  75
  76    o  gal gen -- generate photos from the originals (after this, the originals are no
  77       longer needed).
  78
  79    o  gal cache -- generate cached data.
  80
  81    o  Later, the gallery can be updated:
  82
  83         - When you edit image descriptions, re-run "gal cache".
  84         - When you edit image options (rotation etc.), re-run "gal gen".
  85         - When you want to add new images, re-run "gal scan". Give it the new list
  86           of images and it will try to re-use as much information from the previous
  87           gallery.list as possible.
  88         - When you modify existing images, run "gal scan --update".
  89
  90    o  See example/* for an example web front-end.