Introduction

<H1>Introduction</H1>
<H2>Product overview</H2>
	Albagtor creates a HTML photo album based on a directory containing photo files.
The script can create a photo album based solely on the directory of photo.
In order to be able to have customized album, the script will use the following:
  i1 - directory containing the pictures *MANDATORY*
  i2 - indexes of legends on ACDSee format 
  i3 - configuration set
  i4 - list of labels to separate your album into chapters
  i5 - extra HTML files to be included in the album (called 'logs')

Only i1 is mandatory. It is required that the pictures-directory should be called ref. It's parent directory is called $MainDir (the 'main directory').

<H2>Album structure Overview</H2>
The album will have the following structure:

       $MainDir-+-album # will contain the HTML tree of the album  
                |
                +-ref   # contains the pictures
                |
                +-tn----+-chapter1    # will contain the thumbnails
                |       |
                |       +-chapter2
                |
                +-logs   # contains the extra files (i5)

  Once you created your thumbnails, you will put them in specific chapter directories to organise your album.

<H1>Detailed album structure</H1>
    <H2></H2>* album
      Contains the HTML tree of the album. Will be created if missing. Do not put any extra files on it (if you want extra files, see logs below).

    <H2></H2>* ref
      Contains the pictures full-size (i1) and the index of legend (i2).
      This directory is mandatory
      The pictures should be as following:
        format *.gif, *.jpg or *.jpeg
        no file called header.*
        no blank in filenames
      The index of legend should be as following:
        name: 'descript.ion'
        format: ACDSee format:
          one line per picture
          each line formated as following: 'filename<blank>legend'
          legend is HTML coded
    <H2></H2>* tn
      Contains the chapters and the list of labels (i4)
      Each sub-directory of tn is a chapter of the album.
      To have your pictures appear in the album, you will put their thumbnails in the proper chapter sub-directory as following:
	tn/chapter1/tn_<imageFileName.ext>
	where <imageFileName.ext> matches an existing pictures from ref.
        The name of the chapters as they appear in the album are in the list of label as following:
        filename is 'descript.ion' (on directory tn)
        format: ACDSee format:
          one line per chapter
          each line formated as following: 'chapter-dirname<blank>chapter name'
          chapter name is HTML coded
        The chapter-dirname will be used if chapter name is not defined
      The chapter will be ordered by chapter-dirname
      If this directories are missing, your album will be empty. However, with proper options or command, you can force the Albagtor to create a default chapter and all thumbnails to initialize your album.

    <H2></H2>* logs
      Contains extra HTML files (called 'logs') and other documents. Use this directory to add data in your album that you will not embed with the photos.
      The label to be used for the log section can be customized in the ACDSee file of the main directory
      All logs will be included in the album by means of a list of links in the section 'logs' of the album, hot-text will be read from the logs ACDSee file (filename if not defined).

      The content of the logs will be scanned and each tag <IMG> sourcing to pictures of the album will be normalized:
        sourcing will be set to the thumbnail
        propery ALT will contain the legend (converted as text)
        propery HEIGHT and WIDTH will be set
        image will be upgraded with link to the page of the picture
      If you wish to include non-HTML documents (AVI, sound...), you have to write a HTML log that will link explicitely to them.

  <H2></H2>More details:
    Albagtor will create an album in the subdir album under $MainDir. During the process, the existing directory album will be deleted (deltree), any existing files you may have drop here will be lost (the deltree will be executed in the 'cleaning' phase, after creation of a new album including the untouched files detected by the dirty-file detection system, see below).
    Albagtor will create:
      - three main indexes under album
        - index.html: list of chapters (AT)
        - fullindex.html: list of chapters including display of all thumbnails by chapter (ITAG)
        - index.html: list of chapters including list of all pictures (legend only) by chapter (ITNG)
      - one sub-directory for each chapter (same name as the chapter-dirname from tn) where each chapter will be rooted. Each sub-directory will contain:
        - index.html: list of pictures with display of thumbnails (I1AG)
        - <imageFileName.ext>.html for each picture: one HTML page with display of the picture (size limited by configuration), sourcing to the picture from ref, legend from the index.
    In any cases, blanks in file or directory names are not supported, except for $MainDir.
    In the album, all links will be converted as lowercase. If you use a case-sensitive platform, we recommand you set all your file and dir names to lowercase (this includes your http server if you publish your album).

  <H2></H2>Sound files:
    Albagtor can embed sound files in your album in some extent. This feature is supported as following. In the ref directory, if there is a sound file with the same name as a picture file (example: elephant.jpg and elephant.wav), then the comment of the said picture will be extended with the sound file (as link) plus it's comment if any -from ACDSee file). 
        
