#!/usr/bin/env perl # vim:ts=8 sw=4 sts=4 ai require v5.8.5; use strict; use warnings; =head1 NAME khatgallery - generate a HTML photo-gallery. =head1 VERSION This describes version B<0.03> of khatgallery. =cut our $VERSION = '0.03'; =head1 SYNOPSIS khatgallery --help | --manpage | --version khatgallery --clean I khatgallery [ --captions_file I ] [ --debug_level I ] [ --dir_match I ] [ --force_html ] [ --force_images ] [ --image_match I ] [ --options I ] [ --page_template I ] [ --per_page I ] { --plugins I } { --meta I } [ --thumbdir I ] [ --thumb_geom IxI ] I =head1 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. =head1 OPTIONS =head2 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 L for more information. =over =item --captions_file I The name of the captions file; which is in the same directory as the images which it describes. This file is in L 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) =item --clean Instead of generating files, clean up the thumbnail directories to remove thumbnails and image HTML pages for images which are no longer there. =item --debug_level I Set the level of debugging output. The higher the level, the more verbose. (developer only) (default: 0) =item --dir_match I Regular expression to match the directories we are interested in. Hidden directories and the thumbnail directory will never be included. =item --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. =item --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. =item --help Print help message and exit. =item --image_match I Regular expression determining what filenames should be interpreted as images. =item --manpage Print the full help documentation (manual page) and exit. This requires perldoc to be installed. =item --meta I 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. =item --page_template I Template for HTML pages. The default template is this:  This can be a string or a filename. =item --options I 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 L for more information. =item --per_page I The number of images to display per index page. =item --plugins I Give a KhatGallery plugin to use. This option can be repeated for additional plugins. =item --thumbdir I 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) =item --thumb_geom IxI 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) =item --verbose Print informational messages. =item --version Print version information and exit. =back =head1 FILE FORMATS =head2 Options Files Options can be given in files as well as on the command-line by using the --options I 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 (I 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 I argument inside the option file, it will go and get that referred file as well. See L for more information. =head2 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 L 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: |

These are the fabulous images created by Yours Truly.

image1.png: this is the caption for image1.png =head1 SCRIPT CATEGORIES Web =head1 ENVIRONMENT =over 4 =item HOME khatgallery looks in the HOME directory for config files. =back =head1 FILES =over 4 =item C<~/.khatgalleryrc> User configuration file. =item C<.khatgalleryrc> Configuration file in the current working directory; overrides options in C<~/.khatgalleryrc> and is overridden by command-line options. =back =head1 REQUIRES Getopt::Long Pod::Usage Getopt::ArgvFile HTML::KhatGallery; =head1 SEE ALSO perl(1) Getopt::Long Getopt::ArgvFile Pod::Usage =cut use Getopt::Long 2.34; use Getopt::ArgvFile qw(argvFile); use Pod::Usage; #======================================================== # Subroutines sub init_data ($) { my $data_ref = shift; $data_ref->{manpage} = 0; $data_ref->{verbose} = 1; } # init_data sub process_args ($) { my $data_ref = shift; my $ok = 1; argvFile(home=>1,current=>1, fileOption=>'options', startupFilename=>'.khatgalleryrc'); pod2usage(2) unless @ARGV; my $op = new Getopt::Long::Parser; $op->configure(qw(auto_version auto_help)); $op->getoptions($data_ref, 'verbose!', 'manpage', 'clean', 'plugins=s@', 'per_page=i', 'thumbdir=s', 'thumb_geom=s', 'page_template|template=s', 'force_html!', 'force_images!', 'meta=s@', 'debug_level=i', 'dir_actions=s@', 'clean_actions=s@', 'image_actions=s@', ) or pod2usage(2); if ($data_ref->{'manpage'}) { pod2usage({ -message => "$0 version $VERSION", -exitval => 0, -verbose => 2, }); } # top_dir is $ARGV[0] $data_ref->{top_dir} = shift @ARGV; } # process_args #======================================================== # Main MAIN: { my %data = (); init_data(\%data); process_args(\%data); my $libdir = $data{libdir}; delete $data{libdir}; eval "use lib '$libdir'" if $libdir; die "invalid libdir $libdir: $@" if $@; my $class='HTML::KhatGallery'; eval "require $class;"; die "invalid starter class $class: $@" if $@; my @plugins = qw(HTML::KhatGallery::Core); push @plugins, @{$data{plugins}} if ($data{plugins}); warn "plugins=", join("\n", @plugins), "\n" if $data{debug_level}; delete $data{plugins}; $class->import(@plugins); $class->run(%data); } =head1 BUGS Please report any bugs or feature requests to the author. =head1 AUTHOR Kathryn Andersen (RUBYKAT) perlkat AT katspace dot com http://www.katspace.org/tools =head1 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. =cut __END__