view release on metacpan or  search on metacpan

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

  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.

=item $jscript

The javascript for keyboard navigation.

=item $image

Image pages only: The actual image.

=item $lbot

Image pages only: The text below the image, left.

=item $rbot

Image pages only: The text below the image, right.

=item $contents

Index pages only: The table with all the images for this page.

=item $tag

Journal pages only: The tag for this page.

=item $journal

Journal pages only: The journal for this page.

=back

=head3 External style sheets

When 'album' is run with B<--extcss> it will create a directory 'css'
and, in this directory, the css style sheets 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
external style sheets if they are available.

To obtain good results, the style sheets must match the formats.
'album' will try to verify this by reading the first line of the style
sheets and the formats, and verify that it contains a version
indication of the form

  ALBUM-FMT-VERSION: <major>.<minor>   (for formats)
  ALBUM-CSS-VERSION: <major>.<minor>   (for style sheets)

For all style sheet - format pairs, the major numbers must be the
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