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

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

=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

The format of 'info.dat' is simple. Empty lines and lines starting with
a '#' are ignored. Data lines contain the name of an image file,
followed by its description. Control lines start with an '!' mark.

'album' can fill 'info.dat' for you. To obtain this, create an empty
'info.dat' file, and run 'album':

  $ touch info.dat
  $ album -v --medium --title "My First Album"
  No info.dat, adding images from large
  Updating info.dat
  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)

Upon completion, 'info.dat' will look similar to:

  # album control file generated by album 1.19, Tue Jun  1 22:39:41 2004
  !title My First Album
  !medium
  # New entries added by album 1.19, Tue Jun  1 22:39:41 2004
  !tag 
  im023.jpg  
  im024.jpg  
  im025.jpg  
  im026.jpg  
  im027.jpg  
  im028.jpg  
  im029.jpg  

You can now add a description for each image following the file name,
for example:

  !tag 2004/06/01
  im023.jpg  Sunrise
  im024.jpg  Overview
  im025.jpg  Across the lake
  im026.jpg  Catch of the day
  im027.jpg  Fishermen
  im028.jpg  Swimming cows
  im029.jpg  Moon over Clew Bay

Re-run the program (no need for B<--medium> and B<--title> anymore):

  $ album -v
  Number of entries = 7
  .......[7]
  Creating pages for 7 images
  (Needed to write 14 image pages)
  Creating pages for 1 index
  (Needed to write 1 index page)

There are no complaints anymore about a missing 'info.dat', but
there's also no message 'adding images from ./large'. In other words,
the only images shown are the ones named in the control file. New
images added to the 'large' directory will be ignored. We'll see later
what to do about that.

=head2 Summary of 'info.dat' control commands