webshow

This page describes a Perl script I wrote for generating nicely formatted slide shows via HTML pages. It won't do all the work (you'll need an image manipulation utility too), but it will make it pretty darn easy once you have the photos sized properly.

You can grab the stuff you'll need here via this tar file. Unpack it in the top-level directory where you want your slideshow to reside.   [Windows users note: WinZIP can unpack it for you]   You'll also need to create a few directories, so the resultant top-level directory will contain:

	html            - Generated HTML pages will go here
	images          - Intermediate sized images go here
	originals       - Originals go here (unless you use the -o option)
	thumbs          - Thumbnail versions go here
	ButtonLeft.gif  - Buttons used by the pages
	ButtonRight.gif
	ButtonTop.gif
	webshow         - The webshow script itself
	webshow.css     - A CSS file used by the HTML pages
	myrename        - A quick-n-dirty Perl script to rename files
	filelist        - The ASCII text file that controls things

It works like this: you put all your photos into the originals directory. Use a photo manipulation utility to create thumbnails in the thumbs directory, and medium sized versions in the images directory. [see the mikes_script description at the bottom of this page]. Thus for any given image, there will be three files, each with the same identical name, in the three directories: thumbs, images, originals. The only difference in them will be their size in pixels. I use a max of 100x100 for the thumbs, and 512x512 for the images. You can use whatever sizes you like, the script doesn't care.

If you don't want to bother with 3 sizes of each photo, you can omit the originals directory and put the original photos instead directly into the images directory. In that case, you will run webshow with the -o option -- thus it won't require an originals directory, and won't turn the photos on the individual HTML pages into links (as it would normally).

Then create the filelist file, which contains the names of the image files, one per line. I use the Unix command "ls -1 originals >filelist" or the MS-DOS command "DIR/B originals >filelist" to initially generate the filelist file.

Then I edit the filelist file according to the following rules:

1. All lines with a '#' character in column 1 are treated as comments and ignored. Blank lines are also ignored, and can be used to make the source more readable.
2. Lines beginning with a plus sign (+) are "magic" as follows:

   +TopPage: xxx	Specifies the filename for the top level page (the default is index.html). 'xxx' is the filename.
   +TITLE: xxx	Defines a title for the top-level Webpage. The 'xxx' becomes the text of the title.
   +DESCRIPTION: xxx	Provides some textual description for the page, which appears right below the title. 'xxx' is the text.
   +COPYRIGHT: xxx	A place for you to specify a copyright notice (the 'xxx' text) to be displayed at the bottom of every page. See the example for the code to produce a copyright symbol.
   +SECTION: xxx | yyy	Defines a section header, to break the top page into sections. The 'xxx' becomes an <H2> html tag, and the 'yyy' becomes the description below it. You can leave out the 'yyy' part if you wish, but if you include it you must separate it from the 'xxx' part with a vertical bar (|).

   You don't have to include any of the above, but they are there to make the resultant Webpages more informative and useful. If you do include them, put them first in the filelist file, before any image filenames.
3. Subsequent non-comment lines are assumed to contain the filename of an image. These lines can contain descriptive text, which will appear on the Web page generated for this photo. A vertical bar '|' character separates the filename from the description. The description is optional.
4. Any line may be 'continued' by indenting the following continuation line with a <TAB> character. This is generally needed for the +SECTION: line, and the +DESCRIPTION: lines. See the example below.

An Example

The example filelist below generates this Web page.

# ---------------------
# Example filelist file
# ---------------------
+TITLE: This is the Page Title
+DESCRIPTION: And this is the text at the beginning of the page.
	You can continue with as much text as you want here by indenting
	each line with a <TAB> character.  You can also put HTML here
	if you want.<p>
	Click on an image to start the show.  From there you can navigate
	forwards, backwards, or back here.  When you click on an
	image it will take you to a larger version.
+COPYRIGHT: Copyright © 2002-2004 by H. Marc Lewis.
	All rights reserved.

750SS.jpg | 
Aprilia.jpg |
cavelake.jpg | By the way, all these photos are 
	Copyright © 2003 by H Marc Lewis.  All rights reserved.
Chatcolet.jpg |
Columbia.jpg |
FJR1300.jpg |
Hyder-AK.jpg | Hyder, Alaska
LoloPass.jpg |
RattleSnakeGrade.jpg |
StoneHenge.jpg |

+SECTION: Non-motorcycle photos |
	These photos don't have much to do with motorcycles, but they
	serve to show how you can use the sub-title feature to break the 
	top-level page into sections, as might be appropriate for various
	subjects...

Pie.jpg | Wonderful pie from Huckleberry Heaven, Elk River, ID
Pumpkins.jpg 

The webshow script can be configured somewhat, see the first few lines in the Perl script. However, it does expect the input file filelist to exist and be so named. It also expects (and checks for) the proper directories to exist. It produces a single "I'm done" line noting how many image files it found for which it generated Web pages.

What webshow does

Each time you run webshow it reads the filelist file and generates one HTML file in the html directory for every file listed in the filelist file. It also creates the top-level directory index page (generally index.html). It doesn't do anything with the image files, and doesn't even read the image, thumbs, or originals directory. So even if the image files aren't there, it will still do its job -- though the resultant HTML pages will have broken links.

If you run webshow -o instead, the only difference in operation is that it won't expect there to be an originals directory, and it won't generate any links to the large-sized photos that would normally be stored there.

The 'development cycle' I use is to edit the filelist file, then run webshow, then look at the Web pages just generated, and repeat until I'm satisfied with the results.

Examples:

webshow	-- the 'normal' case
webshow -o	-- omit the 'originals' directory and links to it
webshow whatever.html	-- create 'whatever.html' instead of the default (index.html)

Notes

1. You can omit photos from the show by simply deleting the appropriate line in the filelist file.
2. You can rearrange the order in which the photos are displayed by rearranging the lines in the filelist file.
3. Feel free to modify the CSS file webshow.css to suit your tastes. The version included here suits me, but you may prefer another style.

Obtaining Perl

Linux/Unix users already have Perl. For you Windoze folks, ActiveState has a fine port pre-compiled for various flavors of Windows. I've successfully used the Windows version of Perl to create slideshows with this version of webshow on Win98SE, Win2k and Windows XP Pro systems. There are also ports of Perl for the Apple (various operating systems).

Other tools

I used two tools to generate the images and thumbnails, and found LVIEW-PRO (in batch mode) to be the easy way to go. I liked WEB IMAGE GURU as it did "smart" thumbnails, allowing you to thumbnail just the "important" part of the photo, but it didn't always work right and took forever. [my friend Lee prefers a utility called ACDSee]. You can get functional eval copies from Tucows or downloads.com. Just about any tool that will create thumbnails in batch mode will work fine -- you can even do it by hand if necessary, you only have to do it once...

Michael Bain contributed a script which I have named mikes-script and included in the tar file. It uses the ImageMagick package (commonly found on Unix/Linux systems) to auto-generate the thumbs and images files, given the originals directory is populated with your photos. It's very short, and you can easily modify it to suit your needs.

Thanks to Jack Tavares for the enhancement to add a user-specifiable copyright notice.

Postscript

It is really pretty simple to use, once you get the hang of it. If you make anything more than minor changes to 'webshow', I'd appreciate it if you send me a copy. Thanks!

BTW -- There's a real-life example implementing a slideshow of an Alps tour I did in 2001. It used an early-release (Aug-2001) version of webshow. Another more current version is a trip to Baja, Mexico by motorcycle which I did in March of 2004.

HMarc -- August, 2004