Album

 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

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

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

If you hover the mouse over the file name in the index page, or over
the title on the image pages, a pop-up will show a selection of
information from the EXIF data.

=head2 Embedding other albums

In the file 'info.dat' you can also enter names of HTML documents to
refer to arbitrary other information you want to include in your
album. You can use this to embed (more precisely: refer to) other
albums. For example:

  20040910/index.html  Pictures of an exhibition

This will store in the album a reference to another album. If at the
given location a file 'icon.jpg' exists, this will be used in the
album as thumbnail image. To generate a sample icon for an album to be
included, run the album program with command line option --icon.

The reference will only be present on the index pages. When following
the 'previous' and 'next' links of image pages, these references will
be skipped.

Note that when you click on an external reference thumbnail, a new
browser window will be opened to show the referenced information.

=head2 Journal mode

I<Warning: Journal mode is still under development and may change in
future versions.>

Journal mode is enabled with the control B<!journal> in C<info.dat>.

When journal mode is enabled, the data from C<info.dat> is considered
to be a series of paragraphs. Paragraphs are separated using one or
more empty lines.

The first line of a paragraph may contain image info, preceeded by an
asterisk and whitespace. For example:

  !journal

  !tag 2004/06/01

  A bright, shiny day.

  * im023.jpg  Sunrise
  This morning, we were surprised by a fantastic sunrise like
  we have never seen before.

  * im024.jpg  Overview
  This picture shows an overview of the area.

This way it is possible to attach extended pieces of text to a images.

An additional series of pages is generated, the journal pages. Each
journal page contains the extended text and thumbnail images of all
entries that belong to a single tag. The idea is that the tags are
dates, and each journal page contains the text and images of a single
day.

If the extended text starts with C<< < >> it is assumed to be HTML and
included literally.

The medium and large image pages have an additional icon to jump to
the journal entry for an image. The extended text can be also viewed
on the medium and large image pages when the mouse is placed over the
info at the right side above the image, e.g., C<My First Album: Image
1 of 9>.

Note that journal mode can not be mixed with normal mode.

=head2 External formats and style sheets

I<Warning: External formats and style sheets are still under
development and may change in future versions.>

Internally, 'album' uses formats (templates) to build the generated
HTML pages, and cascading style sheets (CSS) to specify how the
browser should show the pages. Formats and style sheets can be
exported (written to external directories), and 'album' will then use
the external information. So you can have ultimate control over how
pages must look like.

=head2 External formats

When 'album' is run with B<--extformats> it will create a directory
'formats' and, in this directory, the HTML templates for all types of
pages that 'album' will generate. Existing files in this directory
will B<not> be overwritten, so it is safe to change the templates to
your liking. When 'album' is run again to process images, it will use
the templates from the 'formats' directory if they are available.

The templates are plain HTML and contain variables that will be
substituted with actual values. Some of the variables are:

=over 12

=item $title

The title of the album.

=item $css

The code to get the style sheet of this page. This can be in-line
specifications, or a link to an external stylesheet.

=item $ltop

Index and image pages only: The text above each image, left.

=item $rtop

Index and image pages only: The text above each image, right.

=item $vbuttons

The navigation buttons, arranged vertically.

=item $hbuttons

The navigation buttons, arranged horizontally.