view release on metacpan or  search on metacpan

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

package Album::Tutorial;

( $VERSION ) = '$Revision: 1.10 $ ' =~ /\$Revision:\s+([^\s]+)/;

# NOTE: This is a documentation-only module.

use strict;

=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 thumbnails
  mkdir icons
  mkdir css
  Creating icons: first-gr.png first.png ... sound.png movie.jpg
  Creating style sheets: common.css index.css ... journal.css
  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 thumbnails, icons and css directories, created thumbnails by
resizing the images, and finally created the HTML pages. You can
inspect your first photo album by opening file 'index.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.

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 'thumbnails' directories (but see
B<--clobber> below);

=item *

any icons or stylesheets, so it is save to customize these;

=back

=head2 Adding medium sized images

The purpose of medium sized images is easy browsing by having a
consistent and convenient size. The default size shows normal 4:3
images completely on an 1024x768 screen in the browser's full screen
mode.

To add medium sized images (and also specify an album title):

  $ album -v --medium --title "My First Album"
  No info.dat, adding images from large
  info.dat: Cannot update (does not exist)
  Number of entries = 7 (7 added)
  mkdir medium
  im023.jpg: medium OK
  im024.jpg: medium OK
  im025.jpg: medium OK
  im026.jpg: medium OK
  im027.jpg: medium OK
  im028.jpg: medium OK
  im029.jpg: medium OK
  Creating pages for 7 images
  (Needed to write 14 image pages)
  Creating pages for 1 index
  (Needed to write 1 index page)

Again, 'album' only does the work needed, re-using the work already
done.

=head2 Adding image descriptions

As can be seen from the example runs, 'album' looks for a file
'info.dat'. This file can be used to:

=over 4

=item *

control what images must be shown

=item *

the order in which they must be shown

=item *

whether rotation is necessary

=item *

set tag and description information

=item *

control other settings

=back