/ 
khatgallery-0.2405
River stage zero No dependents
/ khatgallery

NAME

khatgallery - generate a HTML photo-gallery.

VERSION

version 0.2405

SYNOPSIS

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

khatgallery --clean directory

khatgallery [ --captions_file filename ] [ --debug_level num | --debug ] [ --dir_match string ] [ --force_html ] [ --force_images ] [ --image_match string ] [ --options filename ] [ --page_template filename ] [ --per_page num ] { --plugins PluginName } { --plugopt name=value } { --meta string } [ --thumbdir string ] [ --thumb_geom numxnum ] [ --top_out_dir directory ] [ --top_url url ] directory

DESCRIPTION

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.

OPTIONS

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)

--clean

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_html

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_images

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.

--help

Print help message and exit.

--image_match string

Regular expression determining what filenames should be interpreted as images.

--manpage

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"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title><!--kg_title--></title>
<!--kg_style-->
</head>
<body>
<!--kg_content-->
</body>
</html>

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.

--plugopt name=value

Additional options to pass to 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)

--top_out_dir directory

The directory to create galleries in; HTML and thumbnails will be created there. If this is not given, it is the same as the images directory.

--top_url URL

The URL of the top images directory; if the top_out_dir isn't the same as the images directory, then we need to know this in order to link to the images in the images directory.

--verbose

Print informational messages.

--version

Print version information and exit.

FILE FORMATS

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

SCRIPT CATEGORIES

Web

ENVIRONMENT

HOME

khatgallery looks in the HOME directory for config files.

FILES

~/.khatgalleryrc

User configuration file.

.khatgalleryrc

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

REQUIRES

Getopt::Long
Pod::Usage
Getopt::ArgvFile
HTML::KhatGallery;

SEE ALSO

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

BUGS

Please report any bugs or feature requests to the author.

AUTHOR

Kathryn Andersen (RUBYKAT)
perlkat AT katspace dot com
http://www.katspace.org/tools

COPYRIGHT AND LICENCE

Copyright (c) 2006 by Kathryn Andersen

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.