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:
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:
Create a new directory and give it the desired access permissions.
CD to the new directory and upload or otherwise move the desired
image files into it.
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
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:
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
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:
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
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 ImageMagickconvert
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:
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:
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
*
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:
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
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:
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
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.
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:
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.
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:
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 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
"é" and
"ñ" 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:
(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:
The Pinterest button is done Javascript. This has two implications:
Visitors to your website will see the button only if they have
Javascript enabled.
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):
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:
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:
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.
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:
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.