XML Photo Galleries, version 1.5
Copyright 2002, 2003, Garrett A. Wollman.  All rights reserved.
(See the individual source files for terms and conditions of distribution.)

INTRODUCTION
============
Over the several years, I've been looking to restructure a lot of the
content on my Web site to be automatically generated from a database,
using an XML document to store the database and XSL transformations to
generate HTML for viewing.  While the top-level project has not made
much progress, I had other incentive to get this piece of it, the
photo galleries, onto a firmer footing.  (Mostly, I was accumulating
digital photos at an alarming rate and never got around to marking
them up by hand.)

There are certainly a number of other programs that can probably do a
better job of it than this one.  I wanted to write my own, because I'm
that sort of person, and also because I wanted to improve my comfort
level in writing XSLT (which is not exactly simple to write and
debug).


PREREQUISITES
=============
I use `xsltproc', the XSLT processor which comes with the GNOME
project's `libxslt'.  I don't have any religious attachment to this
particular processor; I don't actually use GNOME myself or have it
installed on my system -- this just happened to be a convenient
choice.  The scripts have some amount of built-in flexibility as to
the processor used, but unless your processor accepts exactly the same
command-line arguments as `xsltproc' it's not likely to work in
practice.  (I would welcome patches to add support for other
processors.)

You'll also need a working Perl installation with the XML::Writer
module, and a reasonable `make' program.  Some reasonable ability at
writing XML is a must, as is a decent text editor.

Generally speaking, you'll need a reasonably modern operating system.
I don't particularly feel like wasting my time adding all sorts of
kluges and hacks to work around broken operating systems that are
missing this program or that feature; get a real operating system (tm)
if you have problems of that sort.  Legitimate bug reports are
welcome.


HOW IT WORKS
============
This photo-gallery generator is designed around the way I personally
process my digital photos for Web access.  I have a Perl script which
reads images off of the flash device, displays each one, and asks me
three questions:

	- Should it be rotated 90 degrees for presentation (i.e.,
	  portrait or landscape)?

	- Should the color distribution be normalized?

	- What is this a photo of?

It then processes the photos to create the requested sizes (thumbnail,
small, medium, large, and ``original'' -- i.e., unprocessed).  Since
my digital camera normally creates images in JPEG format, it is
important for image quality to avoid re-encoding as much as possible,
so I always keep the originals around in case I need them for other
purposes.  The titles are saved in a file called index.xml in the
target directory.  This script is included in the distribution and is
called `copyphotos'; in addition to the main package's prerequisites,
it requires John Bradley's XV image viewer, ImageMagick, and the Perl
modules Image::Info, Image::Magick, File::Slurp, and a
specially-modified version of XML::Writer.  (XV is used to display
images rather than ImageMagick's `display' utility because it is
faster and more convenient for batch display.)  The script makes
certain fundamental assumptions about the format of images and the way
I like to deal with them; it may not be right for you and I make no
promises about its suitability for anyone else.

An important feature of my system is that all photos are named
according to a simple naming scheme:

	${index_number}-${size}.${format}

Associated with displayable sizes of each photo is an HTML document
with the photo inline, followed by more information about the subject
of the photo.  (Viewers can click on the photo to get the next larger
size, if available.)  The HTML file is named according to the same
scheme as the photos themselves.  So, if I have a photo numbered
`100-00001' and it's in JPEG format, I will have the following files
around in the gallery directory:

	100-00001-th.jpg
	100-00001-sm.jpg
	100-00001-sm.html
	100-00001-med.jpg
	100-00001-med.html
	100-00001-lrg.jpg
	100-00001-lrg.html
	100-00001-orig.jpg

There's no need for the ``photo number'' to actually be a number;
that's what I use, and that's why that attribute in the XML is called
`number', but the style sheets will never attempt to use it as
anything other than an identifying string.

At the highest level, you use this package by creating an index of
images in the gallery, using the XML DTD provided.  The index contains
all of the information about what sizes are available, and each
photo's long and short titles, description, cross-references, and
copyright information.  You then run the `pgmkmf' script, which
invokes the XSLT processor to create a Makefile in the same directory,
and finally run `make' to generate all of the individual image
description pages and the main index page.  (Once the Makefile has
been created, it knows how to keep itself up-to-date with respect to
the index file.)  See the `index-sample.xml' file in this distribution
for an example.

It is possible to mark specific photos as ``not shown'', which
indicates that they will be excluded from the index pages and skipped
over by the navigation links on the adjacent photo pages.  You can
also mark particular sizes in the same way, both as a group and at the
individual photo level -- although the latter can cause navigational
confusion, so use it with caution!  It also doesn't make much sense to
mark thumbnails as ``not shown'' since they are rather fundamental to
the purpose of this program!

The main index page is generated by extracting the main title and
description from the database, followed by a table with four captioned
thumbnail images in each row.  After the thumbnails is a copyright
notice crediting all of the thumbnails' copyright holders (in document
order with duplicates suppressed).

If you have a directory hierarchy containing many distinct photo
galleries, as I do, you can use the included `pgindextree' script to
create a master index listing all of the individual galleries.
Specify `-o outfile.html' on the command line to change the name of
the file generated (default `pg-index.html'), then specify any
directories you want to have scanned.  (The script supports some other
options; see the usage message for details.)

$Id: README,v 1.7 2006/04/30 19:33:54 wollman Exp $
