# Copyright (c) 2003 Nik Clayton
# All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
# 
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
# 
# $Id: proofsheet.pod,v 1.1.1.1 2003/03/29 17:11:49 nik Exp $
 
=head1 NAME

AxKit::App::Gallery::proofsheet

=head1 DESCRIPTION

A proofsheet is generated by AxKit::App::Gallery whenever the user
requests a directory listing of a ::Gallery managed directory.  The
proofsheet is an XML document, and the last stylesheet in the proofsheet
processing chain should style this to HTML (or your final delivery
format).

=head1 PROOFSHEET STRUCTURE

This is an annotated proofsheet.  I should really create this as a DTD.

  <?xml version="1.0"?>
  <proofsheet>			<!-- Root proofsheet element -->

    <!-- These elements contain information about the gallery's
         configuration, as specified in the Apache config file -->
    <config>

      <!-- <perl-vars> contains values that are set using the PerlSetVar
	   command that relate to the gallery config.  A simple

	       <var name="foo">value</var>

	   syntax is used (mostly). -->
      <perl-vars>
        <var name="ProofsheetColumns">4</var>
        <var name="ImagesPerProofsheet">16</var>
        <var name="GalleryCache">/var/tmp/gallery</var>
        <var name="GalleryThumbQuality">preview</var>

	<!-- GallerySizes is different.  It's a space separated string
	     in the config file.  XSLT would much prefer this to be  
	     broken out in to tree of nodes, so that's what we do.  
	     Note the 'type="thumb"' attribute, which indicates which
	     of the sizes is going to be used for thumbnails -->
        <GallerySizes>
          <size type="thumb">133</size>
          <size>640</size>
          <size>800</size>
          <size>1024</size>
          <size>full</size>
        </GallerySizes>
      </perl-vars>
    </config>

    <!-- Each directory to be listed is represented as an <album>
	 element, with a top-level <albums> wrapper -->
    <albums>
      <album>

	<!-- The current directory is always included.  This is so that
	     the breadcrumb trail navigation can be constructed. -->

        <name>.</name>

	<!-- The URI for this directory is included, for the breadcrumb
	     trail, and so that links to it can easily be generated.
	     For ease of parsing in XSLT, the URI is split in to tokens,
	     delimited by the '/' in the URI (which is not included).
	     Each token becomes a <component>, which then contains an
	     <e>scaped and an <u>nescaped version of the URI.  The
	     escaped version is for use in href attributes, the
	     unescaped version is for use when displaying the directory
	     name to the end user in a web page.

             So this URI might end up as:

	     <a href="/pics/2002%2005%20(May)%20Singapore/">/pics/2002
	     05 (May) Singapore</a>

	     -->
        <uri>
          <component>
            <e>pics</e>
            <u>pics</u>
          </component>
          <component>
            <e>2002%2005%20(May)%20Singapore</e>
            <u>2002 05 (May) Singapore</u>
          </component>
        </uri>

	<!-- The local path to the directory and the content-type are
	     also included -->
        <dirpath>/local/2/pub/Pictures/2002 05 (May) Singapore</dirpath>
        <content-type>httpd/unix-directory</content-type>
      </album>

      <!-- Repeat <album> elements as necessary -->
    </albums>

    <!-- Each image is wrapped in an <image> element with various child
	 elements.  All the images are wrapped in an <images> element.  -->

    <images>
      <image>
        <filename>P0001065.JPG</filename>	<!-- Filename -->
        <filesize>359856</filesize>		<!-- Size in bytes -->

	<!-- The modification time is 'seconds-since-the-epoch', which
	     may not be terribly useful in XSLT.  I'm not too worried
	     about this at the moment, since (I think) it's more likely
	     that the EXIF info about when the image was taken or 
	     modified (see <imageinfo> later) is going to be more useful
	     -->

        <modified>1021152828</modified>		

	<!-- The URI for this image.  Actually, it's the URI for the 
	     directory that the image is in.  This follows the same 
	     format as the <uri> element in the <album> element -->

        <uri>
          <component>
            <e>pics</e>
            <u>pics</u>
          </component>
          <component>
            <e>2002%2005%20(May)%20Singapore</e>
            <u>2002 05 (May) Singapore</u>
          </component>
        </uri>

	<!-- Full path to the image on the local file system -->
        <dirpath>/local/2/pub/Pictures/2002 05 (May) Singapore</dirpath>

	<!-- Content type, as determined by Apache -->
        <content-type>image/jpeg</content-type>

	<!-- There now follows information gleaned from the image using
	     the Image::Info module.  This is basically a straight dump
	     of all the info found.

	     This sucks, and needs a better approach.  For example, as
	     you can see, some elements (<BitsPerSample>) appear more
	     than once.  At the moment, there is no guarantee either
	     about what elements will come back.  This really needs to
	     be split in to at least two groups -- info we know we can
	     get (image dimensions, that sort of thing), and additional
	     info that may or may not be present.  Like the camera
	     model, or the aperture value.

	     In addition, this information isn't pre-processed before it
	     gets here.  So you get things like

		 <FNumber>476/100</FNumber>

             which could be made more useful.  I suspect a lot of this
	     will need to go in to an exif: namespace... -->
        <imageinfo>
          <MeteringMode>Center weighted average</MeteringMode>
          <width>1536</width>
          <resolution>150/1 dpi</resolution>
          <ExifImageLength>1024</ExifImageLength>
          <Model>KODAK DIGITAL SCIENCE DC260 (V01.00)</Model>
          <ExifImageWidth>1536</ExifImageWidth>
          <FNumber>476/100</FNumber>
          <BitsPerSample>8</BitsPerSample>
          <BitsPerSample>8</BitsPerSample>
          <BitsPerSample>8</BitsPerSample>
          <MaxApertureValue>300/100</MaxApertureValue>
          <Make>Eastman Kodak Company</Make>
          <LightSource>Auto</LightSource>
          <ApertureValue>450/100</ApertureValue>
          <file_media_type>image/jpeg</file_media_type>
          <SamplesPerPixel>3</SamplesPerPixel>
          <YCbCrPositioning>1</YCbCrPositioning>
          <CompressedBitsPerPixel>24/10</CompressedBitsPerPixel>
          <ColorSpace>1</ColorSpace>
          <DateTimeOriginal>2002:05:11 22:33:48</DateTimeOriginal>
          <ShutterSpeedValue>800/100</ShutterSpeedValue>
          <ExposureTime>1/250</ExposureTime>
          <Orientation>top_left</Orientation>
          <FocalLength>208000/10000</FocalLength>
          <ExifVersion>0200</ExifVersion>
          <ExposureBiasValue>0/100</ExposureBiasValue>
          <FlashPixVersion>0100</FlashPixVersion>
          <color_type>YCbCr</color_type>
          <file_ext>jpg</file_ext>
          <height>1024</height>
          <SubjectDistance>500/100</SubjectDistance>
          <JPEG_Type>Baseline</JPEG_Type>
          <ColorComponents>
            <anon>Y</anon>
            <anon>34</anon>
            <anon>0</anon>
          </ColorComponents>
          <ColorComponents>
            <anon>Cb</anon>
            <anon>17</anon>
            <anon>1</anon>
          </ColorComponents>
          <ColorComponents>
            <anon>Cr</anon>
            <anon>17</anon>
            <anon>1</anon>
          </ColorComponents>
        </imageinfo>

	<!-- The thumbnails for each image are now described.  Each
	     thumbnail is <thumb> element, all wrapped in a <thumbs>
	     element. --->

        <thumbs>
          <thumb>
            <!-- This is the thumbnail's size as it corresponds with one
		 of the definitions in the GallerySizes configuration
		 option.
            <size>133</size>

	    <!-- This is the height and width of the thumbnail.  One of
		 these will be the same value as the <size> element, but
		 it will differ depending on whether the image is
		 oriented as portrait or landscape. -->
            <height>88</height>
            <width>133</width>

	    <!-- This is the name of the thumbnail image -->

            <filename>133.jpg</filename>
          </thumb>

          <thumb>
            <height>426</height>
            <width>640</width>
            <filename>640.jpg</filename>
            <size>640</size>
          </thumb>

	  <!-- More thumb elements as necessary -->
        </thumbs>
      </image>
    </images>

    <!-- The proofsheet may need to be spread over multiple 'virtual'
	 pages, depending on the number of images in the directory, and
         the value of the ImagesPerProofSheet variable.

	 The <pages> element contains one or more <page> elements.  Each
	 <page> element has a 'number' attribute, indicating the page
	 number.  The current page will have a 'current' attribute to
	 indicate that. -->

    <pages>
      <page number="1" current="yes"/>
  
      <!-- A second page would appear as:

	   <page number="2"/>

           -->
    </pages>
  </proofsheet>

=head1 SEE ALSO

AxKit::App::Gallery, AxKit::App::Gallery::proofsheet, 
AxKit::App::Gallery::imagesheet, AxKit::App::Gallery::Plugin, 
AxKit::App::Gallery::Provider

=head1 AUTHOR

Nik Clayton, nik@FreeBSD.org

=head1 BUGS

Undoubtedly.