<H1>Configuration</H1>
  <H2></H2>Configuration set (i3)
    The appearance of the album will be customized by the configuration set.
    The configuration set is a file with the following format:
      one line per parameter
      format of line is: 'parameter =value'
      parameter name is case-sensitive
      parameter will be set to '' if 'value' is empty
      unset parameters will be replaced by default value 
      leading blanks allowed
      empty lines allowed
      blanks before '=' allowed
      no blanks after '='
      commented lines start by '#'
      unknown parameters are ignored
      
  <H2></H2>Configuration parameters overview


      Here are the items of the album file:
MainDir  : Directory where the album is rooted
Tailer   : Text that will appear at the bottom of each page (HTML code) 
NbCol    : Nb of col of thumbnails in the index 
FontFace : Font name of the text
Language : Language of the album (navigational elements) (see below)
Location : Geographic location of the author or album (see substitution below)
Height   : Height of the <IMG> used in the <imageFileName.ext>.html
ThumbnailSurface : Surface (in square pixels) of the created thumbnails.
TitrePrincipal   : Name of the album: will appear in the title and in the window bar.

  The following are the meta tags used in the HTML file.
META_author       : Unqualified author's name
META_description  : A short, plain language description of the document
META_distribution : Distribution conditions
META_keywords     : Keywords used by search engines to index your document
META_ownership    : Author in the copyrights' view
META_generator    : Name and version number of the publishing tool

  The followings are the properties of the BODY tag
BODY_bgcolor	: background color
BODY_text	: color of text
BODY_link	: color of links
BODY_vlink	: color of visited links
BODY_alink	: color of active links (when you click or focus it)
BODY_background : image of background

  The following are used for the automatic synchronization.
  Please refer to the section 'FTP transfer' below and to the doc of ftp_sync.pl.
remote_host : host of server for ftp transfer
remote_user : username for ftp transfer
remote_root : directory on ftp server
remote_pwd  : password for ftp tranfer, may be crypted (see below)

  Extra remarks about configuration follows:
  
<H2></H2>* Language configuration parameter
	List of supported language: fr, us

<H2></H2>* Height configuration parameter
	Each photo page <imageFileName.ext>.html displays the matching picture from ref with tag IMG with this specific height. The witdh will be set accordingly. If the height of the source is lesser than this parameter, the picture will keep its actual size.

<H2></H2>* ThumbnailSurface configuration parameter
	When created by Albagtor, the thumbnail will be created with this constant surface, so that the global appearance will be sweet for the eye. Example with 40000: if your picture is portrait format 4/3, then the thumbnail's size will be 173 x 231 (same format but with surface approx to 40000). The same picture in landscape will be 231 x 173. Another thumbnail with format 16/9 will display as 267x150.
  These three will have different height and size, but constant surface. 
  This only applies when you let Albagtor create (or re-create) the thumbnails, with proper options or command. On default behavior, Albagtor does not recreates the existing thumbnails and displays error messages on missing thumbnails.

<H2></H2>* remote_pwd configuration parameter
if you put the uncrypted password here, be carefull that this file will not be included in the transfer to the server in which case your ftp password would become publicly available by http. To prevent that, you can either put this file outside the $MainDir, or you can crypt it. See section 'FTP Transfer'.

<H2>Use variables in configuration</H2>
  On creation of the album, the values of the configuration set will be expanded as following:
    $Location will be replaced by value of parameter Location
    $generator will be replaced by the name of the product
    $STD_Version will be replaced by product name
    $ENV{var} will be replaced by value of $var (where $var is an environment variable)

