Icon The Kermit Project   |   Now hosted by Panix.com
New York City USA   •   kermit@kermitproject.org
…since 1981

The Photogallery script

A Kermit script for automated creation and maintenance of photo galleries on the Web

Author:  Frank da Cruz
Script version: 2.32
Dated: 2018/06/04
Platform:  Any version of Unix where C-Kermit is available.
Requires:  C-Kermit 9.0.304, Image Magick.
This page last updated: Sun Jul 22 16:24:01 2018

Photogallery is a program written for the Unix operating system family* in the Kermit script language that builds an HTML gallery for the World Wide Web from a collection of JPG images: photos, scans, screen shots, or any other type of image in JPG format. The gallery pages are coded in HTML 4.01. Like all Kermit scripts, Photogallery is a text-mode program; it is to be run in an interactive Unix shell session, in a terminal screen. The Photograllery script can probably be made to work in Windows and/or in VMS with some work, if there is any interest. This document assumes a basic knowledge of Unix and the language (HTML) and structure of Web pages.
* UNIX is an operating system family that includes Linux, Mac OS X, Android, FreeBSD, NetBSD, HP-UX, Solaris, AIX, and hundreds of others. Click here and here for more information about Unix.

Screen shot of a Photogallery gallery - click on it to visit the gallery itself:
Gallery example


04 Jun 2018: Version 2.32... New features for banners, menus, image strips across top of gallery front page (such as this one); more scaling improvements; minor bug fixes.

24 Mar 2018: Version 2.27... A minor improvement to image scaling in subpages.

05 Mar 2018: Version 2.26... Fixes a text-formatting glitch when when the new 'maxwidth' variable was not defined; adds a 'text' tag to the text under an image in each subpage so you can link to the the text, e.g. .

10 Feb 2018: Version 2.25... I finally got the subpage-image scaling right. Now, now matter the size or aspect ratio of an image, it fits any viewport, regardless of the viewport's size and shape, and can also be stretched or squeezed, and the caption has the same width as the image. Other changes: allow IMAGES and PARAMS filenames to be lowercase (for example, if they were transferred by Kermit with "set file names converted"); make sure all images have 1px borders; make sure original image has read permission (for Enlarge button); improved image Alt text (now it's the filename instead of just a number).

27-30 Dec 2017: Version 2.21-2.24... Better (if still not perfect) handling of portrait images in subpages. Previously they would tend to disappear off the bottom of the page. Now they are scaled according to the aspect ratio of the image so you'll usually see the whole image and in most cases the beginning of any text under it (unless your browser window is very short). The problem is that HTML allows scaling of images only in one direction, not both, at least not while preserving the proportions. The new scaling works "pretty well" on computer screens of all different heights and widths, tolerably on cell phones in vertical orientation, but obviously not so well on cell phones held sideways. Scaling might also be done with @media min/max-height queries, but this would result in jumpy screens when squeezing or stretching the browser window. Other approaches such as the new vh/vw/vmin/vmax units might do the job but they are not necessarily supported in all browsers and in any case result in a confusing user interface (landscape images scale horizontally and can't be squeezed or stretched vertically, while portrait images scale vertically and can't be squeezed or stretched horizontally).

26 Dec 2017: Version 2.20... New maxwidth parameter. This allows you to create a gallery without having to resize the images, which is desireable if you didn't intend to discard the originals; this way, instead of have three versions of each image (original, resized, and thumbnail), you have only two. Makes a difference for big galleries.

19 Dec 2017: Version 2.19... Generates HTML5.

21 July - 4 December 2017, versions 2.14-2.18... minor fixes.

26 May 2015: Version 2.13... Adds an option to put Pinterest "Pin it" (a.k.a. "Save") buttons on subpages.

25 May 2015: Version 2.10–2.12... Minor fixes plus improved handling of thumbnails on narrow screens; see example HERE (on a big PC screen, squeeze and expand the browser window horizontally). Previously the default thumbnail size (height 160px) was just too big for small cell phones.

25 Oct 2015: Version 2.08–2.09... Allows the inclusion of some text between a subtitle and the following thumbnail images on the gallery index page (read more). Also some improvements to the scaling of portrait images.

12 Aug 2015: Version 2.07... Previously when resizing images for the sub-pages, portrait and landscape images were treated the same. But for portrait images, this often resulted in the image being taller than the screen, leaving any caption or text out of sight below the viewport. Better to try to make the whole image fit on the screen and at least some of the text, so you know there is something to read. As of version 2.07, Photogallery resizes portrait images to 60% of the resize value. Since HTML doesn't have a way to automatically size an element to the height of the viewport, as it does for the width, the result can be less that satisfying. But I think it's better this way; if an image seems too small, at least you can always click the Enlarge button; if it seems too big, then at least it's not as big as it was before.

18 Jul 2015: Version 2.03-2.06... Minor adjustments and fixes.

19 May 2015: Version 2.02... Previously you had a choice of what should happen when a sub-page image was clicked: go to the next image, or enlarge the current image. It occurred to me that it would be better if both options were always available for every image, so now there is an Enlarge button in the navigation row, right after the triangles, and clicking on the image always goes to the next one. You can see an example of a gallery that is both mobile-friendly and has the Enlarge button HERE.

23 Apr 2015: Version 2.00... New “Mobile-friendly” version. Generates galleries and subpages that pass Google's Mobile-Friendly Test. This kind of removes the distinction between SCALE and NOSCALE but that's progress! Also: for cases where you are not including an external head file, allows specification of stylesheet and favicon for the default header it generates. Also, this page (that you are reading) is "mobilized" too except that it contains some unavoidably wide tables.

