Release 0.99.2v0.99.2v0.99.2

1 files changed, 71 insertions, 23 deletions

diff --git a/README b/README
index f00b9e4..3597b3e 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ CATARACT
 Static web photo gallery generator
 http://cgg.bzatek.net/
 
-version 0.99.2 [2009-02-26]
+version 0.99.2 [2009-03-28]
 Copyright (C) 2008-2009 Tomas Bzatek <tbzatek@users.sourceforge.net>
 
 
@@ -14,36 +14,38 @@ gallery, designed to be clean and easily usable. Due to the 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
-  *  console application, allowing easy scripting 
-     (e.g. auto-refresh after new images are uploaded via FTP)
+  * static HTML gallery, no extra requirements on the server
+  * fast, easy to cache/mirror
+  * XML-based description files
+  * modern design, valid XHTML 1.0 and CSS 2
+  * EXIF & IPTC support
+  * console application, allowing easy scripting
+    (e.g. auto-refresh after new images are uploaded via FTP)
+  * licensed under GNU GPLv2 license
 
 Planned features:
-  *  autotoolize
-  *  optional pushing comments and captions to images
-  *  switchable flat album view
-  *  slideshow mode
-  *  switchable styles
-  *  jBrout db support?
-  *  stars rating system (iframed php script?)
+  * GraphicsMagick port
+  * job parallelization
+  * optional pushing comments and captions to images
+  * switchable flat album view
+  * slideshow mode
+  * 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 
+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 
+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.sh script, which creates 
-an index XML template from images in current directory. That can be used 
+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
@@ -51,16 +53,62 @@ 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.2)
-  glib-2.0    (2.12.0 recommented, tested with 2.18.3)
+  glib-2.0    (2.16.0 recommented, tested with 2.18.3)
   exiv2       (tested with 0.17.1)
   ImageMagick (tested with 6.4.5.7)
 
-To compile cgg, type 'make'
+Please refer to standard instructions in the INSTALL file.
 
 
 DEVELOPMENT