<H2>Default values of configuration</H2>
  The default values of the following can be specified by option on the command lines: ThumbnailSurface, ThumbnailSurface
    
<H1>Album index creation</H1>
    In order to help the user to manage his collection of album when it increases, 
    Albagtor comes with an album indexer that will creates for you list of albums with statistics and addresses.
    The indexer will have different behavior depending it is exectued from the graphical interface and the command line interface. The following apply to all versions.
    With proper options or command, Albagtor will scan a list of specified album files to compute different kind of indexes.
    The list of files included in the scope of the index is specified by a list of mask.
    For example, 'china-*.alb thai-*.alb' is a valid list of masks. The corresponding files will be scanned for relevant information regarding the indexes to construct.
    The index will be written in an HTML file (that may be STDOUT).

    The detailed index will indicate:
      Pictures: number, volume
      Volume of album (pictures + HTML)
      URL of album (when available)
      Description of the album (extracted from the description of the main header image)

    The three supported index have the following tag-ID:
      album_index_simple (AIS)
        list of albums with links to albums on remote server. No details.
      album_detailed_server (ADS)
        detailed list of albums with HTML link to albums on server. Use this one for publication.
      album_detailed_local (ADL)
        detailed list of albums with HTML link to local album files. Use this one for your internal use only

      album_index_mapping (AIM)
       list of albums with internal links to the album items in the index file. This one is suppoes to be used followed by another one.

      index_by_server (IBS)
       list of albums grouped by server, with display of server stat. Use this to keep track of your server layout and occupancies.

    If the file does not previously exist (or is STDOUT), then, standard index are created in an new HTML file, that will contain AIS and ADS.
    Otherwise, the existing index in the HTML file (located by their tag-ID, the 1st of each only) will be updated. If there is none, no index will be computed.
    Example: to insert an AIS index in an existing HTML file, write the following tag where you want the index to be inserted: '<DIV id="album_index_simple"></DIV>'. When you feed your file to Albagtor, all HTML code within this DIV tag will be replaced by the index.

    The expansion of the list of mask will be different depending on the interface and on the platform:
      command-line interface
        Expansion will be performed by the shell. For M$-Windows based platform, you need to set the Wild.pm option. See installation notes of Albagtor. 
        You can use environment variables; relative and absolute path.
      graphical interface
        Expansion will be performed by the standard perl 'glob' (same as /bin/csh). 
        You can use environment variables ${VAR} will be replaced by the value of VAR
        Backslash (\) will be threated as escape characters.
        If you are a M$-Windows user, replace '\' by '/' in the path to expand sub-directories. The system will detect that 'c:\' (example) is a root
        The graphical interface can let you pre-view the list of files selected by the masks