13 Aug 2014: Version 1.15. Allow labels to be associated with subsections; don't generate Javascript if scaling is not elected.

23 Jul 2014: Version 1.14. Allow specification of gallery subsections and subtitles. Add index2 parameter (text to put below thumbnails). Don't assume return code of \fpictureinfo() is index into array element holding length of longer side because new third element is "date taken". Fetch and install this version with Getkermitscript.

14 Jan 2014: Version 1.12 (and 1.11) more options for handling uplink; new dontenlarge option; exit if images file specified but no images found. Plus a new automated installation script is available, HERE.

20 Oct 2013: Version 1.10 (and 1.08-1.09) fix a couple minor bugs (see comments in source).
27 Sep 2013: Version 1.07 fixes a typo that prevented Photogallery from finding its index.txt file.
18 Sep 2013: Version 1.06 allows images from other directories, multiple galleries in one directory.
15 Sep 2013: Version 1.05 allows Javascript to be disabled.
14 Sep 2013: Version 1.04 allows the scale parameter to work with Microsoft Internet Explorer (using Javascript).
08 Sep 2013: Version 1.03 fixes some bugs when adding images to a gallery.
07 Sep 2013: Version 1.02 allows normalization of image file names and sorting of images based on date taken.
07 Aug 2013: Version 1.01 allows image file names to be taken from a file.
04 Aug 2013: Initial version, based on a script from 2006 called Photoalbum.


In its simplest application, the Photogallery script creates a gallery in a fresh directory that contains only the images that are to be shown. It is driven by the JPG images it finds in the directory. The normal sequence is:
  1. Create a new directory and give it the desired access permissions.
  2. CD to the new directory and upload or otherwise move the JPG files into it.
  3. Run the Photogallery script, supplying at least a title for the gallery.
The Photogallery script always operates on its current directory. Be sure to CD to the desired directory before running the script. All the JPGs found in the directory are included in the gallery unless you specify otherwise. Text, captions, and special special effects can be added as explained below.

When you run the Photogallery script...

The script takes some pains to avoid excessive image processing. On its first run for a particular gallery, it produces resized versions of each original (unless told not to), plus a thumbnail for the main gallery page. If you run the script again, it skips these steps unless you have changed the original image or have added new images, in which cases it will only resize and make new thumbnails from the changed or new images.

The script is designed to allow the gallery to be expanded as new photos arrive, and can be run repeatedly on the same gallery without undoing previous work.
* Most images that come from modern digital cameras, cell phones, scanners, or similar devices are too big for web browsers. Photogallery uses an external program, Image Magick convert, to resize them (in both dimensions and byte count), and also to produce thumbnails (very small versions of each image) for the main page. You can control the sizes but reasonable defaults are supplied. The original images are retained but can be deleted once the gallery is created.


This script creates an index.html file in your current directory unless you tell it not to via the 'indexfile' parameter (see below). Unless you want your website home page to be a gallery, YOU SHOULD NOT RUN THIS SCRIPT in the top-level directory of the website without specifying a different name for the index file, because this will replace the website's home page, the index.html file. There is no foolproof way for Photogallery (or any other program) to know whether it is running in the home directory of a website. However:


