# 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.2 2004/02/26 11:46:59 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).

If you have enabled C<?style=xml> processing in your Apache configuration
file you can always get the internally generated XML for a proofsheet
by appending C<?style=xml> to a proofsheet URL.

=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>

      <!-- <server> contains information about the web server 
           configuration -->
      <server>
        <site>http://www.example.com</site>
        <admin>you@example.com</admin>
        <hostname>www.example.com</site>
        <port>80</port>
      </server>
    </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.

             The information is structured as RDF, with elements from a
             number of different XML namespaces used.  Details about the
             namespaces can be found in AxKit::App::Gallery::namespaces.

             Elements in this example have been grouped according to 
             namespace prefix, and sorted according to element name for
             ease of reading.  The actual output from the stylesheets is
	     not sorted this way. -->

        <rdf:RDF 
          xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
          xmlns:a="http://dublincore.org/documents/2003/02/04/dces/" 
          xmlns:b="http://impressive.net/people/gerald/2001/exif#" 
          xmlns:c="http://www.cpan.org/authors/id/G/GA/GAAS/#"
          xmlns:d="http://search.cpan.org/author/NIKC/xml#" 
          xmlns:e="http://xmlns.com/foaf/0.1/">

          <rdf:Description 
            rdf:about="/pics/2003 10 25 Eighty Days Photoshoot/PICT3257.JPG">

            <!-- EXIF, from Image::Info -->
	    <b:BrightnessValue>60/10</b:BrightnessValue>
	    <b:ColorSpace>1</b:ColorSpace>
	    <b:Comment>AppleMark
	    </b:Comment>
	    <b:ComponentsConfiguration>YCbCr</b:ComponentsConfiguration>
	    <b:Contrast>Normal</b:Contrast>
	    <b:CustomRendered>Custom process</b:CustomRendered>
	    <b:DateTime>2003:10:25 18:09:00</b:DateTime>
	    <b:DateTimeDigitized>2003:10:25 13:23:24</b:DateTimeDigitized>
	    <b:DateTimeOriginal>2003:10:25 13:23:24</b:DateTimeOriginal>
	    <b:DigitalZoomRatio>0/1</b:DigitalZoomRatio>
	    <b:ExifImageLength>1920</b:ExifImageLength>
	    <b:ExifImageWidth>2560</b:ExifImageWidth>
	    <b:ExifVersion>0220</b:ExifVersion>
	    <b:ExposureBiasValue>0/10</b:ExposureBiasValue>
	    <b:ExposureMode>Auto exposure</b:ExposureMode>
	    <b:ExposureTime>1/60</b:ExposureTime>
	    <b:FNumber>56/10</b:FNumber>
	    <b:Flash>Flash did not fire, compulsory flash mode</b:Flash>
	    <b:FlashPixVersion>0100</b:FlashPixVersion>
	    <b:FocalLength>4537/256</b:FocalLength>
	    <b:FocalLengthIn35mmFilm>71</b:FocalLengthIn35mmFilm>
	    <b:ISOSpeedRatings>100</b:ISOSpeedRatings>
	    <b:ImageDescription>DCF 1.0</b:ImageDescription>
	    <b:JFIF_Version>1.01</b:JFIF_Version>
	    <b:JPEG_Type>Baseline</b:JPEG_Type>
	    <b:LightSource>unknown</b:LightSource>
	    <b:Make>Minolta Co., Ltd.</b:Make>
	    <b:MaxApertureValue>35/10</b:MaxApertureValue>
	    <b:Model>DiMAGE 7i</b:Model>
	    <b:SamplesPerPixel>3</b:SamplesPerPixel>
	    <b:SceneCaptureType>Standard</b:SceneCaptureType>
	    <b:Sharpness>Normal</b:Sharpness>
	    <b:Software>QuickTime 6.4</b:Software>
	    <b:SubjectDistanceRange>Close view</b:SubjectDistanceRange>
	    <b:Tag-0x013c>Mac OS X 10.2.8</b:Tag-0x013c>
	    <b:WhiteBalance>Auto white balance</b:WhiteBalance>
	    <b:YCbCrPositioning>1</b:YCbCrPositioning>
            <b:ExposureProgram>Program</b:ExposureProgram>
            <b:MeteringMode>Pattern</b:MeteringMode>
            <b:Saturation>Normal</b:Saturation>
	
            <!-- Non-EXIF, from Image::Info -->
	    <c:width>1920</c:width>
	    <c:file_media_type>image/jpeg</c:file_media_type>
	    <c:color_type>YCbCr</c:color_type>
	    <c:height>2560</c:height>
	    <c:file_ext>jpg</c:file_ext>

            <!-- Each potential version of the image is also representated.
                 The 'e:thumbnail/rdf:Description/rdf/@about' element is the
                 URI that will generate the thumbnail at this particular
                 size. -->
            <e:thumbnail>
              <rdf:Description 
                rdf:about="/pics/2003 10 25 Eighty Days Photoshoot/PICT3257.JPG?size=133">
                <a:title>133.jpg</a:title>
                <c:height>133</c:height>
                <c:width>99</c:width>
                <d:size>133</d:size>
              </rdf:Description>
            </e:thumbnail>
            <e:thumbnail>
              <rdf:Description rdf:about="/pics/2003 10 25 Eighty Days Photoshoot/PICT3257.JPG?size=640">
	        <a:title>640.jpg</a:title>
	        <c:height>640</c:height>
	        <c:width>480</c:width>
	        <d:size>640</d:size>
              </rdf:Description>
            </e:thumbnail>
            <e:thumbnail>
              <rdf:Description rdf:about="/pics/2003 10 25 Eighty Days Photoshoot/PICT3257.JPG?size=800">
		<a:title>800.jpg</a:title>
		<c:height>800</c:height>
		<c:width>600</c:width>
		<d:size>800</d:size>
              </rdf:Description>
            </e:thumbnail>
            <e:thumbnail>
              <rdf:Description rdf:about="/pics/2003 10 25 Eighty Days Photoshoot/PICT3257.JPG?size=1024">
		<a:title>1024.jpg</a:title>
		<c:height>1024</c:height>
		<c:width>768</c:width>
		<d:size>1024</d:size>
              </rdf:Description>
            </e:thumbnail>
          </rdf:Description>
        </rdf:RDF>
      </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::namespaces,
AxKit::App::Gallery::Plugin, AxKit::App::Gallery::Provider

=head1 AUTHOR

Nik Clayton, nik@FreeBSD.org

=head1 BUGS

Undoubtedly.