view release on metacpan or  search on metacpan

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

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
B<--clobber> below);

=item *

any icons, so it is safe 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

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

  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

The first line can be used to designate a coding system, in case the
information needs to contain non-ASCII characters. For example, to
designate that the data is in ISO 8895.1 (Latin-1) encoding, use:

  #    -*- coding: iso8859-1 -*-

Most settings can also obtained with command line options, as shown.

=over

=item B<!title> I<XXX>

Sets the title to I<XXX>, override with B<--title>.

=item B<!home> I<XXX>

Provides an 'up' link on the index pages. Override with B<--home>.
Note that this link is relative to the location of the index directory.

=item B<!page> I<N>B<x>I<M>

Sets the layout to I<N> rows (B<--rows>) and I<M> columns (B<--columns>).

=item B<!thumbsize> NNN

Specifies the desired width for thumbnail images (B<--thumbsize>).

=item B<!medium>

Includes medium sized images (B<--medium>) of default size.

=item B<!mediumsize> I<NNN>

Specifies the desired width for medium sized images (B<--mediumsize>).
To enforce this width, even if the original image is smaller, specify
C<!> after the size.

=item B<!tag> I<XXX>

Sets the tag line for all subsequent images. Cancel with an empty
B<!tag> command.

=item B<!caption>

Sets the caption code for index pages (B<--caption>). It must be a
sequence of B<f> (file name), B<s> (size, WxH), B<c> (caption), B<t>
(tag line). If no B<!caption> has been used, the default value is
B<fct>.

=item B<!dateformat> I<XXX>

Sets the default date format as used for the tag lines for new images.
I<XXX> must be a valid strftime(2) date format string, for example:

  !dateformat %a %e %B %Y

=item B<!icon>

Produce a file C<icon.jpg> to be used as an icon for this album
(B<--icon>). The icon is of thumbnail size, and contains a small
lookalike of the first index page.

B<!icon> may be followed by a something true or false (B<--noicon>).
Default is true.

=item B<!locale> I<XXX>

Set the locales for sorting and date formats to I<XXX>.

=back

B<album> can read values for settings from configuration files.
Settings can be set as in C<info.dat>, the leading exclamation mark is
optional in this case. By default, the configuration files used are
C<.albumrc> in the current directory, and C<.albumrc> in the user's
home directory. The order of precedence is:

=over

=item 1. command line options

=item 2. C<info.dat>

=item 3. user config file C<.albumrc> in current directory

=item 4. user config file C<.albumrc> in the home directory

=back

Environment variable ALBUMCONFIG can be used to designate user
config files. It should be set to a colon-separated list of file names
to be processed in order of precedence.

=head2 Importing new images