README

   1 ================================================================================
   2
   3                                UCW::Gallery v2.1
   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.
  11
  12 License
  13 ~~~~~~~
  14 UCW::Gallery and the accompanying scripts can be freely used and distributed
  15 according to the terms of the GNU GPL v2 or newer.
  16
  17 The images in nrt-blue/, used by the NrtBlue theme, are derived from images
  18 in an ancient version of the cthumb package, which is (c) Carlos Puchol
  19 and which can be distributed under GNU GPL v2. See http://cthumb.sourceforge.net/
  20 for the current version of cthumb.
  21
  22 The JavaScript files and related data in highslide/, used by the HighSlide theme,
  23 come from the Highslide JS media viewer, which is (c) Highsoft AS. It can be
  24 freely used on personal and non-profit websites. For commercial or government
  25 use, a paid license is required. See http://www.highslide.com/ for details.
  26
  27 Requirements
  28 ~~~~~~~~~~~~
  29 Perl with the following non-core modules:
  30
  31    o  UCW::CGI (see http://www.ucw.cz/libucw/)
  32    o  Image::Magick
  33    o  Image::Exif
  34    o  Archive::Zip
  35    o  Digest::SHA
  36    o  common::sense
  37
  38 Files and directories
  39 ~~~~~~~~~~~~~~~~~~~~~
  40
  41    o  gal -- a front-end script for maintenance of galleries. All other programs
  42       are run as sub-commands of this script. Try "gal --help".
  43
  44    o  gallery.cf -- all programs expect that the current directory contains
  45       a configuration file. In fact, the config file is a perl script, whose
  46       sole purpose is to set up paths, construct a gallery object and set its
  47       options.
  48
  49       A simple example looks as follows:
  50
  51                 use UCW::Gallery;
  52
  53                 my $gal = UCW::Gallery->new;
  54                 $gal->set(Title => 'A Gallery', SubTitle => '(an example)');
  55                 return $gal;
  56
  57    o  gallery.list -- a list of original photos together with per-photo parameters.
  58       Usually created by "gal scan", then tweaked manually. See `FORMATS' for
  59       description of file syntax.
  60
  61    o  gallery.cache -- used internally by "gal scan" to store cached image hashes.
  62
  63    o  Originals directory -- original images, from which the gallery is generated.
  64
  65    o  Photo directory -- keeps processed (usually down-scaled) versions of the original
  66       images. These are the images shown to the user.
  67
  68    o  Cache directory -- keeps various cached data, like thumbnails of all photos.
  69
  70    o  gallery.cgi -- interfaces the gallery to your web server. E.g.:
  71
  72                 #!/usr/bin/perl
  73
  74                 use lib "../path/to/gallery/modules";
  75                 use UCW::Gallery;
  76                 use UCW::Gallery::Web::Plain;
  77
  78                 my $gal = UCW::Gallery->load_config();
  79                 UCW::Gallery::Web::Plain->run($gal);
  80
  81 Workflow
  82 ~~~~~~~~
  83
  84    o  vi gallery.cf
  85
  86    o  gal scan /path/to/originals -- this creates gallery.list, populates it with
  87       descriptions of all photos and reads rotation from EXIF tags.
  88
  89    o  vi gallery.list -- edit image descriptions and other options.
  90
  91    o  gal gen -- generate photos from the originals (after this, the originals are no
  92       longer needed).
  93
  94    o  gal cache -- generate cached data.
  95
  96    o  Later, the gallery can be updated:
  97
  98         - When you edit image descriptions, re-run "gal cache".
  99         - When you edit image options (rotation etc.), re-run "gal gen".
 100         - When you want to add new images, re-run "gal scan". Give it the new list
 101           of images and it will try to re-use as much information from the previous
 102           gallery.list as possible.
 103         - When you modify existing images, run "gal scan --update".
 104
 105    o  See example/* for an example web front-end.
 106
 107 Various notes
 108 ~~~~~~~~~~~~~
 109
 110    o  When you want to re-generate all galleries at once, you can use
 111       "gal --all -p4 gen". This will run "gal gen" on all subdirectories
 112       containing "gallery.cf", 4 of them in parallel.
 113
 114    o  See bin/gal-mj-* for various hacks I wrote for myself.