view release on metacpan or  search on metacpan

lib/Album/Tutorial.pm  view on Meta::CPAN

package Album::Tutorial;

# NOTE: This is a documentation-only module.

use strict;

our $VERSION = "1.901.0";

=pod

=head1 NAME

Album::Tutorial - How to use the Album program

=head1 SYNOPSIS

This tutorial describes the basic use of the Album program to create
and maintain browser based photo albums.

=head1 DESCRIPTION

=head2 Getting started

To get started, create a new directory and cd to it. Create a
subdirectory 'large' and put some pictures there. If you have
installed the 'album' tool in your execution path, you can now execute
it as follows:

  $ album -v
  No info.dat, adding images from large
  info.dat: Cannot update (does not exist)
  Number of entries = 7 (7 added)
  mkdir index
  mkdir icons
  Creating icons: first-gr.png first.png ... sound.png movie.jpg
  im023.jpg: thumbnail OK
  im024.jpg: thumbnail OK
  im025.jpg: thumbnail OK
  im026.jpg: thumbnail OK
  im027.jpg: thumbnail OK
  im028.jpg: thumbnail OK
  im029.jpg: thumbnail OK
  Creating pages for 7 images
  (Needed to write 7 image pages)
  Creating pages for 1 index
  (Needed to write 1 index page)

Your results will vary, but be similar to this example run. What you
can see is that 'album' found 7 images in the 'large' directory,
created index and icons directories, created thumbnails by
resizing the images, and finally created the HTML pages. You can
inspect your first photo album by opening file 'index/index001.html' with your
favorite browser. You can click on any image to see the larger
version. Navigation buttons are provided to the left of the image. You
can also navigate from the keyboard: space (next), backspace
(previous), enter (larger image), and 'd' (index).

It is interesting to run 'album' again:

  $ album -v
  No info.dat, adding images from large
  info.dat: Cannot update (does not exist)
  Number of entries = 7 (7 added)
  .......[7]
  Creating pages for 7 images
  (No image pages needed updating)
  Creating pages for 1 index
  (No index pages needed updating)

'album' tries to avoid doing unnecessary work as much as possible. In
this case, all thumbnails and image and index pages are up to date.
The line of periods shows progress, one period for each image
processed.

=head2 Protecting your work

'album' not only tries to avoid doing unnecessary work, but it is also
very careful to not destroy your original images, nor any other
changes you may have made.

In general, 'album' will I<never> overwrite or modify:

=over 4

=item *

anything in the import directories (see below);

=item *

any images in the 'large' directory (which is considered 'original work');

=item *

any images in the 'medium' and 'index' directories (but see

lib/Album/Tutorial.pm  view on Meta::CPAN

same.

Older versions of 'album' always created external style sheets. As a
consequence, if you upgrade to the newer version, you'll get a fatal
error the first time you run 'album'.

 *************************************************************************
 Existing style sheet ... is not compatible with this version.
 It has probably been created by an older version of this program, or it
 has been modified manually.

 If you did not change any style sheets, just remove the css directory and
 try again.

 If you did modify the style sheets move them away to a backup location,
 run the program with '--extcss', and apply your changes to the new style
 sheets.
 *************************************************************************

We apologise for the inconvenience.

=head2 Keyboard navigation

While browsing the album, some actions can be performed from the keyboard.

The C<Enter> key will go to an enlarged version of the image, if available.

The C<Space> key will advance to the next page.

The C<Backspace> key will advance to the previous page.

Key C<d> will go to the index page.

Key C<u> will go up, i.e., the reverse of the C<Enter> key.

Key C<j> will go to the journal entry of the current image.

=head2 Additional notes

The B<--clobber> command line option will force regeneration of all
medium and thumbnail images, and HTML pages. It will not force
re-import of the 'large' images. To completely rebuild everything
save info.dat, remove all the files in the album directory (including
.cache), restore info.dat and re-run the 'album' program.

The digital camera import is designed for cameras that adhere to the
ISO DCF standard. Handling of MPG movies and voice images is probably
specific for my Sony DSC-V1.

When importing images from different camera's, there's an extremely
small chance that the EXIF information would lead to identical file
names. This can only happen if the pictures were taken at the exact
same time (according to the camera's notion of time!), and have the
same internal sequence number.

When parsing C<info.dat>, Album treats anything up to a known file
name extension to be part of the file name. In general, this means
that you can safely enter file names with whitespace and other
uglyness.

Known file name extensions are C<jpg>, C<jpeg>, C<png>, and C<gif> for
images, C<mpg>, C<mpeg>, C<mov>, and C<avi> for movies, and C<html>
and C<htm> for links.

=head1 AUTHOR AND CREDITS

Johan Vromans (jvromans@squirrel.nl) wrote this module.

=head1 COPYRIGHT AND DISCLAIMER

This program is Copyright 2004,2007 by Squirrel Consultancy. All
rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of either: a) the GNU General Public License as
published by the Free Software Foundation; either version 1, or (at
your option) any later version, or b) the "Artistic License" which
comes with Perl.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
GNU General Public License or the Artistic License for more details.

=cut

1;

# $Id: Tutorial.pm,v 1.12 2007/05/31 21:01:34 jv Exp $