picturepages ============ picturepages is today's slide projector; it lets you bore your friends with your vacation photos from across the country instead of having to invite them to your house. You give it a directory full of big images and a text file describing the images; it generates web pages with smaller images, linking to the larger images, and captions. picturepages is licensed to you under the terms of the GNU General Public License, Version 2, which is in the file called "COPYING" in this directory. picturepages was written by Kragen Sitaker . This is picturepages version 1. features -------- - puts your images on the Web - thumbnail index page - image pages with images scaled down to fit the screen - image pages link to full-size images - image pages have captions - image pages have prev and next links - image pages have links to specialized index pages listing only images containing similar things (unfortunately you have to tell picturepages what an image contains; it isn't smart enough to figure that out on its own) - automatic JavaScript-driven slideshow from index pages prerequisites ------------- Obviously you need a web server. Less obviously, you need to be able to run CGI scripts on it. To generate the web directory, picturepages uses a bunch of tools, all of which should be installed on any modern Unix system: mkdir that understands -p, cp, chmod, Perl, and the mogrify program from ImageMagick. These all need to be in PATH. The web directory, once generated, contains an index.cgi that needs to run as CGI and needs Perl and CGI.pm. It also uses a Perl module from the same directory; this can cause problems with mod_perl and on web servers that don't change their current directory to the CGI script's directory when running CGI scripts. (I think IIS falls in this category.) Your web server should be configured to serve up index.cgi as the index page for the directory, although it doesn't really need to be. usage ----- To use picturepages, you first need to write a description file, as described below under the "description file" heading. Then you need to run ./mkpp descriptionfilename outdir where "descriptionfilename" means the name of the description file and "outdir" means the name of the directory where you want it to put its output. mkpp normally only copies and resizes the images to outdir if they aren't already there, because recreating the images is slow; this means that if you modify an image, you need to delete all three versions of that image by hand in outdir, run mkpp with a new outdir (and rename it), or blow away outdir before running mkpp. mkpp expects to find slideshow.html, blank.html, and ImageDirCGI.pm in the current directory when you run it, and it copies it to outdir. Practically this means you should probably copy or symlink all of picturepages into the directory with your input images in it. mkpp also copies ".htaccess" from the current directory to outdir if it exists. description file ---------------- The description file consists of stanzas separated by blank lines, each stanza corresponding to an image; each stanza consists of some name-value pairs, consisting of a name, a colon, possible whitespace, and some text. The text can continue onto the next line if it's indented. There are four names with defined meanings, all of which are more or less mandatory: 'file', 'title', 'caption', and 'contains'. They need to be lower-case. I'm sorry, I know that's stupid, but I don't care enough to fix it. Here's an example stanza. file: feet.jpeg title: The water past the feet caption: Robert's (?) feet are crossed, but they don't obstruct the view of the gorgeous water, rock, and pine trees. contains: water, rock, pine trees, sky This says that this stanza is about an image file called 'feet.jpeg', that its web page should be titled 'The water past the feet', that its caption should be "Robert's ... trees.", and that it contains four items called "water", "rock", "pine trees", and "sky", which appear as four links in the output HTML, linking to four index pages listing other images the description file claims contain "water", "rock", "pine trees", and "sky". title and caption can have arbitrary HTML tags in them. Be careful to close any tags you open. contains and file probably could, but they'd almost inevitably cause problems. So don't put HTML tags there. Name your files and items sensible things that don't include less-than '<' and ampersand '&' symbols. The description file format is fairly rigid. Don't have blank lines at the beginning of the file; separate adjacent stanzas with a single blank line. You won't get error messages if you run stanzas together; you'll just get missing images. You won't get error messages if you misspell things like 'caption' or 'sky'; you'll just get broken output.