makealbum2.pl -- An HTML photo album generator that sucks but is useful 
                 anyway

(See end of this file for a EFAQ)

I'm sharing this script, even though it's not really "release" quality, 
because it will come in handy for people who need to generate HTML photo 
albums quickly and without a lot of fuss.

makealbum2.pl is a simple perl script that takes a directory of images
and generates an HTML album from that images. I wrote it because I was
tired of overcomplicated scripts out there that did the same thing,
but had billions of dependancies.

You can always get the latest version at:

http://www.cs.fiu.edu/~flynnj/makealbum2.tar.gz

The only dependancies that makealbum2.pl has is that 
djpeg/cjpeg/pnmscale/pnmscale/pnmdepth/pnmtopng/pngtopnm/giftopnm be installed. 
These utilities come standard on most Linux distributions, so you 
shouldn't have any problems unless you're on a weird/old or non-Linux 
system. If you don't have them, here's where you can get them:

cjpeg/djpeg (comes with libjpeg): http://www.ijg.org/
pbm utilities (netpbm, basically): http://netpbm.sourceforge.net/

These utilities should be in your path before continuing.

makealbum2.pl is incredibly easy to use. Just run it inside a directory
full of JPG files, and it'll create HTML files called album1.html through 
albumn.html, each file containing part of the album. The album files
have links to go the next and previous pages in the album.

Each thumbnail image will be linked to a "smaller" version of the image.
"Smaller" here means smaller than the original size of the image, if
it is larger than the default "smaller" size. There are also links to
the full sized version of the image, as well as a "websized" link which
just points directly to the "smaller" image just discussed.

There are many options to this script which modify its behavior. Just
run the script with the -h option to get a list of all of them. Note
that thumbnails and smaller images are only created if they don't 
already exist; if you want to recreate them because the images have
changed or because you want to compress them differently, etc., delete
the thumbs and smaller directories before running the script again.

You can create captions for your images. Just create a file with the same 
name as the image, but with .txt on the end, and write your text in. I 
recommend a few lines at most.

If you want to put some HTML before a page in the album, there is a 
convenient way to do so. Just make a header-albumn.html where n is the 
page number. The HTML will be inserted at the top of the page.

Here's some of the options with more detailed descriptions:

-W: How many thumbnails across are on each album page. Self explanatory.
-H: How many rows of thumbnails are on each album page. Self explanatory.
-d: If there is no caption file for an image, use the image's modify date
    (MM/DD/YYYY) instead.
-n: Print the filename of the image over the image. Handy if the filenames
    are descriptive.
-D: Instead of sorting alphabetically by filename, sort by the file's 
    mtime date.
-r: Reverse sort the images in the album, regardless of the sorting method
    used. Note that image pages generated by the -p option will still be
    sorted in forward order.
-l: Check surrounding directories (one level down and up) for album1.html
    files, and create a row of links on the top of each album page linking
    to these other albums.
-p: Generate seperate HTML pages for each image. This lets you see the 
    image and its caption when you click on the image, as well as move 
    forward and back through the album as if it were a slide show.
-P: Insert a "pre-load" into each of the seperate HTML pages generated
    above. It basically <img src>'s the next and previous image as one pixel
    sized images on the page, so they are already in your cache when you
    click "next" or "previous". This makes browsing through an album much
    quicker, at the expense of wasting the bandwidth of people who just
    click single images from the thumbnails page.
-s: The image size in TOTAL PIXELS of the smaller versions of each image.
    For instance, if you want roughly 640x480 images, use 640 * 480 = 
    307200 for this number. This method is used so the aspect ratio of the
    image is preserved without making some of the smaller images odd 
    sizes.
-t: The image size in TOTAL PIXELS for the thumbnails. Same concept as -s.
-S: JPEG compression quality of the smaller versions of each image. An
    integer from 1-100, 1 is the worst, 100 is the best.
-T: JPEG compression quality of the thumbnails.

EFAQ (Expected Frequently Asked Questions):

Q: How do you pick the directory to process?

A: The script processes the current directory. Feel free to modify this 
   behavior if you see fit. I don't. }:)


Q: Why is this so sloppily coded? No subs or anything!

A: It was just a quick hack that grew larger and more advanced. I'm just 
   releasing it because some people might find it useful.


Q: makealbum2.pl? What happened to the first one?

A: The first one was a shell script called makealbum.sh that just created
   an HTML page full of thumbnails. No captions, text, just a ton of 
   thumbnails. I figured I could do better, though.


Q: Could you possibly be less original with the name?

A: Nah, this is about as unoriginal as you can get. }:)


Q: Does it handle gifs, pngs, etc.?

A: Yep, it also does GIF and PNG, thanks to modifications by
   J. L. Blank (jlb@twu.net)

Q: I get tons of noise from pnmscale when the images are being processed.
   What gives?

A: Upgrade to the latest version of the utils which are only spammy when
   asked to be. It personally doesn't bother me; I like seeing what's
   going on.


Q: Dude, why don't you add--

A: Why don't you add it? The nice thing about perl is that it's easy to 
   code in. If you want to add something, do so, and send me the new
   script or a diff. If your change rocks, I'll incorporate it into
   my version.


Q: What inspired this?

A: Over 400 pictures of my cat. No way to organize them. See for yourself:
    http://www.cs.fiu.edu/~flynnj/kittenpics/


Q: You're crazy!

A: That's not a question. But yes, I am!


Q: You're a freak. I'm outta here.

A: Later...

CHANGELOG:

7/11/2002 - 1.0

Initial release.

7/24/2002 - 1.01

Some braindead software out there uses the extension "*.jpe" for jpeg files.
I included that extension in the processed files. You really shouldn't use
that extension, though; other software packages may not be leniant about
it like I am.

7/25/2002 - 1.02

Added -f option for NOT making the "smaller" images. Handy when you have 
tons of images that are already a reasonable size for the web.

8/7/2004 - 1.03

Added -P option for the pre-load stuff.

8/7/2004 - 1.06PNG

Merged PNG and GIF support from J. L. Blank <jlb@twu.net> in, as well
as other minor cosmetic HTML generation changes.