The Photogallery script

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.

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:

Overview

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.

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

• It resizes your original images for Web browsers
• It creates a thumbnail of each image for the main (index) page
• It creates the HTML index page showing the thumbnails
• It creates an HTML sub-page for each image
• It creates links for navigating among the pages and sub-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.

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

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:

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

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.

Text 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

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

• Photogallery checks for a robots.txt file in the current directory and refuses to run if one is found (because robots.txt files are intended for use only in the top-level directory of a website), but that's not foolproof because not every home directory has one, and a file called robots.txt might be found in some other directory. If you actually want the index.html created by this script to be the home page of the website and a robots.txt file is getting in the way, run this script like this:

  IGNORE_ROBOTS=1 photogallery  [args...]

• Also, index.html files created by Photogallery contain the identification string PHOTOGALLERYINDEX. If you run the Photogallery script in a directory that has an index.html file that contains this string, Photogallery assumes it's updating an existing gallery and proceeds with its work. If you run it in a directory that has no index.html, the script knows it's creating a new gallery. However, if an index.html exists but does not contain the ID string, the script prints a warning and exits.

Download and Installation

• Move it to a directory that is in your PATH.
• Give it execute permission (chmod +x).
• In a plain-text editor, change the top line to show the full path of the C-Kermit executable, preceded by "#!" (explained here) and followed by a space and plus sign (explained here); for example:

  #!/usr/local/bin/kermit +

• Give it execute permission, e.g.:

  chmod 755 photogallery

Basic Operation

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/

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

Order of Images

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

• Rename the image files; or:
• Or you can tell Photogallery to sort the images according to their internal Date Taken information, explained below (the sort parameter). This is useful if you are mixing images produced by different cameras or devices, or when the images have been renamed, or for any other situation where "alphabetical" order of image file names does not correspond to chronological order.
• Create a file named IMAGES in the same directory as the images, containing the image filenames in the desired order.

The IMAGES File

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}

ls -1 *.{jpg,gif,png} > IMAGES

If you want to reorder the images after you have already created a gallery (in which case there are likely to be a bunch of resized images with names like img_2199.jpg, img_2199-r.jpg, and img_2199-t.jpg), use a command like this (assuming all the images are JPGs):

ls -1 img_????.jpg > IMAGES

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:

• Arrange the images in an order other than alphabetical or chronological; or:
• Include images from any directory other than the current directory; or:
• Exclude some of the images that are in the current directory, or:
• Include section titles in the main gallery page.

Gallery Section Titles

[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

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

[SUBTITLE:bxcourthouse:bxcourthouse.txt]Bronx County Courthouse
chbc100.jpg
chbc110.jpg

Gallery Subpage Titles

The PARAMS File

# 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

.background =

.background = "#fff0f0"

Optional External Files

Optional HEAD and TAIL files

(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 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

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

File permissions

Photogallery Parameters

• On the command line; or:
• In a file called PARAMS in the same directory as the images; or:
• In some other file that you identify on the command line.

On the command line, parameters are given as:

name=value

name="value with spaces"

In the PARAMS file, the syntax is slightly different:

.name = value

.title = Vacuum Tube Computers
.title = "Vacuum Tube Computers"

Example using command line:

photogallery title="New Models for Fall 2013" color=gold background=black

.title = "New Models for Fall 2013"
.color = gold
.background = black

Parameter List

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

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
}

[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

Making Changes to a Gallery

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

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

photogallery title="Bronx photos"

photogallery title="Bronx photos" height=72

(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

• index.txt for text to go on the main page above the thumbnails.
• index2.txt for text on the main page under the thumbnails.
• imagename.txt for text to go under the image on a subpage; for example, if the image name is starrynight.jpg (or .gif, etc), its "caption" file would be starrynight.txt. If you want to put captions on all the images, you'll need to make a .txt file for each one.

Galleries with PARAMS file

photogallery title="Bronx photos" height=72

.title = Bronx photos
.height = 72

Multiple galleries in the same directory

.imagesfile = IMAGES2
.indexfile = gallery2

photogallery paramsfile=PARAMS2

ls -l PARAMS*

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

• Aymar Embury II Gallery of NYC New Deal Projects
• Highbridge Park, Pool, and Play Center
• Brooklyn Navy Yard
• The New Deal site's style sheet

• Bronx Day Parade 2015 (with links to other years)