===============
- pynakotheka -
===============

:Author: Iigo Serna, inigoserna AT gmail DOT com

:Version: 1.1.0, February 25th., 2007

:License: \(C\) 2005-7, Iigo Serna

          This software has been released under the `GPL License`_,
          see the COPYING_ file that comes with this package.
          There is NO WARRANTY.

:Last update: Sun Feb 25 01:36:51 2007

.. contents:: Table of Contents


Introduction
============
Not much to say, **pynakotheka** is a simple python script which generates 
static HTML photo albums to be added to web sites or to be burnt in CDs.

The gallery can contain folders and/or pictures
and the folders can contain other folders and/or pictures, recursively. 
There are 4 views: folder, tree, thumbnails and photo detail (with or 
without exif info). You can even create your own templates easily.

Released under GNU Public License, read COPYING for more details.

Some inspiration from curator_, another python gallery builder.

Here you have a `demo site`_ with some photos of my friends.


You don't need to install the script, uncompress the package and
select the proper path of the templates when executing the program.
Anyway, since v1.0.1 you can use the usual python process to install 
*pynakotheka* and let the program to find out where the templates are
located::

  # python setup.py install


These are the options:

::

  Usage:  pynakotheka.py <options> [source_dir [target_dir]]

  Arguments:
      source_dir       Location of the source photos, defaults to current dir
      target_dir       Directory where to save the gallery, defaults to current dir

  Options:
      -h, --help       Show this text
      -v, --version    Show version and exit
      -q, --quiet      Don't show progress information messages, default SHOW
      -c, --color      Show information messages with colors, default NO COLOR

      -o, --copy-originals
                       Copy original images to the gallery, default NO
      -s, --thumbsize  Thumbnail size, defaults to 250
      -i, --imagesize  Image size, defaults to 640
      -d, --templates-dir
                       Path to templates directory, defaults to 
		       "$PREFIX/share/pynakotheka/templates"
      -t, --template   Template to use, defaults to "default"

      --clean=all|images|html
                       Remove all files / images / html and style files
                       generated by the program


Templates
=========
Each template has his own directory which **must** contain exactly these 7 files:

- *view_albums.tmpl*: html template for the album view
- *view_tree.tmpl*: html template for the tree view
- *view_thumbs.tmpl*: html template for the thumbnails view
- *view_image.tmpl*: html template for the image detail view
- *style.css*: cascading style sheet
- *background.jpeg*: background image
- *transparent_black.gif*: image

All of these files must exist in your template directory. If you don't need 
any of them, create an empty file anyway (yes, this could be improved).

The name of the template is taken from the directory name.

 
There are only three templates by now:

- *default*: nice and elegant look with exif information and previous and
  next images preview
- *noexif*: similar to *default* but without exif information
- *simple*: you see, no colors, no css, no background

Thanks to http://wancam.precompiled.org/tdigs and 
http://photolib.sourceforge.net from which I've taken some ideas and html code 
for these templates.

If you design a new template, please contribute back to the community. Thanks.


Album folder description file
=============================
You can specify some information for each folder.

To do it, create a file called *album.xml* and place it in the base directory
for the folder. This is the example included with *pynakotheka* (if you have
installed the program you can find it in */usr/share/doc/pynakotheka*)::

  <?xml version="1.0" encoding="utf-8"?>
  <album>
    <title>
      This is the title
    </title>
    <description>
      These photos were taken during our holidays in Mars last October
    </description>
    <sample_photo>
      path/to/photo1.jpeg
    </sample_photo>
    <omit_album>
      FALSE
    </omit_album>
    <omitted_files>
      <omitted_file>
        photo12.jpeg
      </omitted_file>
      <omitted_file>
        photo26.jpeg
      </omitted_file>
    </omitted_files>
  </album>

- the first line sets the *encoding* for the file
- *title*: the name for the folder, instead of directory name
- *description*: summary for the folder contents
- *sample_photo*: path to the image you want as sample for this folder
- *omit_album*: either TRUE or FALSE. If you want *pynakotheka* not to
  include this directory in the gallery set it to TRUE
- *omitted_files*: list of photos to be omitted


Requirements and Download
=========================
- pynakotheka_, you can download it from here_
- Python_
- `Python Imaging Library`_
- EXIF_ 
- `Mako Templates`_


FAQ
===
**Q: Didn't pynakotheka use Cheetah Templates before?**

A: Yes, but since v1.1.0 pynakotheka uses `Mako Templates`_
It's much faster and manages utf-8 encodings in an easier way.

**Q: It's a bit slow... what can I do?**

A: Since v1.1.0 generating html pages is quite fast, so the only slowness comes
from images manipulation, but there is nothing to do to speed it up.
You can also generate the gallery after going to sleep after all.

**Q: How can I disable exif information in my gallery?**

A: Use the *noexif* template.

**Q: pynakotheka crashes when using a template without "background.jpeg" file**

A: File must exist. See Templates_ section.


CHANGES
=======
Changes from v1.0.3 to v1.1.0:

  - use *Mako Templates* instead of *Cheetah Templating System*
  - file names encoded in UTF8 works ok now, or so I hope
  - added a *"--version"* option

Changes from v1.0.2 to v1.0.3:

  - support file names encoded in UTF8

Changes from v1.0.1 to v1.0.2:

  - now albums are sorted by creation time

Changes from v1.0 to v1.0.1:

  - distutils support. Now you can install *pynakotheka* in your system
  - added a man page
  - fixed some typos in templates


TODO
====

Alex Greif:

1) [**FIXED**]
I have found the following bug:
if I run pynakotheka on windows and have nested folders with pictures,
then the image tag contains backslashes. This makes problems if I ftp
the html files on a unix server. here is a sample of the bad generated
code with the nested folder "NeuerOrdner"::

   <a href="NeuerOrdner/index.html">
     <img src="NeuerOrdner\image_a6xdow-150.jpeg" alt="image" border="1">
   </a>
   
   The image tag should have a forward slash as
   <img src="NeuerOrdner/image_a6xdow-150.jpeg" alt="image" border="1">
   
2) [**DONE**]
a --version command line option would be good, to check which version
is currrently installed
   
3)
it would be good to mention the way how to upgrade to a newer version
on the homepage:
easy_install -U pynakotheka


Post v1.0 ideas:
  
  - more templates
  - define schema for templates: template.index
  - comments for photos

Rejected ideas:

  - add text/watermark to images, let specify font and size
    Shane Hathaway and Terry Carroll "Watermark with PIL"
    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/362879
  - add a shadow or other effects to the photos
  - option to disable exif: use template with no exif info


---------------------------------------------------------------


[This documentation was generated with `reStructuredText`_]


.. _pynakotheka: http://inigo.katxi.org/devel/pynakotheka
.. _here: ./pynakotheka-1.1.0.tar.gz
.. _`demo site`: http://gallery.katxi.org/katxi
.. _Python: http://www.python.org
.. _`Python Imaging Library`: http://www.pythonware.com/products/pil/
.. _`Mako Templates`: http://www.makotemplates.org/
.. _EXIF: http://home.cfl.rr.com/genecash/digital_camera.html

.. _curator: http://curator.sourceforge.net

.. _COPYING: COPYING
.. _`GPL License`: http://www.gnu.org/licenses/licenses.html#GPL
.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
