Script generator

Generate HTML image gallery pages.

Curator is a powerful script that allows one to generate Web page image
galleries with the intent of displaying photographic images on the Web, or for a
CD-ROM presentation and archiving. It generates static Web pages only - no
special configuration or running scripts are required on the server. The script
supports many file formats, hierarchical directories, thumbnail generation and
update, per-image description file with any attributes, and 'tracks' of images
spanning multiple directories. The templates consist of HTML with embedded
Python. Running this script only requires a recent Python interpreter (version 2
or more) and the ImageMagick tools.

All links it generates are relative links, so that the pages can be moved or
copied to different media. Each image page and directory can be associated any
set of attributes which become available from the template (this way you can
implement descriptions, conversion code, camera settings, and more).

You can find the latest version at http://curator.sourceforge.net


Input
------------------------------

The image files need to be organized in a directory structure.

For each image, the following is required:

 - <image>.<ext>: the main image file to be displayed in the html page, where
   <ext> is an image extension (e.g. jpg, gif, etc.)

The following is optional, and will be used if present:

 - <image>.desc: a per-image description file containing user-provided
   attributes about the photograph.  The format is, e.g.:

          <attribute-name>: <text>
          <text>
          <text>

          <attribute-name>: <text>
          ...

   Each attribute text is ended with a blank line.  You can inclue all the
   attribute fields you want, it is up to the template file to access them or
   not. There are, however, some special predefined attributes:

        - title: A descriptive title for the image (a short one liner).

        - tracks: <trackname1> <trackname2> ...
          specifies the tracks that the image is part of

        - ignore: yes
          specifies that the image should be ignored

 - <image>--<string>.<ext>: alternative representations of the image. Could be
   the original scan plate, or alternative resolutions, or anything else related
   to this image.  The image html page can add links to these alternative
   representations. We assume that we only need to generate an HTML page for the
   main resolution (i.e. smaller resolutions won't have associated web pages)

To configure the generated HTML files, use --save-templates and modify the code
that will appear in the output directory.

The following files can be put in the root:

 - template-image.html: template for image HTML file
 - template-allindex.html: template for global index HTML file
 - template-dirindex.html: template for directory index HTML file
 - template-trackindex.html: template for track index HTML file
 - template-sortindex.html: template for sorted index HTML file

The template is a normal HTML file, the way you like it, except that it contains
certain special tags that get evaluated by the script in a special environment
nwhich contains useful variables and functions.  You can use the following two
tags:

<!--tagcode:
print 'some python code',
for i in images:
        print 'bla'
-->

<!--tag:title-->

The second tag is implemented as 'print <tag contents>,'. You can put
definitions, function calls, whatever you like.  Variable bindings and
definitions will remain between tags.

The templates are looked up in the following order:
 - user-specified path (-templates option)
 - the root of the hierarchy
 - the dir specified in the env var CURATOR_TEMPLATE

If not found, simple fallback templates are used. Remember that under unix,
processing python code with carriage returns will fail the python interpreter
with a Syntax Error.

For a complete description of the environment, look at the code.


Output
------------------------------

Note by default nothing that already exists is overwritten. Use the --no* or
--force* options to disable or force thumbnails, indexes and image pages.
Directories which do not contain images (and whose subdirectories do not contain
images) will be ignored.

For each image:

 - <image>--thumb.<ext>: associated image thumbnail.

 - <image>.html
   (for each image, an associated web page which features it)

Thus you will end up with the following files for each image:

 - <image>.<ext>
 - <image>.desc
 - <image>--<string>.<ext>
 - <image>--<string>.<ext>
 - ...
 - <image>--thumb.<ext>
 - <image>.html

In each subdirectory of the root:

 - dirindex.html: an HTML index of the directory, with thumbnails and
   titles.

In the root:

 - trackindex-<track>.html: for each track, an HTML index of the track, with
   thumbnails and titles.

 - allindex.cidx: a text index of all the pictures, with image filenames and
   titles, each on a single line.

 - allindex.html: an HTML index of all the pictures, with thumbnails and titles,
   and list of tracks.

 - sortindex.html: an HTML index of all the pictures, with some form of sorting
   This output can be used as a global index for sorting images by
   name/date/whatever.  The images in the author's photo gallery are named
   by date so sorting by name is sorting by date, which the default template
   implements.


Usage:
------------------------------
  curator <options> [<root>]

If <root> is not specified, we assume cwd is the root.