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: 3.15
Dated: 26 January 2023
Platform:  Any version of Unix where C-Kermit is available.
Requires:  C-Kermit 9.0 or later, ImageMagick Studio LLC ImageMagick*.
[LICENSE]  [DOWNLOAD [SEE CODE]
This page last updated: Thu Jan 26 07:07:06 2023

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 images: digital photos, scans, screen shots, or any other type of image in JPG, GIF, or PNG format. The gallery pages are coded in standards-compliant HTML5. 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. This document assumes a basic knowledge of Unix and (to some extent) the language (HTML) and structure of Web pages.

See a gorgeous Photogallery example:  Kenya 2020 by Prabhakar Ragde, University of Waterloo, 17 February 2020.

* ImageMagick is free, Open Source, Apache 2.0 licensed software for Linux, Windows, Mac OS X, iOS, Andoid, and other platforms. It is required for resizing of images, but as of Photogallery 3.00, galleries can also be produced without resizing; the tradeoffs are explained below. So strictly speaking, ImageMagic is not required. Website: http://imagemagick.org/.
** UNIX is an operating system family that includes Linux, Mac OS X, Android, FreeBSD, NetBSD, iOS, HP-UX, Solaris, AIX, and hundreds of others. Click here and here for more information about Unix. The Photogallery script could be adapted to Windows and/or to VMS with some work, if there were any interest.

The "iframe" window just below contains a real Photogallery gallery that illustrates many of the features available: menu, image strip along the top; supertitle, title, text, up-link ▲, and a number of labeled sections with thumbnails that are links to subpages that contain larger versions of the photos, descriptive text, and navigation buttons. If the iframe gives you trouble you can visit the page directly HERE.

Live gallery created by the Photogallery script; use the mouse wheel or scrollbar to go down; click any image to see the result. (Warning: don't click the ▲; if you do then there's no way to come back to the demo page... A peculiarity of iframes — they don't have a Back button.) To avoid confusion you can also visit the page directly HERE.
Screen shot of a Photogallery gallery - click on it to visit the gallery itself:
Gallery example
CONTENTS:

News

24 July 2022: version 3.13... Two badly formed IF statements in version check (previous item) corrected.

26 May 2022: version 3.13... C-Kermit version number check fixed to work for C-Kermit 10.0.

16 Oct 2021: version 3.12... If convertpath specified, actually use it!

29 Sep 2021: version 3.11... Prevent empty charset="" declaration in subpages.

12 Jul 2021: version 3.10... Simplify charset declaration in head.

04 Apr 2021: version 3.09... Fixed a problem building a gallery with a non-default imagesfile name and also prevented the creation of a subpage with the same name as the index page.

14 Mar 2021: version 3.08... I fixed some problems with the "bannerfile" parameter and added new "titlestyle" parameter.

15 Sep 2020: version 3.07... Changes over the last 18 months broke the ability to build a gallery from an IMAGES file that referenced images outside the current directory (e.g. "../trees.jpg" instead of just "trees.jpg"), now fixed. Plus: various minor and cosmetic changes.

10 Sep 2020: version 3.06... Adds arrow-key navigation for moving forward, backward, and upward among gallery pages (3.05 plus some improvements in 3.06).

31 Jan 2020: version 3.00... Almost a total rewrite. Works with JPG, PNG, GIF, and Animated GIF image formats, instead of only JPG as before. Also...  § Accepts various spellings of image file extensions, such as JPG, Jpg, jpg, Jpeg, etc, instead of only "jpg".  § New ability to build a totally functional gallery without ImageMagic.  § New ability to detect text-file character encodings UTF-8, ISO-8859-1, US-ASCII.  § New ability to deal with filenames that contain spaces and/or that include hyphens.

26 Nov 2019: Version 2.39... Allow definition of ATEND macro in PARAMS file; trim too-long lines in progress report.

22 Nov 2019: Version 2.38... Allow trailing comments in IMAGES file; make Validate overridable.

10 Nov 2019: Version 2.37... Ignore leading blanks in IMAGES file.

06 Nov 2019: Version 2.36... Fix margin around thumbnails.

08 Oct 2019: Version 2.35... New Supertitle directive (a phrase that goes above the title, e.g. to identify the series or topic of the page); defaults for ENLARGEBUTTON and DONTENLARGE changed to match common usage; runtime feedback highlights the sections better; "validate" link added at bottom right of main gallery page; the parameter list documentation below is greatly expanded.

18 Aug 2019: Version 2.34... Better feedback and diagnostics during execution, better handling of problematic image-file names.

25 Sep 2018: Version 2.33... New features for banners, menus, image strips across top of gallery front page (such as the one in the example just above); major scaling improvements. 

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. <a href="somegallery/img_0123.html#text">.

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, which in turn was based on a 2001 script I made for my own use but never published.

Overview

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 image files it finds in the directory: JPG, GIF, PNG... The gallery has a main page (normally index.html) with a title and thumbnails of the images, then there are subpages that have a larger (or full-size) version of each image. The normal procedure 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 desired image files into it.
  3. Run the Photogallery script, supplying at least a title for the gallery.
See an example below.

The Photogallery script always operates on its current directory. Be sure to CD to the desired directory before running the script. All the original images found in the directory are included in the gallery unless you specify otherwise. Text, captions, and special special effects can be added. All this is explained below.

Photogallery can be run repeatedly on the same gallery so you can add or remove images and/or captions.

Original, resized, and thumbnail images

Photogallery has been evolving since the early days of the Internet when network bandwidth was restricted, disk storage was scarce, and desktop computers were slow. Its "default" mode of operation (that is, how it works unless you instruct it otherwise) is tailored to that environment: So when people visit your gallery, they see a page of small thumbnails that load quickly, and when they click on a thumbnail they come to a new page with a larger version of the same image that is still (usually) much smaller than the the original image, and therefore loads much faster than the original would. This new page is called a subpage, and it includes Next ▶, Previous ◀, and Up ▲ navigation buttons so the gallery can work like a slide show. Each subpage normally also includes an Enlarge button to show the full-size original image. Subpages can also include text under the image — a simple caption or something more complex. As of Photogallery 3.05, you can also use arrow keys to move among gallery pages.

The resizing of images and creation of thumbnails is accomplished not by Photogallery itself, but by an external Open Source software package called ImageMagick, which Photogallery invokes, in particular its 'convert' program, which is included with Unix-llke platforms such as Linux, Mac OS X, BSD, etc, and can be downloaded and installed on any Unix-based OS. Photogallery does its best to find the ImageMagick utilities on your Web server but in case it fails, you can include a "convertpath" parameter to let it know their location.

The purpose of making separate thumbnail and resized versions of the original images is to reduce transmission time from Web server to desktop. And secondarily, when disk space is tight on the server, the (usually much larger) original images can be deleted after the resized ones are created. To illustrate, the table shows shows file sizes and resolutions for relatively non-compressible JPG images taken by different digital cameras when the resize width is set to 740 pixels and the thumbnail height to 160px.

Camera Year Original image Resized image Thumbnail
Canon 60D 2013 5184×3456 9608483 740×483 393775 240×160 39218
iPhone 5s 2013 3264×2448 3650512 740×555 296399 213×160 25740
Canon EOS XTi 2005 3888×2592 5171673 740×483 311918 240×160 32075
Fujifilm Finepix 1300 2001 1280×960 634535 740×555 267605 213×160 23619

You can see that that while the original JPG file size varies a lot (tends to get bigger over time), the resized and thumbnail images are all about the same size.

New for 2020... Photogallery 3.00

Twenty years hence, most Web servers have near-infinite storage capacity, networks are much faster (even if sometimes they can become congested), and your desktop computer or other device is also much faster. Therefore in many cases there might not be much advantage to having three copies of each image (original, resized, and thumbnail), so starting with Photogallery 3.00 (January 2020) your original image can be used in all contexts: as a thumbnail on the main gallery page; as a larger image in the subpage, and in its actual size, which might be much larger than your screen; in this case, the image is scaled by your browser to fit in the area specified for it by Photogallery.

To illustrate, suppose we have a gallery of 100 original photos from the Canon 60D, and that the average size of the photos is 8254719 bytes (7.87MB), which was measured on a large assortment of original photos. Using the resized-image and thumbnail sizes from the table above, and assuming no network delays, we can see the download time (in seconds) for different connection speeds with and without resizing:

  Download time (seconds)
Connection speed With resizing Without resizing
56Kbps Dialup DSL 7550.08 143950.88
1MBps Broadband 41.50 787.23
5MBps Broadband 8.25 257.44
10MBps Broadband 4.13 78.72
25MBps Broadband 1.65 31.49
50MBps Broadband 0.83 15.74
100MBps Broadband 0.41 7.87
1000MBps Broadband 0.00 0.01

The lower the connection speed, the more important it is to have resized images. As connection speeds approach 1000MBps (=1GBps) there is little difference, but Gigabyte connections are rare at this writing (2020); 25MBps is considered normal. So at present, it's still best to resize the images and create thumbnails with ImageMagick if it's available; but if not, at least now you can still make a fully functional gallery. So by default, Photogallery still resizes images and makes thumbnails if it can find ImageMagick Convert on your computer; otherwise it uses only the original images and instructs your browser to scale them appropriately.

When using ImageMagick, Photogallery takes 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 thumbnails for the main gallery page. For a large gallery, this can take some time. If you run Photogallery again, it skips these steps unless you have changed the original image or have added new images, in which case it resizes and makes new thumbnails only from the changed or new images. Of course, if you change the thumbnail height or the resize width, it will re-do all the thumbnails or subpage images.

Image types supported

Until version 3.00, Photogallery supported only JPG images, and then only if their filetype was ".jpg" (lowercase). Now it supports JPG, PNG, and GIF in any mixture and in all common spellings (JPG, Jpg, Jpeg, JPEG, GIF, Gif, Png, etc). And it also supports animated GIFs.
JPG (Jpg, jpg, JPEG, Jpeg, jpeg)
Dimensions (width×length) and "date taken" are detected by C-Kermit itself. Resizing (if desired) is done by ImageMagick.
PNG (Png, png)
Detection of width×length depends the external 'file' command. "Date taken" is not detected. Resizing (if desired) is done by ImageMagick.
GIF (Gif, gif) [not animated]
Dimensions (width×length) are detected by C-Kermit. "Date taken" is not supported. Resizing (if desired) is done by ImageMagick, but can be very slow.
GIF (Gif, gif) [animated]
Dimensions (width×length) are detected by C-Kermit. "Date taken" is not supported. Resizing can not be done. Animated GIFs used as subpage and thumbnail images are the original image scaled by your browser to the appropriate width and height.
A future release of C-Kermit might be able to parse the PNG and GIF files directly.

Text encoding

Since the 1960s the predominant computer text encoding (outside the IBM mainframe world) was ASCII, which contains the letters needed for English and a couple other languages, such as German without Umlauts. Starting about 1980 different computer companies began to devise character sets to accomodate other languages and scripts, and soon there was a proliferation of character sets, both standard and proprietary; you can see a list of some of them here. Starting about 1990 a Universal Character Set (Unicode) was introduced to take the place of the many language- and country-specific sets, with the goal of being to represent text in any language or script ever used by human beings. A version of Unicode called UTF-8 was devised for use in data communications and on the Web. Today, any given Web page might have any of these encodings but all "legacy" text is supposed to be converted to UTF-8. For now, however, most encodings are still accepted. Each web page declares its encoding so the Web browser knows how to intepret it. Some Web browsers and/or servers also "autodetect" the encoding so that sometimes a page comes out looking right even though it declared the wrong character set. But is also possible that a page looks like random gibberish if the "charset" declaration doesn't agree with the actual encoding.

Photogallery 3.00 tries to automatically detect the character encoding of any page that it creates, i.e. the main gallery pages and each of its subpages. If, however, you know the encoding (for example, UTF-8), it is best to declare it your PARAMS file:

.charset = utf-8
If you do this, Photogallery will believe you. But if the main gallery page has scrambled text, it means one or more pieces of it (e.g. index.txt, index2.txt, or copyright.txt) were not actually encoded in UTF-8, and you need to do something about it; for example, use Kermit's TRANSLATE command to convert them into UTF-8.

Gallery subpages are treated a bit differently in that if Photogallery reliably detects the encoding of an image caption, it will will declare this encoding for the resulting page even if it is different from the main page's encoding or the 'charset' definition in your PARAMS file, except that if the caption encoding is detected as 'us-ascii', Photogallery will use 'utf-8' since (a) us-ascii is a proper subset of utf-8, and (b) utf-8 is the preferred character set for all web pages.

In short, if you are creating non-English text to be included in a gallery and you don't know what its encoding is, omit the Photogallery charset parameter and Photogallery will fill it in for you and its choice will usually be correct. The ideal case is that you encode all your text as UTF-8, since that is the current standard for the Web.

Demonstration of new features in Photogallery 3.00

Live gallery created by the Photogallery 3.00; use the scrollbar to go down; click any image to see the result. (Warning: don't click the ▲, if you do then there's no way to come back to the demo page because iframes don't have a Back button.) Alternatively, you could click here to visit the same gallery directly, and then come back by clicking your browser's Back button.

IMPORTANT WARNING

The Photogallery script creates an index.html file in your current directory unless you instruct it otherwise via the 'indexfile' parameter (explained 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:

Download and Installation

The Photogallery script requires C-Kermit 9.0.304 or later* on a Unix-based operating system, and also (if you want thumbnail and resized versions of your images) that the ImageMagick 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.9.10" rather than "convert: command not found").  Download links:

Link to download... Status
[CLICK] C-Kermit 10.0* Free open-source software, next release (in development)
[CLICK] ImageMagick** Free open-source software
ImageMagick is available for Windows too, CLICK HERE to download it.
[CLICK] The Photogallery script Free open-source software [LICENSE]
Better, download the Photogallery script with Getkermiscript that also completes the installation for you.
After downloading the Photogallery script (if you did not download it with Getkermiscript), follow these steps:
* Photogallery should also work with other versions of C-Kermit back to 9.0 of 2011, but certain features will not be available: sorting by Date Taken, importing header files for your gallery, anything to with locales, etc.
** ImageMagick is required if you want to create small, quick-loading thumbnail images for the main gallery page, and reduced-size larger images for the subpages. As of Photogallery 3.00, a fully functional gallery can be built without ImageMagick, but it is likely to load more slowly.

Basic Operation

The absolute simplest way to use Photogallery is to put some digital image files (JPG, GIF, or PNG) in a new, empty directory on a Web server; cd to that directory and (assuming you have the Photogallery script installed on the same computer somewhere in your PATH as "photogallery"), type:
photogallery title="Some photos I took"

The result will be a gallery page with thumbnails of each photo, in which clicking on any thumbnail will bring you to a subpage for the image. The subpages are linked to each other and to the main gallery page, so you can go back and forth and back up just by clicking. Let's say your web account is on Panix.com, and your user ID there is "myuserid", you would see the gallery in your browser at:

http://www.panix.com/~myuserid/
Hint: "photogallery" is kind of keyboardful, so it's convenient to assign a short alias for it, such a "pg". If the program is to be used by more than one person, "pg" can be symlink. If it's only for your own use, you can put an alias in your .bashrc or other shell configuraton file. Or for that matter you can just install Photogallery as "pg".

If you don't care about captions or text or menus or customization, or dividing your gallery into sections, or ongoing maintenance of an ever-changing gallery, that's all there is to it! Otherwise, read on.

Gallery File Names

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. The table shows ".jpg" in all the image file names, but as of Photogallery 3.00, they could be ".JPG", ".GIF", ".PNG", with variations of capitalization. But note that "photo.jpg" and "Photo.Jpg" and "PHOTO.JPG" (etc) are separate and distinct image files, not different names for the same file.

Name Example Created by Description
imagename.jpg dscn1234.jpg Your camera or scanner (etc) An original image
imagename-t.jpg* dscn1234-t.jpg Photogallery + ImageMagick A thumbnail of the image
imagename-r.jpg** dscn1234-r.jpg Photogallery + ImageMagick A resized version of the image
imagename.txt dscn1234.txt You (with text editor) Text for this image's subpage
imagename.ttl dscn1234.ttl You (with text editor) Title for this image's subpage
imagename.html dscn1234.html Photogallery Gallery subpage for this image
index.html index.html Photogallery The home page of your gallery
* Only if ImageMagick is installed.
** Only if ImageMagick is installed and if 'resize' is not 0.

Order of Images

Normally, all image 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 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. But if you're mixing images from different devices or from different "folders" on the same device, all bets are off.

So to change the order in which images appear, you can:

The IMAGES File

Normally Photogallery makes a gallery of all the image files in the current directory. But you can also specify exactly which images are to be included in the gallery, and in what order, by creating a plain-text file called IMAGES (uppercase) in the directory where the images are, containing a list of the images to be included, in the desired order, one name per line. Once you have an IMAGES file you can edit it to change the order, add or remove images, or you can or comment them out by putting "" in front of their names.

You can create the IMAGES file with a text editor, or with a C-Kermit command like this one, assuming all the files are of type ".jpg", ".gif", or ".png":

directory /brief /output:IMAGES *.{jpg,gif,png}
or with a shell command:
ls -1 *.{jpg,gif,png} > IMAGES
"*.{jpg,gif,png}" is "wildcard" notation understood by both Kermit and the shell, a pattern used to select all files whose names match it. If you have image file names with other spellings like JPG, Jpeg, GIF, or PNG, include them in the pattern too. By the way, this also works with symbolic links (symlinks); only the link name appears.

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 IMAGES file.

Use an IMAGES file when you want to:

Gallery Section Titles

If you want your gallery to be divided into sections, with a title for each section like in this gallery, you can add section headings to your gallery by including [SUBTITLE] lines in your IMAGES file, like so:
[SUBTITLE]Van Cortlandt Stadium
davc00.jpg
davc05.jpg
[SUBTITLE]Van Cortlandt Park Southwest Playground
davc10.jpg
davc20.jpg
davc30.jpg
[SUBTITLE]Bronx County Courthouse
chbc100.jpg
chbc110.jpg
Section titles are available only 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.

To make it possible to link directly to a subsection of your main gallery page, you can include a tag (ID) in your [SUBTITLE] directive:

[SUBTITLE:vcstadium]Van Cortlandt Stadium
davc00.jpg
davc05.jpg
[SUBTITLE:vcswplayground]Van Cortlandt Park Southwest Playground
davc10.jpg
davc20.jpg
davc30.jpg
[SUBTITLE:bxcourthouse]Bronx County Courthouse
chbc100.jpg
chbc110.jpg
And 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
chbc100.jpg
chbc110.jpg
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.

Gallery Subpage Titles

The title normally placed on top of each subpage is the gallery title (the TITLE parameter) or, if the gallery has sections, the title of the current section. If you wish to override the title 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, highbridgeplaycenter.ttl for the image highbridgeplaycenter.jpg.

The PARAMS File

The entire process of creating and maintaining a gallery can (but need not) be controlled by a file named PARAMS (uppercase) 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

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.

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

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

Optional External Files

You can create some "helper" files that make the creation and maintainance of a gallery much easier, and the end result more useful or 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. Since photogallery so far works only on Unixlike operating systems (Linux, Mac OS X, FreeBSD, etc) you have to be careful about capitalization.

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 bannerfile file (none) index.html A heading and/or navigation menu across the top
The strip file (none) index.html An image strip across the top
The Index text file index.txt index.html Text to be included above the thumbnails on the main gallery page
The Index2 text file index2.txt index.html Text to be included below the thumbnails on the main gallery page
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
The stylesheet (none) whole gallery HTML CSS stylesheet
An icon (none) whole gallery Icon for the gallery

Optional HEAD and TAIL files

Normally Photogallery generates all the HTML code needed so that your gallery functions as a web page, but you might want your gallery to have something different on top or at the bottom. In this case, 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. 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 ../head.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 can be used to substitute the HTML prolog that Photogallery generates with another one. Just copy the HTML from a page that has the desired top matter down to the <body> line into a separate file, change title to <title>_PAGETITLE_</title>, which Photogallery will replace by the title of your own gallery, and save it in the desired place, and let Photogallery know where to find it as shown in the table above.

The bannerfile. This is kind of a lightweight Head file, in that it puts stuff at the top of the main gallery page, but it does not supply an HTML prolog. The contents of the specified bannerfile go right after the the <body> tag of the gallery's main page. Typically used if just want to have a menu on top. PARAMS file example: .bannerfile = ../menu.html.

The strip file. Similar to the bannerfile, but it puts an image strip across the top instead of inserting HTML. You have to make the image strip yourself; typically it is 80 to 180 pixels high and (say) 1600 pixels wide. Photogallery will make it fit on the display window; if it's not wide enough, it will be repeated. PARAMS file example: .strip = ../albuquerque-strip2-140.jpg.

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 supplied by Photogallery.

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.

Optional COPYRIGHT file

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 reasons of your own. The files that actually compose the gallery – the original, resized, and thumbnail images and the HTML files – are, of course, automatically protected to allow public reading. The default permission for these files is 644. You can override this on the command line or in the PARAMS file as explained just below. For an explanation of Unix file system permissions, click here.

Photogallery Parameters

You can customize your gallery by specifying parameters that alter Photogallery's default behavior. This can be done: When Photogallery 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 on the command line each time.

On the command line, parameters are given as:

name=value
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 parameters are listed in this table and explained in more detail below it:

Photogallery parameters
Parameter Value Default PARAMS file example Description
arrows 0 or 1 1 .arrows = 1 Arrows(1) or words(0) as navigation links
atend macro definition (none) see below commands to execute after gallery is built
background Color name or code white .background = "#fff0f0" Background color
bannerfile Local filename path (none) .bannerfile = ../menu.html HTML code for page header, e.g. menu
charset MIME name See this section .charset = utf-8 Character encoding of text in gallery
color Color name or code black .color = darkmagenta Foreground text color
convertpath Local filename path (none) .convertpath = /bin/convert Location of ImageMagick 'convert'
copyright Local filename path (none) .copyright = ../copyright.txt For bottom of each sub-page
dontenlarge 0 or 1 1 .dontenlarge = 0 When resizing don't enlarge
enlargebutton 0 or 1 1 .enlargebutton = 0 Display an Enlarge button
favicon Local filename path (none) .favicon = favicon.ico Shortcut icon for web browser
head Local filename path (none) .head = ../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 .indexfile = newgallery.html Name of gallery main page
language English or Spanish English .language = spanish Language for navigation
linkcolor Color name or code darkorchid .color = fuchsia Color for clickable links
maxwidth number 0 .maxwidth = 740 Maximum subpage image width (0 = none)
noarrows 0 or 1 0 .noarrows = 1 Opposite of 'arrows'
noimagemagick 0 or 1 0 .noimagemagick = 1 1=don't use ImageMagick for anything
noimagesfile 0 or 1 0 .noimagesfile = 1 1=Even if there is an IMAGES file ignore it
paramsfile local file path PARAMS .paramsfile = newparams Name for alternative PARAMS file
permissions octal number 644 .permisssions = 664 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
sort 0, 1, or 2 0 .sort = 1 Sort subpages by image 'date taken'
shorttitle text string the full title .shorttitle = "Parade" Short title for sub-pages
strip filename (none) .strip = ../clouds.jpg Image strip to insert at top of of main page
stylesheet URL (none) .stylesheet = /mygallery.css Cascading style sheet file
supertitle text string (none) .supertitle = NYC New Deal Phrase to include above main title
tail Local filename path (none) .tail = ../tail.html For bottom of index page
title text string (none) .title = "Mexican Parade" Title of the gallery
titlestyle text string border-bottom: 1px solid grey .titlestyle = border:0; color:green CSS styling for the title
uplink URL (none) .uplink = /newdeal/index.html Relative/absolute URL for main-page Up link
validate number 0 .validate = 1 Add W3C Validate link at bottom of each page

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

Parameter List

In alphabetical order:
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.
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 BANNERFILE parameter...
Use this to import any desired top matter for your gallery's main page, such as a site-specific heading and/or a menu. The value is specified as an absolute or relative pathname on the local computer. It applies only to the main page of the gallery, not to its subpages. The Bannerfile would normally consist of HTML code and data.
The CHARSET parameter...
The Internet Assigned Numbers Authority (IANA) name for the character encoding of your gallery pages such as ISO-8859-1, Windows-1252, or (preferably) the universal and now Web-standard character set UTF-8. These are also known as MIME names (Multipurpose Internet Mail Extensions). CLICK HERE or HERE for complete list of them. If you include the 'charset' parameter, then all of the text you create for your gallery's index page should be encoded in the character set that you specify (this includes index.txt, index2.txt, copyright.txt, subheading title and blurbs, custom subpage titles (*.ttl), and any 'head' or 'tail' files (explained below). For the subpages, the imagename.txt files can be in any of the character sets from the table in THIS PAGE, but for sanity and ease of maintence, it's best to use the same encoding as the main page, for which UTF-8 is recommended as the World Wide Web is threatening to retire all the older "legacy" character sets. If you omit the 'charset' parameter, Photogallery will treat the sub-pages the same way, but the index page's encoding will be guessed from index.txt or index2.txt file, whichever is found first. Example:

.charset = utf-8

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 (see hover).
The CONVERTPATH parameter...
Specifies the pathname of the ImageMagick 'convert' utility in case it's not in your PATH and Photogallery can't find it.
The COPYRIGHT parameter...
Specifies a file with text to include at the bottom of each subpage page, such as a copyright notice. If the Copyright file contains the string _YEAR_, it is replaced by the current year.
The DONTENLARGE parameter...
Images are normally scaled to fit into the viewport. But if an image is significantly smaller than the viewport, scaling it to be bigger would make it blurry. The 'dontenlarge' parameter says to display the image in its own size. Thus, large originals are reduced but small ones are left alone. Since this behavior is almost always desirable, it is the default.
The ENLARGEBUTTON parameter...
This causes Photogallery to include an Enlarge button on the navigation bar of each sub-page, which, when clicked, displays the original image in full size.
The FAVICON parameter...
If you have an icon you would like to be shown by the browser for your gallery, use this parameter to identify it by its full URL or by a relative pathname (for example, if the icon image is in your gallery directory, just put its filename). Once upon a time, icon files had to be in a special format, but now they can be regular JPGs, GIFs, or whatever. They should (but need not be) relatively small.
The HEAD parameter...
Normally Photogally writes all the website HTML itself. But you can also tell it to import an HTML heading that has its own <head> section and top matter for the body, for example a standard banner and menu that appears on all the site's web pages. The HEAD file is expressed as a full local pathname, or as a path relative to the current directory. If the head file is not in your gallery directory, all of the links in it should be relative to the website's root directory. Read more about this topic HERE. The head file should include at least "<!DOCTYPE>", "<head>", "</head>", and "<body>" HTML tags. And its character encoding should agree with your other index files. If you put "<title>_PAGETITLE_</title>" in your head file, the string _TITLE_ will be replaced by the title of your gallery.
The HEIGHT parameter...
applies to the thumbnails generated for the index page; it tells how many pixels high each thumbnail should be; specify a number only, e.g. 140, not 140px.
The HELP parameter...
is not exactly a parameter, it tells Photogallery to print a list of its command-line options. It also does this if you run it with no arguments and there is no PARAMS file.
The HOVER parameter...
Color to use for URLs when mouse cursor is on them. If not specified, Photogallery chooses a brighter color automatically (in most cases).
The IMAGESFILE parameter...
Normally Photogallery builds a gallery of all the JPG images it finds in the current directly. But you can also 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 for any text to display on the gallery's front page, rather than automatically looking for index.txt; e.g. bronx.txt.
The LINKCOLOR parameter...
The default color for text links in HTML pages is blue. You can use this parameter to change it to any color you like; see this page for a list of choices.
The LANGUAGE parameter...
tells whether text generated by Photogallery (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 using HTML entities like "&eacute;" and "&ntilde;" so it should not matter what character encoding you have chosen for your gallery: ISO-8859-1, Windows-1252, UTF-8, or any other. If you specify language=spanish and you have an external HEAD file, it should include the following in it:
<html lang="es">
...
<META http-equiv="Content-Type" content="text/html; charset="utf-8">
(or ISO-8859-1 or whatever other encoding you are using).
The MAXWIDTH parameter
The maximum width, in pixels, when scaling a subfile image; e.g. '.maxwidth = 800" in the PARAMS file (just put the number). MAXWIDTH also applies to the text on the main gallery page. In the subpages, the images will often be less than MAXWIDTH pixels, because they are scaled to fit with width of the browser's viewport, and also vertically so you can see at least the beginning of the figure caption (if there is one). The caption itself is scaled to the same width as the image.
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. To have Photogallery use a PARAMS file who name isn't "PARAMS", you must tell Photogallery its name by including the 'paramsfile=xxx" option on the command line.
The PERMISSIONS parameter...
lets you specify the permissions for the image and HTML files that comprise the gallery. The default permission is 644, meaning the owner can read and write the files, others can only read them. You can change this to 664 if you 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. People visiting your galler can click this button to "Pin" the image to any of their 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).
The RESIZE parameter...
The RESIZE parameter tells whether to make smaller copies of the original images to be viewed in the gallery's subpages. As explained at the beginning of this document, the only reason for this is to save disk space and/or transmission time. RESIZE=0 means don't resize them; that is, put the original images in your subpages and let your browser scale them. RESIZE=800 means to create a new version of each image file that is 800 pixels wide (note: don't include "px" in the resize value). If you resize your images, it's not destructive; the original image is still there. If the original image name was "twilight.gif", the resized version is "twilight-r.gif": the "-r" suffix indicates a resized image. 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 SHORTTITLE parameter...
specifies the title to be used for sub-pages. If no SHORTTITLE is specified, the title is used.
The STRIP parameter...
Lets you put an image strip across the top of the page, such as a horizontal mini-gallery 100 pixels high and (say) 1920 pixels wide, like the one on this page. If you have also specified a BANNERFILE, the strip goes immediately under it.
The STYLESHEET parameter...
This lets you load a CSS stylesheet, provided you are not also including a HEAD file. The value is a URI relative to the root directory of the website, because it is used as a URL in the <head> of the generated HTML result.
The SORT parameter...
lets you tell Photogallery 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 image file before saving it.
  • Sorting by Date Taken works as expected only if all the cameras or scanners that created the JPG images had their date-time clocks set to agree.
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 images from a device whose naming sequence wrapped around.
The SUPERTITLE parameter...
Lets you put a short and relatively small text line above the main title. For example, if you have lots of different pages on NYC New Deal sites, you could give them all a supertitle of "New York City New Deal..." and then the title could be just the name of the site, like "Bryant Park" ← (Click to see how it looks):
.supertitle = New York City New Deal...
.title = Bryant Park
The order doesn't matter.
The TAIL parameter...
Tells Photogallery to import your gallery main page's end matter from an external file, which is expressed as a full local pathname, or a path relative to the current directory. The tail file should include at least the "</body>" and "</html>" tags. If you put "<title>_PAGEDATE_</title>" in your tail file, the string  _PAGEDATE_ will be replaced by the date on which the gallery was built.
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 TITLESTYLE parameter...
lets you customize the appearance of the title on the gallery's front page. The value is one or more CSS expressions, such as "font-family:times" or "font-size:120%; font-variant:small-caps".
The UPLINK parameter...
This applies only to the main (home, index) page of your gallery. It 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 to the index.html file of the website's root directory.
The VALIDATE parameter...
If you want to be able to run your gallery pages through the W3C HTML validator, you can set .validate = 1, and this will put a Validate link at the bottom of each page that sends it to HTML checker at validator.w3.org, of use mainly to the gallery creator (or the Photogallery author) while you're working on the gallery; normally you'd set .validate = 0 when the gallery is ready for public viewing.

Macro execution

In Photogallery 3.00 and later, you can define a macro named ATEND ("at end") in your PARAMS file to do anything you want done after the gallery is fully built. Like any other C-Kermit macro, the ATEND macro can contain any C-Kermit commands, or it can access operating system commands with RUN, !, or \fcommand(). It can also refer to any variables that are defined in the PARAMS file or, for that matter, in the Photogallery script itself. Here's an example from the top of a PARAMS file, that uses C-Kermit's CHANGE command to make some changes to the gallery's main page (index.html in this case):
define ATEND {
  change /list index.html _UPDATED_ \v(timestamp) # C-Kermit builtin variable
  change /list index.html _IMAGES_ \m(subpages)   # Photogallery variable
  change /list index.html _SITES_ \fcommand(grep -c countme IMAGES) # External command
}
It changes the gallery's main page to report the number of images in the gallery (the \m(subpages) variable), the date and time the gallery was built, and (in this case) the number of distinct "projects" represented in the gallery, which are indicated by comments containing the word "countme" in the IMAGES file; for example:
[SUBTITLE:bridges]Bridges, highways, and tunnels
triboroughbridge.jpg # countme
triborough10.jpg
triborough4.jpg
whitestone.jpg # countme
whitestone01.jpg
henryhudsonparkway.jpg # countme
henryhudsonbridge1937.jpg
henryhudsonbridge.jpg
You can see the resulting gallery HERE; the filled-in numbers are just below the title.

Making Changes to a Gallery

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 Photogallery again by typing its name (e.g. photogallery or pg); you don't need to enter the parameters on the command line any more. 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 if you have an IMAGES file, add the filename of the new image to it in the desired place. Then run the Photogallery script again.
Removing images
To remove an image from the gallery: If you have an IMAGES file, simply remove (or comment out) the file's name. If you don't have an IMAGES file, delete (or move) all the files that start with the image's name. Example (Unix shell):
cd machupicchu
mv dscn3742*.* save/
Then run Photogallery again to rebuild the gallery.
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; you can use C-Kermit's RENAME /REPLACE command for this (read about it); for example:
rename /list /replace:{{abc}{xyz}} abc*.*
If the gallery is driven by an IMAGES file, the name of the image should be changed in that file too (a simple Kermit script for doing all of this at once would require only a RENAME /REPLACE command and a CHANGE command for the IMAGES file).
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 the gallery will have the updated version of the image and thumbnail. If you don't see it, you might have to Shift-Reload your browser and/or clear its cache.
Changing the order of images
If you are already using an IMAGES file, just edit it as desired. If not, you can create one with the following shell command while cd'd to the gallery directory:
ls -1 *.jpg | egrep -v "(-[rt].)" > IMAGES
(That's ls-dash-one, not ls-dash-letter-l.) ("ls" is letter L and letter S but lowercase.) Then edit or sort the new IMAGES file to put the files in the desired order and re-run Photogallery. Well, it's a bit more complicated in Photogallery 3.00 if you have images whose names don't end with .jpg, but this would cover all the possibilities:
ls -1 *.{jpg,gif,png,Jpg,Gif,Png,JPG,GIF,PNG,jpeg,Jpeg,JPEG} | \
egrep -v "(-[rt].)" > IMAGES
(it's one command, the '\' is the shell's line continuation character). You could do it in Kermit too:
dir /except:*-[rt].* /output:IMAGES -
*.{jpg,gif,png,Jpg,Gif,Png,JPG,GIF,PNG,jpeg,Jpeg,JPEG}
Adding or changing captions
Create or edit a file that has the same name as the desired image file, but ending with ".txt" instead of ".jpg", or ".gif", etc (for example the caption file for "dscn4321.jpg" would be "dscn4321.txt". Then run Photogallery again. You don't have to run it again after each change; you can change a series of files and then run it once when you're finished. If you see a mistake in a sub-page caption, edit the caption file (imagename.txt) and run Photogallery again. Caption files contain regular plain text but you can also put HTML tags like <b>THISISBOLD</b>, links, or anything else you want, even other images, but bear in mind that they won't be resized because Photogallery doesn't know a thing about them, it is just copying your .txt file into the subpage, "dscn4321.html" in this case.
Adding or changing text on the main gallery page.
Create or edit a plain-text file named "index.txt" in the gallery directory, then run Photogallery 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. The index.txt contents go above the thumbnails. If you create an index2.txt file, its contents go below the thumbnails.
Changing Photogallery parameters
If you want to change any of the parameters (for example, the size of the thumbnails, the colors, whether to resize images) edit the PARAMS file and run Photogallery again.

A simple images-only gallery

To make a very simple photo gallery like this one, with no text or captions or special effects, you don't need anything but the photos. Create a directory in your top-level website directory, give it the appropriate permissions, copy your photos into it, cd to it, and run Photogallery. Here's an example in which you upload the images with Kermit from your desktop computer (Windows or Linux with Kermit installed):
cd public_html Change to top-level directory of website
mkdir bronxphotos Create a subdirectory called "bronxphotos"
chmod 755 bronxphotos     Set the permissions
cd bronxphotos
Change to the bronxphotos subdirectory
kermit -g *.jpg Upload the images
and type (for example):
photogallery title="Bronx photos"
Actually I cheated and typed:
photogallery title="Bronx photos" height=72
so the thumbnails would be smaller. Here's the result:
(Don't click the ▲, if you do then there's no way to come back to the demo page because iframes don't have a Back button.) You can avoid any confusion by visiting the gallery directly and then using its up ▲ button or your browser's Back button to come back here. Either way, web pages inside of web pages can be a little confusing.

While working, Photogallery prints its progress messages and then at the end a summary so you can see what it did:

SUMMARY 31-Jan-2020 14:54:02... Interpreter: C-Kermit version 900304 Dev.23
Supported graphics file extensions:
jpg gif png Jpg Gif Png JPG GIF PNG jpeg Jpeg JPEG
This directory: /kermitproject/pg300/demo2/
Title: Bronx photos
Index file name: index.html
Character encoding not declared
Parameters set from command line: 2
Included 20 images from /kermitproject/pg300/demo2/
ImageMagick Convert was found at /usr/local/bin/convert
Resize width: 740 pixels
Used ImageMagick 'convert' to resize 20 subpage images
Thumbnail height: 72 pixels
Used ImageMagick 'convert' to create or update 20 thumbnails
Images in gallery: 20

Galleries with text

The next step up is to add text to your gallery. Use a plain text editor to create xxx.txt files to supply the text for different elements of the gallery: See the External Gallery Components table for a complete list of possibilities. These text files, by the way, are not restricted to plain text. They can include any kind of HTML markup and/or embedded images as in this example.

Galleries with PARAMS file

Once you start adding text, you'll be building the gallery over and over and you don't want to have to type:
photogallery title="Bronx photos" height=72
over and over. So make a PARAMS file containing:
.title = Bronx photos
.height = 72
and you just have to type "photogallery" to rebuild the same gallery. Or "pg" if you install it under that name. You can put other parameters in here too, see the "Parameters" section.

Multiple galleries in the same directory

For this you need to have a PARAMS file and an IMAGES file for each gallery. But since you can't have multiple files in the same directory with the same name, you'll need to give unique names to each one. For example: PARAMS1, IMAGES1; PARAMS2, IMAGES2, etc. And the main page of each gallery will also need a unique name. So the PARAMS2 file might contain something like this:
.imagesfile = IMAGES2
.indexfile = gallery2
And then to build this gallery the command would be:
photogallery paramsfile=PARAMS2
This naming convention is arbitrary, you can call these files anything you want, but this way it's easy to see what galleries you have with:
ls -l PARAMS*
Meanwhile, to guard against clobbering your website's home page, you should create a PARAMS file that contains:
echo This directory has multiple galleries.
echo Please use:
echo
echo "  photogallery paramsfile=PARAMS2"
echo
echo to build the desired gallery, substituting 
echo the desired PARAMS file name.
exit

Big galleries with many features

Look through the Parameters section to see other options that can be used to customize your gallery. If you are proficient in HTML, you can even create your own stylesheets. You can see numerous production gallery examples in my New York City New Deal site. Some examples: and (not New Deal): Whenever you see some effect that interests you, you can "View Source" (Ctrl-U in most browsers) to see how it's done. You can also see the IMAGES and PARAMS files by typing their names into your browser's address bar.

C-Kermit Photogallery script / The Kermit Project / kermit@kermitproject.org / August 2013 - January 2023