khatgallery - generate a HTML photo-gallery.


This describes version 0.03 of khatgallery.


khatgallery --help | --manpage | --version

khatgallery --clean directory

khatgallery [ --captions_file filename ] [ --debug_level num ] [ --dir_match string ] [ --force_html ] [ --force_images ] [ --image_match string ] [ --options filename ] [ --page_template filename ] [ --per_page num ] { --plugins PluginName } { --meta string } [ --thumbdir string ] [ --thumb_geom numxnum ] directory


The khatgallery script generates a HTML photo gallery. It takes a directory of images, and generates the HTML pages and thumbnails needed.

Place your photos in a new directory somewhere on your web site. Then run "khatgallery" from the command-line with the directory path as an argument, and there you have it.

The options can be used to fine-tune and customize your gallery.


A Note about Options

Options can start with "--" or "-"; boolean options can be negated by preceding them with "no"; options with hash or array values can be added to by giving the option again for each value.

See Getopt::Long for more information.

--captions_file filename

The name of the captions file; which is in the same directory as the images which it describes. This file is in YAML format. For example:

    index.html: this is the caption for the album as a whole
    image1.png: this is the caption for image1.png
    image2.jpg: I like the second image

(default: captions.yml)


Instead of generating files, clean up the thumbnail directories to remove thumbnails and image HTML pages for images which are no longer there.

--debug_level num

Set the level of debugging output. The higher the level, the more verbose. (developer only) (default: 0)

--dir_match string

Regular expression to match the directories we are interested in. Hidden directories and the thumbnail directory will never be included.


Force the re-generation of all the HTML files even if they already exist. If false (the default) then a given HTML file will only be created if there is a change in that particular directory.


Force the re-generation of the thumbnail images even if they already exist. If false (the default) then a given (thumbnail) image file will only be created if it doesn't already exist.


Print help message and exit.

--image_match string

Regular expression determining what filenames should be interpreted as images.


Print the full help documentation (manual page) and exit. This requires perldoc to be installed.

--meta string

This defines what meta-data to show for an image and how to format it. The field to show is surrounded by % characters. For example:

    --meta 'Date: %DateTime%'

To show more than one field of meta-data, just give the option again.

    --meta 'Date: %DateTime%' --meta '%Comment%'

If an image doesn't have that particular field, the data for that field is not shown. All the meta-data is placed after any caption the image has.

--page_template filename

Template for HTML pages. The default template is this:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    <html xmlns="">

This can be a string or a filename.

--options filename

The name of a file to read more options from. This can be used more than once. For example:

--options your.args --options my.args

See Options Files for more information.

--per_page num

The number of images to display per index page.

--plugins PluginName

Give a KhatGallery plugin to use. This option can be repeated for additional plugins.

--thumbdir string

The name of the directory where thumbnails and image-pages are put. It is a subdirectory below the directory where its images are. (default: tn)

--thumb_geom numxnum

The size of the thumbnails. This doesn't actually define the dimensions of the thumbnails, but their area. This gives better-quality thumbnails. (default:100x100)


Print informational messages.


Print version information and exit.


Options Files

Options can be given in files as well as on the command-line by using the --options filename option in the command-line. Also, the files ~/.khatgalleryrc and ./.khatgalleryrc are checked for options.

The format is as follows: Lines starting with # are comments. Lines enclosed in PoD markers are also comments. Blank lines are ignored. The options themselves should be given the way they would be on the command line, that is, the option name (including the --) followed by its value (if any).

For example:

    # set meta names
    --meta 'Date: %DateTime%'
    --meta %Comment%

Option files can be nested, by giving an --options filename argument inside the option file, it will go and get that referred file as well.

See Getopt::ArgvFile for more information.

Captions Files

A captions file contains captions to describe the images and the album (directory or sub-directory) in which the file is. The default name of this file is 'captions.yml'.

This file is in YAML format. The contents are interpreted as follows: if an entry is called 'index.html', then that will contain the description of the album. If an entry matches the name of an image in that directory, then its value will be used as the caption for that image. If an entry doesn't match anything, it will be ignored.

For example:

    index.html: this is the caption for the album as a whole
    image1.png: this is the caption for image1.png
    image2.jpg: I like the second image

(Note that the leading '---' is required, this is part of YAML format.)

HTML tags can be included in the captions, but care needs to be taken with them (and with quotes) to make sure that they conform to YAML syntax.

Another example:

    index.html: |
       <p>These are the <i>fabulous</i> images created by Yours Truly.</p>
    image1.png: this is the caption for image1.png





khatgallery looks in the HOME directory for config files.



User configuration file.


Configuration file in the current working directory; overrides options in ~/.khatgalleryrc and is overridden by command-line options.




perl(1) Getopt::Long Getopt::ArgvFile Pod::Usage


Please report any bugs or feature requests to the author.


    Kathryn Andersen (RUBYKAT)
    perlkat AT katspace dot com