<H1>Dirty-page detection</H1>
  The dirty page detection is the system that will let you or another process detect which pages has been modified after album update. These files are called dirty files (because they have been touched).
  When the album gets bigger, the number of files increases. If you publish the album on a http server remote server synchronized by ftp, the transfer time will increase. It is thus worthwile to limite the transfer only to the modified files. The dirty-page detection will help you with that regard.
  The followings are implemented:
   * Albagtor is able to detect when you perform an update of an existing album (as opposed to creation of a new album), the pages that do not bear modification are left untouched. The pages that are not part of the album any more are removed (including any extra unknown file or directory).
   * stampdates, version number, location... are only set on dirty pages.
   * An invisible character-padding will randomize the size of the file.

  These three features combined will garantee that a dirty file will always have a different file size (than it's own size before update), even if (for example) the modification is only changing one character 'a' to 'A'.   
  
  After album updates, the dirty files can thus be detected:
  	by their stampdate
  	by comparing their size versus their size before the update

<H1>FTP transfer</H1>
  If you want to send your album on a remote server (example for HTTP publication), you can use any FTP client. However, then you can make Albagtor to do job by using another software developped by the author named ftp_sync.pl.
  
  If ftp_sync.pl is installed, and on proper options and command, Albagtor will execute ftp_sync.pl to connect by ftp to the remote server and synchronise the album, using the file-size as dirty-page detection system (providing you always transfer your files in binary mode).

  With Albagtor combined with ftp_sync.pl, you will only transfer the pages that where modified by the album update.
  
  The configuration file that ftp_sync.pl uses is the same as the one used by Albagtor: you will fill the thre 'remote_*' parameters. Password should be crypted, and will be decrypted by ftp_sync.pl on connection time based on the key specified by the user on execution time.

  Please refer to the documentation of ftp_sync.pl for details, specifcally the encryption/decryption system.

<H1>Line command</H1>
<H2>Usage</H2>
Usage 1: albagtor.pl [-wsTR] -f Config_file_path [-t new_chapter] [-S default_surface] [ -F crypt_key]
Usage 2: albagtor.pl [-wsTR] -I photos_path [-t new_chapter] [-S default_surface]
Usage 3: albagtor.pl -i [-s] [-H HTML_index_file] [--] list_of_album_masks...
Usage 4: albagtor.pl [-h|-v| {-P package_level}]

  Usage 1: create/update album according to specification in file Config_file_path
  Usage 2: create/update album with default value using pictures in photos_path (MainDir/ref).
  Usage 3: update/create index based on a list of album files designated by list_of_album_masks
  Usage 4: displays online doc, version number or package list.

<H2>Options</H2>
    -f: usage 1, mandatory. Specify the config file .
    
    -t: usage 1 & 2, optional. With this option, all orphean picture (pictures without thumbnails)  will have a thumbnail created in the chapter new_chapter, which will be created if necessary. See also option -S.
    
    -T: usage 1 & 2, optional. Force Albagtor to rebuild every existing thumbnail. This option becomes handy after you made major editing on your pictures collection (red-eye reduction, cropping...). See also option -S. 
    
    -S: usage 1 & 2, optional. Whether missing or reconstructed (see option -T and -t), the thumbnails created by Albagtor will have a constant surface, as explained in the main documentation. When this surface is not specified in a configuration file, Albagtor will use the value specified in option -S. Note that if the surface is specified in the configuration file, the -S option does not override it (only for usage 1).
    
    -R: usage 1 & 2, optional: remove (delete) all orphean thumbnails (thumbnails for which there is no matching picture). Combine this option with -t, chapter by chapter, after you made some major file renames in your pictures collection.

    -I: usage 2, mandatory. Specify the photo directory. The main directory will be the parent of the photo directory, it is thus required that the photo directoy should be named like MainDir/ref. Thumbnail directories will be created if missing with name according to option -t or 'new' if not specified.
    
    -H: usage 3: specify the file to edit or create to construct the index. If not specified, file will be STDOUT.

    -w: use wrap mode when updating the HTML code of the log files.	  

    -W: set to verbose warning mode. If you use logs combines with this option, Albagtor will complain for every picture present in ref but not referenced in the log.

    -s: set to silent mode: suppress info, display only warnings and errors

    -F: usage 1, optional. Specify the crypt key to use to decode the password for FTP transfer.

    -P: usage 4, optional. Albagtor will diplay package information depending on the level. 1: list of mandatory files to be included in the package for shipment; 2: version of each file.


<H1>Future upgrades</H1>
  Documentation related to indexer anf ftp synchronization requires review
  'Belph�gor' bug
  crypt/decrypt should be available in graphic mode from the albagraph front-end

<H1>Final statement</H1>

  The author hopes you enjoyed reading it's documentation and that you will enjoy much more using his product.

  Copyright (c) Dr Baptiste Marcel 2002, 2003 and later.
This programms is freeware, you can modify and/or distribute them under the term of the GNU General Public License version 2 or later. It comes with no warranty of any sort. Refer to www.gnu.org/copyleft/gpl.html for the full text of the GNU GPL.

  Always make sure you use the last version which is available at http://www.dunwich.org/soft
  Bug reports and feature requests should be sent to author at baptiste@dunwich.org.
  Refer to http://www.dunwich.org for more contact information about the author.
  
  Product Albagtor, Library albalib.pl version 6.60
  Script albagtor.pl version 1.51