CATARACT
Static web photo gallery generator
http://cgg.bzatek.net/

version 1.1.0 [2010-12-05]
Copyright (C) 2008-2010 Tomas Bzatek <tbzatek@users.sourceforge.net>

See NEWS for brief list of changes


DESCRIPTION
-----------

This is the CGG, Cataract Gallery Generator - a simple static web photo
gallery, designed to be clean and easily usable. Due to its static design,
there's no way to comment pictures on the web.

Feature highlights:
  * static HTML gallery, no extra requirements on server
  * fast, easy to cache/mirror
  * XML-based description files
  * modern design, valid XHTML 1.0 and CSS 2
  * EXIF & IPTC support
  * Atom feed writer
  * multithreaded console application allowing easy scripting
    (e.g. auto-refresh after new images are uploaded via FTP)
  * licensed under GNU GPLv2 license

Planned features:
  * GraphicsMagick port
  * optional pushing comments and captions to images
  * switchable flat album view
  * slideshow mode
  * mobile/lite version
  * switchable styles
  * jBrout db support?
  * stars rating system (iframed php script?)


DOCUMENTATION
-------------

CGG creates a set of HTML files and images from the source structure.
Input files are structured in subdirectories, each directory may contain
only one index XML file and the generated directory tree copies the source
structure. All links to sub-galleries, items, descriptions and individual
settings are specified in XML files. No more files other than global setup
XML file are needed.

For convenience, sources contain the cgg-dirgen script, which creates
an index XML template from images in current directory. That can be used
as a skeleton of new album, writing down title, description and comments.

For detailed syntax of input XML files please check the sample gallery included
in the source tree. It demonstrates basic features and contains detailed tag
description inside the XML files.


ENTITIES
--------

 * As a general rule, all nested tags have to be surrounded by the CDATA block,
   e.g. <![CDATA[<b>text</b>]]>
 * It's strongly discouraged to use named entities like &lt; or &gt; outside
   the CDATA block as the XML parser will unescape them to < and > automatically
   which might lead to validation troubles. Some other commonly-used 
   HTML entities like &copy; are unknown to the XML parser and will throw an error.
 * Lonely ampersands (forgotten or inside a URL) get escaped automatically 
   for the safety. Opening ampersands in entities are left untouched of course.


VALIDATION
----------

For easy validation of single files you can use well-known W3C Markup Validator.
For automated validation of series of files it's better to use command-line tools
like xmllint, which is a part of the libxml2 suite, also heavily used in cataract.

Using xmllint we can easily validate all html files in the current
directory structure:

for i in `find -regex '.*html$'`; do (echo "=================== $i"; xmllint --valid --noout $i); done

This will automatically download linked DTD schema (XHTML 1.0 Strict in this case)
as defined in the XML header. Processing large number of files might be inconvenient
and you may want to use locally cached schemes. Running

XML_DEBUG_CATALOG="1" xmllint --valid --noout <file.html>

will tell you which schema files are needed. Then just create local catalog file,
as described on the Wikipedia XML Catalog page:

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
                  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
    <public publicId="-//W3C//DTD XHTML 1.0 Strict//EN" uri="xhtml1-strict.dtd"/>
</catalog>

and pass it as XML_CATALOG_FILES variable:

XML_CATALOG_FILES="catalog.xml" xmllint --valid --noout <file.html>


BUILDING
--------

First make sure you have met the following requirements:
  libxml-2.0  (tested with 2.7.7)
  glib-2.0    (2.16.0 recommented, tested with 2.26.0)
  exiv2       (tested with 0.20)
  ImageMagick (tested with 6.6.5.6)

Please refer to standard instructions in the INSTALL file.


DEVELOPMENT
-----------

gitweb: http://git.bzatek.net/?p=cataract;a=summary
repository snapshot command:
  git clone git://git.bzatek.net/cataract

For write access to the repository please contact developers.
Feel free to send any patches, we'll review them and commit if suitable.


LICENSE
-------

Please see 'COPYING'