The Photogallery script requires C-Kermit 9.0.304 or later* on a Unix-based operating system, and also that the Image Magick convert program is installed in your PATH (that is, if you type “convert -version” at the shell prompt, you'll see some text like “Version: ImageMagick 6.2.9” rather than “convert: command not found”).  Download links:

Link to download... Status
[CLICK] C-Kermit 9.0.304 Free open-source software, next release (in development)
[CLICK] Image Magick** Free open-source software
[CLICK] The Photogallery script Free open-source software [LICENSE]
Better, download the Photogallery script with Getkermiscript that does the following steps for you.

After downloading the Photogallery script (if you did not download it with Getkermiscript), follow these steps:

* The script should also work with earlier versions of C-Kermit 9.0, but certain features will not be available: sorting by Date Taken, anything to with locales, etc.
** Strictly speaking, Image Magick convert is not required, but if Photogallery doesn't find it, it won't be able to resize pictures or make thumbnails. If you have some other way of doing that, or if you are willing to have text links in place of thumbnails, you can still use Photogallery to create galleries. Name the thumbnails as shown in the table in the following section.

Simplified Method

As of version 2.20, many of the parameters and techniques described below are superfluous. Scaling of images to window size is done automatically, and this makes resizing unnecessary except when the original images are very large and you want to save space. Default colors are black on white. "Arrows" (rather than words) are used by default for navigation. Images are not enlarged beyond their actual size. The following PARAMS file is appropriate for use Photogallery 2.20 or later:
.title = Family Photos   # Gallery title
.height = 80             # Thumbnail height
.enlargebutton = 1       # Include an Enlarge button
.maxwidth = 700          # Maximum width for subpages


These are the names of the files that actually compose the gallery, and that are served by the web server when the gallery is visited. Note that file names in Unix operating systems (with the possible exception of Mac OS X) are case-sensitive.

Name Example Created by Description
imagename.jpg dscn1234.jpg Your camera or scanner (etc) An original image
imagename-r.jpg dscn1234-r.jpg Photogallery + Image Magick A resized version of the image
imagename-t.jpg dscn1234-t.jpg Photogallery + Image Magick A thumbnail of the image
imagename.html dscn1234.html Photogallery Gallery subpage for this image
index.html index.html Photogallery The home page of your gallery

Image file names must be lowercase; for example dscn4321.jpg rather than DSCN4321.JPG. This is because (a) Unix filenames are case-sensitive and (b) the script assumes all image files have names ending with “.jpg”. If your images have uppercase letters in their name, you can convert them to lowercase by including:

on the command line (or in the PARAMS file, explained below). The script does not do this by default because you might want to have images in the directory that do not appear in the gallery, or different images whose names have the same spelling but different casing.

You can also use Kermit's RENAME command; for example:

rename /lower *.JPG
If the JPG images have a different extension such as .jpeg instead of .jpg, this too can be fixed with Kermit's RENAME command:
rename /replace:{{.jpeg}{.jpg}{$}} *.jpg

Once the gallery is built, the originals can (but need not) be deleted. If an original image is changed (e.g. by editing it in Photoshop) and the script is run again, a new thumbnail and a new resized version are produced automatically.

To add or modify text or captions, create or change the relevant *.txt files and run the script again to rebuild the HTML files (see examples below).

If any of your original images have filenames that end with -r.jpg or -t.jpg, all bets are off!


Normally, all .jpg files in the directory are included in the gallery. Unless instructed otherwise, Photogallery orders the images “alphabetically” by filename; that is, in the same order Kermit's “directory *.jpg” command would list them. Image files originating from cameras, scanners, cell phones, and similar devices generally have a naming sequence that corresponds with chronological order. For example, a photo with image name dscn1234.jpg will have been taken before dscn1235.jpg from the same device.

To change the order in which images appear, you can:

When you use an IMAGES file to specify the source images, the images need not be in current directory. To include images from other directories, just put the relative or absolute pathname of each image in the image file.

Use an IMAGES file when you want to:


Suppose you want your gallery to be divided into sections, with a title for each section, like this one. In this case, I've made what appears to be a gallery of galleries of different places in the Bronx. To do this you can include [SUBTITLE] lines in your IMAGES file, like so:
[SUBTITLE]Van Cortlandt Stadium
[SUBTITLE]Van Cortlandt Park Southwest Playground
[SUBTITLE]Bronx County Courthouse
Subtitles only work when you're using an IMAGES files, and they don't work if you tell photogallery to SORT the images.

When you specify a subtitle, it appears on the main gallery page on a line by itself above the images whose names follow it in the IMAGES file. It also is appended to the title of each subpage until another [SUBTITLE] directive is encountered. Visit the Bronx New Deal gallery to see how this looks.

If you wish to be able to link to subsections of your main gallery page, you can include a label in your [SUBTITLE] directive:

[SUBTITLE:vcstadium]Van Cortlandt Stadium
[SUBTITLE:vcswplayground]Van Cortlandt Park Southwest Playground
[SUBTITLE:bxcourthouse]Bronx County Courthouse
If you want to include some text after the subtitle and before the thumbnails, put it in a file and then include the filename as the second parameter to the SUBTITLE directive:
[SUBTITLE:bxcourthouse:bxcourthouse.txt]Bronx County Courthouse
and Photogallery will copy the contents of the file directly into the gallery's index page just below the subtitle, as a <div>. The "subtext" is copied literally and can include any HTML you like.

If you wish to override the subtitle for a particular image, create a file with the same name as the .jpg file, but with a file type of .ttl instead of .jpg; for example, davc00.ttl for the image davc00.jpg. WARNING: If the ttl text is longer than the image is wide, this might interfere with Google's “mobile friendly” determination.


The entire process of creating and maintaining a gallery can (but need not) be controlled by a file named PARAMS (upperase) in the same directory where the images are. The file contains the parameters used for the gallery. While the following sections discuss the kinds of things you can specify in the PARAMS file, it is important to understand that it is nothing more than a Kermit command file, and can contain any Kermit commands at all, as well as blank lines and comments in Kermit syntax. Normally it contains definitions for the same variables that you can define on command line (listed below). Here is an example (# indicates a comment):
# Photogallery parameters file for the Mermaid Parade
.title = Coney Island Mermaid Parade June 22, 2013, Brooklyn NY
.shorttitle = Coney Island Mermaid Parade 2013
.head = ../head.html                # Use standard head file   
.tail = ../tail.html                # Use standard tail file   
.copyright = ../copyright.html
.root = festivals

You can set the same set of parameters with the PARAMS file or from the command line. Any variables that you set on the command line override the settings of the same variables in the PARAMS file.

NOTE: The PARAMS file is a Kermit script and has the same syntax rules as any other Kermit script. So, for example " #" begins a comment. Therefore a command like:

.background = #fff0f0
will be interpreted as:
.background =
To specify colors using this notation, use:
.background = "#fff0f0"


You can create some “helper” files that make the creation and maintainance of a gallery much easier, and the end result more pleasing. This section applies to the normal case, where a gallery has its own directory. Later you'll see how to put multiple galleries in one directory or to put a gallery in the home directory of a website without interfering with its home page. File names in most Unix operating systems are case-sensitive, so "PARAMS", "Params", and "params" would be three different files.

External gallery components (all optional)
File Default name Used in Used for
Parameters file PARAMS whole gallery Gallery configuration
Images file IMAGES whole gallery List of images to be included in gallery
The head file (none) index.html HTML prolog, style, menus, etc, for index.html
The Index text file index.txt index.html Text to be included above the thumbnails
The Index text file index2.txt index.html Text to be included below the thumbnails
The tail file (none) index.html End matter, HTML epilog
imagename.txt Invariant Each gallery sub-page Caption or text for each image
The copyright file (none) Each gallery sub-page Copyright notice for each image

Gallery with head file The beginning and end of the main page of the gallery (its index.html file) can be copied from an external file if you wish. This is desirable if you want your gallery to have some kind of banner and/or menu on top and/or on the bottom, and/or a particular style or look, as in the example on the right (click it to see it in full size). The importable top part is called the head file; you can specify it in any of these ways:

The Head File (optional)
Method Example
In the PARAMS file .head = head.html
In the PARAMS file define head ../head3.html
On the command line head="../head3.html"
As an environment variable export HEAD_HTML=~/heads/special.html

(Note: the “../” notation is a Unix shortcut for “in the superior directory”.) The head file should contain the HTML prolog, the <head> section, the <body> tag, and whatever else you want to appear above the thumbnails except text particular this gallery (which comes from the index.txt file). When you import an external head file, the string _PAGETITLE_ is replaced by the gallery title. Within the <head> section you can have a <style> section where you can choose the font and so on. If you don't specify a head file, the script generates a minimal HTML prolog, <head> section, and <body> tag.

Gallery with tail file Similarly, for the end of the index page there can be an external tail file specified in the same way:

The Tail File (optional)
Method Example
In the PARAMS file .tail = tail.html
In the PARAMS file define tail ../headsandtails/tail4.html
On the command line tail="../tail3.html"
As an environment variable export TAIL_HTML=~/$USER/html/standardtail.html

The tail file should include the </body> and </html> tags, but you can also include whatever you want before that: links, menus, logos, text.

When you import a tail file, if it contains the string _PAGEDATE_, this is replaced by the current date. If there is no tail file, a minimal tail is provided by the script.

Language, color, and background specified in the head file take precedence over whatever you might have specified on the command line or in the PARAMS file, but only for the index page; the sub-pages still use the settings you specified.

Finally, you can have a copyright file if you wish to place a copyright notice on the bottom of each sub-page. (CLICK HERE to see an example of a sub-page with both a caption and a copyright notice).

The Copyright File (optional)
Method Example
In the PARAMS file .copyright = copyright.html
In the PARAMS file define copyright ../includes/copyright.html
On the command line copyright="../copyright3.html"
As an environment variable export COPYRIGHT_HTML=~/$USER/html/standardcopyright.html

If the copyright file contains the string _YEAR_, it is replaced by the current year.

File permissions: The files that are used to build to the gallery, including the PARAMS and IMAGES files, the original JPG images, and any head, tail, or .txt files, do not need to be world-readable. In fact you might prefer to keep them private; for example to avoid having the transmission lines clogged by large, high-resolution images. The files that actually compose the gallery – the resized and thumbnail images and the HTML files – are, of course, automatically protected to allow public reading. The default permission for these files is 664. You can override this on the command line or in the PARAMS file as explained below. For an explanation of Unix file system permissions, click here.


Parameters for a gallery can be specified: When the script is to be invoked repeatedly for the same gallery, it is best to put the parameters in the PARAMS file so you don't have to type them each time.

On the command line, parameters are given as:

OR (doublequotes required around values with spaces by Unix shell):
name="value with spaces"

In the PARAMS file, the syntax is slightly different:

.name = value
In this case, each definition must begin with a period, and the equal sign must have spaces around it. If the value contains spaces it may, but need not, be enclosed in doublequotes:
.title = Vacuum Tube Computers
.title = "Vacuum Tube Computers"
When giving parameters on the command line, all parameters except title are optional. Photogallery's command-line parameters are listed in this table and explained in more detail below it:

Photogallery parameters
Parameter Value Default Command-line example Description
arrows 0 or 1 1 arrows=1 Use arrows for navigation
background Color name or code #fff0f0 background=white Background color
color Color name or code darkmagenta color=blue Foreground text color
copyright filename (none) copyright=copyright.txt For bottom of each sub-page
dontenlarge 0 or 1 0 dontenlarge=1 When resizing don't enlarge
enlargebutton 0 or 1 0 enlargebutton=1 Display an Enlarge button
favicon filename (none) favicon=favicon.ico Shortcut icon for web browser
fixfilenames 0 or 1 0 fixfilenames=1 Normalize image file names
head filename (none) copyright=../head.html For top of index page
height number of pixels 160 height=200 Height for thumbnails
help (none) (none) help List command-line options
imagesfile filename IMAGES imagesfile=newimages Name for alternative IMAGES file
indexfile filename index.html imagegallery.html Name of gallery main page
language English or Spanish English language=spanish Language for navigation
linktonext 0 or 1 1 linktonext=1 Click-on-image action (OBSOLETE)
maxwidth number 0 maxwidth=740 Maximum subpage width (0 = none)
noarrows 0 or 1 0 noarrows=0 Use words for navigation
noscale 0 or 1 1 noscale=0 1=don't scale, 0=scale
paramsfile filename PARAMS paramsfile=newparams Name for alternative PARAMS file
permissions octal number 664 permisssions=644 Permissions for gallery files
pinterest your website url (none) pinterest=http://your.url Adds pinterest button to each subpage
resize number of pixels 740 resize=0 0 means don't resize
root directory path none root=. See Advanced Use
scale 0 or 1 0 scale=1 1=scale, 0=don't scale
sort 0, 1, or 2 0 sort=1 0=no, 1=yes, 2=reverse
shorttitle string same as title shorttitle="Parade" Short title for sub-pages
stylesheet filename (none) stylesheet=mygallery.css External cascading style sheet file
tail filename (none) copyright=../tail.html For bottom of index page
title string (none) title="Mexican Parade" Title of the gallery
uplink     uplink=../index.html Where uplink should link to
version (none) (none) version Show script version

Example using command line:

photogallery title="New Models for Fall 2013" color=gold background=black
Example using PARAMS file:
.title = "New Models for Fall 2013"
.color = gold
.background = black
Resizing and thumbnails are not done by the script itself, but by an external package called Image Magick, which is freely available for Unix, VMS, and Windows. If Image Magick is not available, the script still works, but images won't be resized and thumbnails will not be produced (text links are shown in their place on the index page).

The ARROWS parameter...
says whether to use "arrows" for navigation icons. These are actually Unicode triangles: ▲ ▶ ◀. If you specify arrows=0, then words are used, English or Spanish according your language selection. Since the default value is 1, if you give an arrows parameter without a value, it is the same as specifying arrows=1.
The BACKGROUND parameter...
is the background color to be used for the index page (unless a different background is specified in a head file) and all sub-pages. Normal HTML color names or numeric tags (such as #fff0f0) are used. In PARAMS file numeric color names should be enclosed in doublequotes because the '#' makes it look like a Kermit comment:
.background = "#fff0f0"
The COLOR parameter...
is the foreground color; the color to be used for text, lines, arrows, and borders on the index.html page and on the sub-pages (also in HTML notation. It also determines to some extent the "hover" color for links; for example, if the color parameter is gold the hover color will be yellow.
The DONTENLARGE parameter...
When resizing would result in enlarging an image, which would necessarily make it more blurry, this parameter says to skip resizing and display the image in its own size. Thus, large originals will be reduced but small ones will be left as-is.
The ENLARGEBUTTON parameter...
When set to a nonzero numeric value, this causes Photogallery to include an Enlarge button on the navigation bar of each sub-page, which, when clicked, displays the original non-resized image in full size. If the original does not exist, the Web server displays a "not found" message. Thus if you create a gallery with enlargebutton=1, you should not delete original images unless you also run Photogallery again with enlargebutton=0.
The FIXFILENAMES parameter...
normalizes image file names, converting them to all lowercase and changing any .jpeg files to .jpg, as required by the script. If you request that Kermit normalize filenames, this applies also when the names are taken from an IMAGES file, in which case a new IMAGES file is created containing the normalized names.
The HEIGHT parameter...
applies to the thumbnails generated for the index page; it tells how many pixels high each thumbnail should be.
The HELP parameter...
is not exactly a parameter, it tells the script to print a list of its command-line options. It also does this if you run the script with no arguments and there is no PARAMS file.
The IMAGESFILE parameter...
You can provide an explicit list of image files from which to build the gallery in a file named IMAGES, which Photogallery looks for automatically when you run it. But in case you want to have more than one gallery in the same directory, with one or more of them using an images files, you'll need to prevent confusion over which gallery uses which IMAGE file. To specify an alternative filename use the "imagesfile=xxx" option on the command line or ".imagesfile = xxx" in the PARAMS file.
The INDEXFILE parameter...
Normally the main page of the gallery is named index.html. But in case you are building a gallery in a directory that already has index.html file that you don't want to destroy, you can give the gallery's main page another name of your choice; for example:
.indexfile := bronx.html
When you specify an indexfile name, then Photogallery also looks for the corresponding .txt file, in place of index.txt; e.g. bronx.txt.
The LANGUAGE parameter...
tells whether text generated by the script (such as instructions, tool tips, navigation labels, dates, etc) should be in English (which is the default) or Spanish. As of this writing, those are the only choices. Spanish text is written in the ISO-8859-1 character-set, properly announced. If you specify language=spanish and you have an external head file, it should include the following:
<html lang="es">
<META http-equiv="Content-Type" content="text/html; charset="ISO-8859-1">
At present it is not possible to use a different character set (such as UTF-8), at least not if you have selected Spanish as the output language, because Spanish words in the script are encoded in ISO-8859-1. This could be addressed if there were any interest.
The LINKTONEXT parameter...
Obsolete and ignored if you give it. Now clicking on a subpage image always goes to the next page, and there is a new Englarge button if you want to enlarge the current image.
The NOARROWS parameter
is the same as the ARROWS but with opposite sense: noarrows=1 is the same as arrows=0. If you include a noarrows parameter without a value, it is the same as specifying noarrows=1; that is, don't use arrows.
The NOSCALE parameter...
is the opposite of the SCALE parameter (see below).
The PARAMSFILE parameter...
Photogallery looks for parameters in a file called PARAMS in the current directory. But in case you want to have more than one gallery in the same directory, you can have a different parameters file for each one, but then each parameters file must have a different name. You can tell Photogallery which parameters file to use by including the 'paramsfile=xxx" option on the command line.
The PERMISSIONS parameter...
lets you specify the permissions for the JPG and HTML files that comprise the gallery. The default permission is 664, meaning owner and group can read and write the files, others can only read them. You might want to change this to 644 if you don't want others in your group to be able to change or delete your gallery files.
The PINTEREST parameter...
Pinterest is a social media site were people can post photos and other images. It's a good way to draw attention to your gallery (if you want to do that). The PINTEREST parameter tells Photogallery to add a Pinterest “Pin it"” button to each gallery subpage. The user clicks this button to “Pin” the image to any of her or his Pinterest boards. Users who do not have a Pinterest account are given the opportunity to open one (it's free). The value of the Pinterest parameter is the URL of the website of the gallery you are making. Photogallery has no way of knowing this, so you have to specify it so the Pinterest button knows where to find the image and the associated HTML page. Suppose you have a website at www.mywebsite.com and you are making a gallery in a subdirectory 'foodgallery'; here's what you would put in your PARAMS file:
.pinterest = http://www.mywebsite.com/foodgallery/

The Pinterest button is done Javascript. This has two implications:

  1. Visitors to your website will see the button only if they have Javascript enabled.
  2. Photogallery must load the Javascript. As distributed it loads it from http://kermitproject.org/ftp/kermit/scripts/pinterest.js, which is the same place you downloaded the Photogallery script from. If you wish you can download pinterest.js to your own website, but then you have to change the Photogallery script (the code that starts just below the long introductory comments).
See Photogallery galleries with Pin-it buttons on their subpages HERE and HERE.
The RESIZE parameter...
tells whether to resize the original images for display in the sub-pages, and if so, to what size. RESIZE=0 means don't resize them; that is, put them in the subpages exactly as they are. Use this when your original images are small enough to fit into a normal browser window. When you give a number (e.g. RESIZE=600), this says to resize the image so its longer dimension (height or width) is that many pixels. Resizing is not destructive; it makes a copy of each original image with “-r” added before the .jpg in the name. This way you can always come back and re-resize them to a different size if you wish, as long as you haven't deleted the originals.
The SCALE parameter...
The SCALE and NOSCALE parameters are not used in Photogallery 2.00 and later. Now sub-page images are always scaled to fit horizontally across the screen, up to their actual width. Then, to see a larger version of the image, an Enlarge button is included on the navigation bar.

Previously the SCALE parameter applied to the image shown in each sub-page. Normally the image (original or resized) is shown in its true size, regardless of the window size. With scale=1 (or noscale=0), the image is scaled by the browser to fit the window size. If you are using Firefox, Chrome, Safari, Opera, or probably any browser other than Internet Explorer, then if you change the window size by dragging or maximizing or restoring, the image size changes with it. If you're using Internet Explorer, you'll need to reload the page to see the image in the new size after the resizing the browser. Use scaling only for fairly large images, because smaller images don't look good when magnified.

The SHORTTITLE parameter...
specifies the title to be used for sub-pages. If no SHORTTITLE is specified, the title is used.
The SORT parameter...
lets you tell the script to arrange the images in chronological order according to the "Date Taken" that is recorded by the camera or scanner inside the JPG file itself. The default is not to sort. When sort=1, the filenames are sorted in normal chronological order (oldest first, latest last). When sort=2 (or any number greater than 1), they are sorted in reverse chronological order (newest first). Note:
  • If any of the images do not contain a "Date Taken", the images can't be sorted. Kermit detects this, cancels the sorting operation, and proceeds with the gallery. This can happen, for example, if you saved the Image from Photoshop's “Save for Web & Devices” option, which strips most non-graphic information out of the JPG file before saving it.
  • If you have an IMAGES file, the names specified there will be sorted too if you specify sort with a nonzero value.
  • Sorting by Date Taken works as expected only if all the cameras or scanners that created the JPG images had their date and time set correctly.
Sorting is useful when the names of the image files would not produce a chronological arrangement; for example, when you have images from different devices, or image from a device whose naming sequence wrapped around.

You can use a separate Kermit script, Jpginfo, to get a listing of JPG files with their internal information: date taken and dimensions. CLICK HERE to download it.

The TITLE parameter...
specifies the title for the gallery and for its index page. It goes in the HTML <title> clause and also appears as the main heading on the index page.
The UPLINK parameter...
lets you specify where the uplink (normally shown as ▲) goes to when clicked. If this parameter is not specified, it goes to the index.html file of the superior directory, if there is one, or else if a root parameter has been defined, to the index.html file of that directory, or else to the index.html file of the website's root directory.


If you will be making changes to a gallery, or think you might, or even if you don't think you might, it is best to create a PARAMS file. Then any time you need to make changes, you simply run the script again by typing its name; you don't need to enter the parameters again. If you don't have a PARAMS files, then you'll need include all the relevant parameters on the command line each time.
Adding images
To add a new image (or images) to the gallery, simply put the new image(s) in the gallery directory, make it your current directory, and run the Photogallery script again. Example:
cd teachersday
kermit -g img_7654.jpg
Deleting images
To delete an image from the gallery, delete all the files that start with the image's name and run the script again. Example (Unix shell):
cd machupicchu
rm dscn3742*.*
Or, alternatively, create an IMAGES file that lists only the images you want to include.
Renaming images
If you want to rename an image, you should rename not only the original image file, but all associated files accordingly: the rezised image, the thumbnail, and any caption file. And if the gallery is driven by an IMAGES file, the name of the image should be changed in that file too.
Editing images
If you want to improve or change the appearance of an image, edit the original image in Photoshop (or whatever) and replace it, then run the script again and it will generate an updated resized version and a new thumbnail.
Changing the order of images
If you are already using an IMAGES file, just edit it as desired. If not, you can create one like this:
ls -1 *.jpg | egrep -v "(-r.|-t.)" | head > IMAGES
Then edit or sort the new IMAGES file to put the files in the desired order.
Adding or changing captions
Create or edit a file that has the same name as the image file, but ending with “.txt” instead of “.jpg” (for example “dscn4321.txt”. Then run the script again. You don't have to run it again after each change; you can change a lot of files and then run it when you're finished. If you see a mistake on a sub-page, edit the caption file and run the script again. Caption files contain regular plain text but you can also put HTML tags like <b>THISISBOLD</b>, links, or anything else you want.
Adding or changing text on the main gallery page.
Create or edit a plain-text file named “index.txt”, then run the script again. Like the caption files, this one can also include HTML tags. Typical contents include author and/or contact and/or copyright information and a brief description of the gallery.
Changing Photogallery parameters
If you want to change any of the parameters (for example, the size of the thumbnails) edit the PARAMS file and run the script again.


IF you resized the originals (which is done automatically unless you specified resize=0) AND: THEN the gallery doesn't use the originals and you can delete them once the gallery is complete if you want to save space. You can use the following Kermit script to delete all the JPGs in the gallery directory that are not referred by any of the HTML files in the directory:
The script tells you which files it's going to delete and then asks your permission to delete them.

In case you want to dispose of the originals in some other way, you can use C-Kermit to RENAME (move) them to another directory, SEND (transfer) them to another computer, etc. For example, to transfer them:

send /delete /except:*-[tr].jpg *.jpg
which means “send all JPG files except the ones that have “-t” (thumbnail) or “-r” (resized) before “.jpg” in their names, and delete each one after (and only if) it has been successfully transferred.

If you run the Photogallery script again after deleting the originals, it will treat the “*-r.jpg” files as originals. If you run the Deletegalleryoriginals script again, it won't do anything unless you added more originals.


EXAMPLE 1 - Simple no-frills gallery
Screen shots of a simple no-frills gallery...
Gallery index page
Index page
First gallery sub-page
First sub-page
Second gallery sub-page
Second sub-page
Last Gallery sub-page
Last sub-page
To make a very simple photo gallery like this one , you don't need anything but the photos. Create a directory in your top-level website directory, give it the appropriate permissions, cd to it, and upload your photos. Example:
cd public_html Change to top-level directory of website
mkdir bronxday Create a subdirectory called "bronxday"
chmod 755 bronxday     Set the permissions
cd bronxday
Change to the bronxday subdirectory
kermit -g *.jpg Upload the images
Then if you don't care about text or captions and you're only going to do this once, just type:

photogallery title="Bronx Day"

(substituting the desired title). The script resizes the photos, makes thumbnails, creates all the forward, back, and up links, creates an index page, sets the correct permissions on all the files, and when the script is finished running, the page is ready for viewing, for example as:


If you look at the files in the directory you'll see something like this for each image:

img_0100.jpg     An original image
img_0100-r.jpg A resized version for the sub-page
img_0100-t.jpg A thumbnail for the index page
img_0100.html The sub-page itself

and then an index.html file, which shows all the thumbnails. If you wish, and if you did NOT specify resize=0, you can delete the original images (for example, if they are huge and you want to save space); the gallery only uses the -r and -t images unless you specified linktonext=0 or resize=0 on the command line.

EXAMPLE 2 - Gallery with text
Suppose you want your page to have text, and perhaps a different look. In this case you'll need to create some external files for the text, so since you're doing that you might as well create a PARAMS file so you can easily rebuild the gallery any time you want to make a change. Create these files with a regular plain-text editor such as EMACS or vi in Unix or Notepad in Windows.

To add text to the index.html file, just create an index.txt file (you can include HTML tags in it if you wish). After you run Photogallery again, the text will appear after the title and before the images. This would normally be a description of the gallery as a whole; for example:

Rhinebeck Air Show, August 18, 2013, Rhinebeck Aerodrome, Rhinebeck, New York.

Then for each subpage where you want to add a caption, create a file that has the same name as the original image, but with an extension of ".txt" rather than ".jpg", for example "dscn3271.txt" as a caption for "dscn3271.jpg"; these, too, can contain HTML tags (e.g. for boldface, underline, italics, links, etc); example:

<a href="http://en.wikipedia.org/wiki/Sopwith_Snipe">Sopwith 7F.1 Snipe</a>
biplane at Old Rhinebeck Aerodrome with British markings.

Then create a PARAMS file (uppercase name), for example:

.title = Rhinebeck Aerodrome WWI Aircraft Air Show, August 18, 2013
.shortitle = Rhinebeck Air Show 2013/08/18
.background = blue
.color = lightgrey

(Note: the spaces around the equal sign are required, as is the period before the parameter name.)

Run the photogallery script again after creating or editing the index.txt or caption files. You can come back and change the text files any time, or even edit the images in photoshop. Just run the script again to update the gallery.

EXAMPLE 3 - Gallery with customizations
Suppose you want to make the index page look nicer... font selections, logos, colors, links to other pages or sites... For this you can create an external "head file", that contains the HTML for the first part of the index page. The head file contains the <head>...</head> section, including style selections, and then the beginning of the <body> section, such as a banner or title or whatever you like, that should appear above the thumbnails. You just have to let the script know about it:

.title = Rhinebeck Aerodrome WWI Aircraft Air Show, August 18, 2013
.shortitle = Rhinebeck Air Show 2013/08/18
.background = black
.color = gold
.head = airshowhead.html

Similarly for the tail, which might contain dates, copyright notice, contact information, disclaimer, whatever:

.tail = ../standardtail.html


Unless you tell it otherwise, the Photogallery script builds a gallery in a directory of its own, composed of all the JPG images in the directory. The  front page” of the gallery is a page with thumbnails of all the images, plus whatever other content you want to add by providing external HEAD and TAIL files and/or an index.txt file.

But what if you want the front page of the gallery to have the same look and feel and the same menus and links as the other pages on your site? This could be a problem because the gallery is in its own directory, and just copying links from files in the website home directory won't work (unless they are fully-specified absolute links). The normal technique to allow a web page in one directory to use links and menus from another is to put a BASE directive in the index.html file specifying to the URL of the directory to “pretend” that it's in; that is, the base for any relative URLs. You have to put the whole URL or else Internet Explorer won't be able to display the page correctly (BASE="/" is sufficient for other browsers):

<BASE href="http://www.kermitproject.org/">
This way you can copy the code from your other pages to your head and tail files without having to change the links to point to a superior directory. This would not be a big deal if you are only going to have one gallery, but if you have a lot of galleries that share the same head, it can save you a lot of time (read about the HTML BASE tag).
If you are using a head file and you want to take advantage of the BASE feature, you have to put the BASE tag shown above in the head file's <head> section. If you are not using a head file, the Photogallery script will include it automatically.
The BASE tag, however, also introduces a slight complication: now you need special links for the thumbnails and the sub-pages! If you just put their filenames, the web server would look for them in the top-level directory (i.e. the directory indicated by the BASE tag) and, of course, would not find them there.

A special PARAMS-file entry handles this situation:

.root = directoryname

This is the pathname of the directory or directories between the website's home directory and the one where the gallery goes. If a root is specified, the script generates correct paths for the images. If no root is specified, the script just puts their names. Thus, if you are importing a head file that contains a BASE tag, you must include a root parameter in your PARAMS file. If the gallery directory is an immediate subdirectory of the website directory, you can use this notation:

.root = .

If you create a rooted gallery and then rename the directory that it's in (or any superior directory), you'll need to run Photogallery again to generate new links, adjusting the .root = directive as needed.

EXAMPLE 4 - Gallery among other galleries
Suppose you have a website that has lots of parades galleries, so it has a "parades" subdirectory for these, and then each parade gallery is in a subdirectory of the parades directory. But you want to use a standard header with standard menus for each gallery, without having to edit all the links. This is where the root parameter comes in. Specify it in your PARAMS file like this:

.title = Dominican Rican Day Parade
.head = ../head3.html
.tail = ../tail3.html
.root = parades

Then just type "photogallery" to run the script. If the gallery directory is more than two levels below the website home directory, include all the intervening directories in the root definition; for example:

.root = events/bronx/parades
EXAMPLE 5 - Gallery of pictures that keep arriving
Suppose a photographer sends in one or more batches of photos after you have created the gallery. Simply put the new images in the gallery directory, create any desired caption files, and then run the script again. You can do this again and again each time new photos arrive.
EXAMPLE 6 - Gallery of pictures from multiple devices
Suppose you have pictures from different photographers or cameras or devices. Images from each source will have their own naming conventions and sequences and so would come out in a seemingly random order. If you want the photos to appear in chronological order you can create an IMAGES file that lists the image file names in the desired order, or you can tell Photogallery to sort them by Date Taken, as explained above in this section.
EXAMPLE 7 - Example of a nontrivial real-life gallery
Gallery example This gallery uses most of the features described above. The main gallery page has a banner and a menu that is just like all the other pages in the Kermit website, accomplished using exactly the same HTML and links, even though the gallery is in a totally different directory (accomplished with the "root" feature). There's text on on the main page, which comes from the index.txt file, and many of the sub-pages have photo captions, which come from the imagename.txt files. And there's a bit at the bottom of the index page that comes from the tail file:
  • CLICK to see the gallery.
  • CLICK to see the source files.
Clicking the "see the source files" link will give you a listing of the files in the gallery directory, but the results of clicking on them depends on your browser:
  • The PARAMS file should show up as expected. Ditto for any IMAGES file.
  • *.html files such as index.html, will be shown as web pages. To see the HTML code, tell your browser to "Show page source" (Ctrl-U in Firefox; in IE, Right-click on the page, then click "View source").
  • *.txt files such as index.txt or dscf0511.txt will show up as expected.
  • *.jpg image files will show up as images, for example dscf0511.jpg as a full-size image, dscf0511-r.jpg as a resized image, and dscf0511-t.jpg as a thumbnail.
You won't see the head.html and tail2.html files in the listing, though, because they are in the main website directory. That's the whole point; we're sharing the front matter with all the other pages in the website. Here are links to the head and tail files in the main website directory ("view source" to see the HTML code):
EXAMPLE 8 - Example of a Gallery embedded in a website home directory
Gallery example This gallery shows some random images from the main Kermit website directory. It does not interefere with the website's home page. It was produced by the command (all on one line):
photogallery title="Kermit images" indexfile=example.html
and with an IMAGES file listing the images to include. No PARAMS file or anything else.
EXAMPLE 9 - Gallery of pictures from different directories
Gallery example The Kermit project home page shows a random photo of the Bronx (if you click on the photo, another random photo appears). There's a link underneath, “see all images”, to a gallery of all the Bronx images, which is in a different directory. To avoid making copies of all the images for that directory, an IMAGES file was created using this script, which makes a list of all the bronx*.jpg files in the superior directory in "numerical" order (rather than "alphabetical" order, which is different in this case). Then photogallery is run with this PARAMS file to produce the gallery. Whenever a new image is added, the script is run again to incorporate it.

In this example, all the original images are in a single directory, but when using the IMAGES file, each image listed in it can be in any directory at all.

EXAMPLE 10 - Multiple galleries in the same directory
To have multiple galleries in the same directory: For each gallery, Photogallery should be run with the name of the params file on the command line:
photogallery paramsfile=PARAMS3
Each params file should specify unique image and index file names; for example:
.title = Gallery Number 3
.imagesfile = IMAGES3
.indexfile = index3.html
.height = 80             # use the same thumbnail height in all galleries
.resize = 720            # and resize all images to the same size
The names can be whatever you want, as long as they are unique.
EXAMPLE 11 - Changing the order of images in an existing gallery
If the gallery was constructed using an IMAGES file, just edit the file.

If the gallery was constructed without an IMAGES file, you can create one with the following C-Kermit command:

directory /brief /except:*-[tr].jpg /output:IMAGES *.jpg
(NOTE: this command was broken in C-Kermit until November 2014, it is fixed in C-Kermit 9.0.304 Dev.11 and later.) Then edit the resulting IMAGES file to list the images in the desired order, add any desired subtitles, and run Photogallery again to produce the new gallery. Here is an example:
  It uses a PARAMS file, an IMAGES file with subtitles, an index.txt file to put text on top of the thumbnails, an index2.txt file to put more text below the thumbnails, and various options discussed above.


C-Kermit Photogallery script / The Kermit Project / kermit@kermitproject.org / August 2013 - February 2018