Lyle
====
1. Introduction
1.1 What is it?
Lyle is a CGI program for display collections of images (typically
photographs). It will be renamed at some point, as there is already
another program with the same name and similar functionality.
1.2 Requirements
It requires:
* Perl (tested with 5.8.8)
* jpegtran (e.g. from Debian package libjpeg-progs).
* the Image::Magick perl interface (e.g. Debian package perlmagick).
Lyle is designed to run as the user that owns the pictures and not as
the web server's userid. Use something like suexec or ucgi to achieve
this.
1.3 Upgrading
Version 0.4 has a new templating system; you must install the new
template files somewhere sensible, edit them according to taste, and
configure Lyle to find them. See below for more details.
Version 0.7 changs a lot of names around! See CHANGES.html for details.
2. How to use it
Put your images in directories, grouped however you like.
Currently JPEGs and PNGs are supported and must have the file
extension .jpeg, .jpg or .png. (Upper case is allowed.)
Write a lyle.conf file. This should be available as ~/.lyle.conf
for the user that the script runs as (but it might be a symlink).
It's a fragment of Perl and should define at least the following
variables:
* $rootdir. This is the common parent of all the directories you have
images in.
$rootdir = "/home/whatever/public_html/photos";
* $rooturl. This is the URL equivalent of $rootdir.
$rooturl = "http://www.example.com/photos";
* $cachedir. A directory to use for cache data.
$cachedir = "/home/whatever/public_html/gc";
* $cacheurl. The URL equivalent of $cachedir.
$cacheurl = "http://www.example.com/photos/gc";
* $lyleurl. The URL that lyle is available under. If it ends in
a / then generated URLs will contain the images directory as part
of the path rather than as a parameter.
$lyleurl = "http://www.example.com/~user/lyle.cgi";
* $imagesurl. The base URL for image files. There should be at
least the following available:
$imagesurl/left.png
$imagesurl/right.png
$imagesurl/up.png
$imagesurl/data.png
$imagesurl = "http://www.example.com/~user/lyle-images";
Suitable sample images are included in the Lyle distribution in the
'images' directory.
* $maxthumbwidth and $maxthumbheight. These define the maximum size
in each dimension for thumbnails. The thumbnail will be generated
by shrinking the image to the largest size that fits these limits
and maintains aspect ration.
Optional, defaults are 128x96.
$maxthumbheight = 128;
* $maxdisplaywidth and $maxdisplayheight. These define the maximum
size in each dimension for displayed images. The displayed image
will be generated by shrinking the image to the largest size that
fits these limits and maintains aspect ration.
Optional, defaults are 640x512.
$maxdisplayheight = 480;
* $jpegquality. This is an integer between 0 and 100 and is passed
to ImageMagick to determine the JPEG quality used when rescaling
images. 0 is the worst and 100 the best. Higher quality values
take more disk space.
Note that this option cannot improve the appearance of an image
already compressed at low quality!
Optional, default is determined by ImageMagick and is 75.
$jpegquality = 95;
* @dirs. A list of directories, relative to $rootdir, that contain
pictures.
@dirs = (
"photos/summer2002",
"photos/xmas2002",
);
* @autodirs. A list of directories, relative to $rootdir, that
contain directories containing pictures. For each directory in
@autodirs, all its subdirectories are examined and if they contain
an info.pl file they are automatically added to @dirs.
@autodirs = (
"photos",
);
This can be used to save updating @dirs every time you added a
directory.
At least one of @dirs and @autodirs must be nonempty.
* $lock. Path to a writable file that can be used to guard against
concurrent access. Optional, defaults to ~/.lyle.lock. You can
undef this if you don't want locking.
Locking is not mandatory but if you don't use locking then nothing
stops someone making hundreds of copies of the CPU-heavy image
conversion code run simultaneously on your system!
* $index. The URL to use for the link back up to the index of all
galleries. Optional, default not set.
* @templates. This should be a list of one or more directories
containing template files. They will be search in order; the first
match wins. You should install the *.tmpl files from the source
distribution into one of these directories, and edit them (or
install your own versions earlier in the path) according to taste.
(See below for more about templates.)
End with "1;" on a line by itself.
URLs can be relative, but it's usually easier to get it right by using
absolute URLs. Filenames should all be absolute.
In each directory that contains images, write a info.pl file (perhaps
using lyle-refresh to initialize it - see below). This should define
the following variables:
* $title. The title for the directory.
$title = "Photos from Summer 2002";
* $description. A longer description.
$description = "Pictures I took on my holiday.";
* %caption. A hash mapping picture filenames to captions.
%caption = (
"1.jpeg" => "My friend Bob",
"2.jpeg" => "The beach",
);
* %comments. A hash mapping picture filenames to more detailed
descriptions.
%comments = (
"2.jpeg" => "<p>Lots of shells on this beach.</p>",
);
* %rotate. A hash mapping picture filenames to rotation angles in
degrees. Only put images that need rotating for display here.
Must be multiples of 90 degrees.
Positive angles rotate clockwise, while negative angles
rotate anticlockwise.
%rotate = (
"1.jpeg" => 90 # portrait orientation
);
End with "1;" on a line by itself.
3. Templates
The suggested way of using templates is to install the standard
templates into one directory and create a separate directory for any
overrides you wish to write yourself. The @templates variable should
list the directory containing the standard templates last.
The standard template files are can be found in the Lyle distribution
in the 'templates' directory. They are:
* index.tmpl. This is used for the thumbnail page.
* picture.tmpl. This is used for each picture's individual page.
* error.tmpl. This is used for errors.
* stdhead.tmpl. This is included in the <head> element of all the
standard templates. The default just includes stylesheet.tmpl.
* stylesheet.tmpl. This provides a simple default inline
stylesheet. You can either edit it or replace it with a <LINK> to
reference another stylesheet.
* footer.tmpl. This is included just before the </body> tag of all
the standard templates.
In a template file you can use the following expansions:
@navigation@ The navigation links for this page.
@thumbnails@ The full set of thumbnail links.
@images@ The image link (only for picture.tmpl).
@title@ The title for index.tmpl or picture.tmpl
@description@ The detailed description for index.tmpl
@comment@ The comment for picture.tmpl.
@error@ The brief error message for error.tmpl
@detail@ A more detailed error message for error.tmpl
@generated@ An SGML comment with a timestamp.
@include:PATH@ Include a file. It is searched for in the same way
as other template files.
In @thumbnails@ each thumbnail is preceded by an anchor named for the
picture, and each thumbnail links to that anchor. This can be used to
add a scrollable column of thumbnails to the the picture template with
apparently persistent state.
See css.txt for more details about this.
4. lyle-refresh
This is a simple Perl script that generates info.pl files. You run it
in the directory containing the images and it will write a skeleton
info.pl file for you.
If there is already an info.pl there then it will preserve $title,
$description, %caption and %rotate.
If images are removed and have a nontrivial caption then the caption
is preserved (but a warning is displayed). So if the image returns
under the same name then it will get its old caption back.
5. Troubleshooting
If things go wrong:
* Check that all the variables described above are set correctly.
* Filesystem paths should be absolute, i.e. start with a "/".
* The image and configuration files must be readable by whatever
user the script runs as.
* The cache directory must be writable by whatever user the script
runs as.
* If you have a lockfile it must be writable by whatever user the
script runs as. (If it does not exist the first time it runs
then it will try to create it, in which case the directory it is
in must be writable by the right user.)
6. Wishlist
See:
http://www.chiark.greenend.org.uk/ucgi/~dans/chiarkwiki?GalleryWishlist
7. Mailing Lists
New versions will be announced on sgo-software-announce, which you can
subscribe to via
<http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-announce>.
Discuss this software on sgo-software-discuss, which you can subscribe
to via
<http://www.chiark.greenend.org.uk/mailman/listinfo/sgo-software-discuss>.
8. Copyright
"Lyle" is Copyright (C) 2003, 2004, 2005, 2008 Richard Kettlewell
Copyright (C) 2004 Ross Younger
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA
------------------------------------------------------------------------
Local Variables:
mode:text
End: