cthumb - a themable web picture album generator
===============================================

	Home Page:	http://cthumb.sourceforge.net/
	Project Page:	http://sourceforge.net/projects/cthumb/

	Ideas and contributions: cthumb-devel@nospam.lists.sourceforge.net

Quick Intro
===========

suppose you have some pictures in a directory, say *.jpg. to
get going quickly, you do this:

	bash$ cthumb -c *.jpg > starter.album
	bash$ mkdir thumb/
	bash$ cthumb starter.album
	bash$ vi starter.album
	      (edit at will)
	bash$ cthumb starter.album
	      (view)
	bash$ vi starter.album
	      (edit at will)
	bash$ cthumb starter.album
	      (view)
	bash$ ...etc., releat until you are happy with the result

Introduction
============

You have a digital camera. You have lots of pictures. You have family
and friends who speak, say, two languages, but not both. This program
was written because I urgently needed to organize my online pictures
in a sane manner and wanted two sets of friends to enjoy them, with
captions in their own languages. See an example in

	Home Page:	http://cthumb.sourceforge.net/
	Project Page:	http://sourceforge.net/projects/cthumb/

cthumb is a command-line program that allows you to create an web
picture album, with an index and several pages, each with thumbnails
of your pictures. It optionally generates otherwise identical pages
but in several languages, simultaneously. It automatically generates
thumbnails of the pictures. It attempts to be nice in the look of the
pages it generates.

It is geared towards people that have ton of digital images that need
to be labeled, grouped, captioned and sorted out. All you need is the
pictures and a text editor to put all the captions for the picture in
a simple "album" textfile.


The .album Input Files
======================

The "input file" for cthumb is called an "album file", something like
"trip-to-cancun.album" which is a simple text file, formatted in a
very simple way. You invoke cthumb with that album file and it
generates HTML pages with the contents of the web album:

	bash$ cthumb trip-to-cancun.album
	cthumb 3.2, running in ....
		generating thumbnail for cancun1.jpg ... done.
		generating thumbnail for cancun2.jpg ... done.
		generating thumbnail for cancun3.jpg ... done.
		generating thumbnail for cancun4.jpg ... done.
	Creating page:	page-1.shtml
	Creating page:	page-2.shtml
	Index for trip-to-cancun.album in: trip-to-cancun-index.shtml
	bash$ 

Now, "how do I come up with the '.album' file?", you are probably
wondering...

Rather than explaining the format for .album files here, we can
actually use cthumb for generating default-looking album files for a
bunch of pictures, which you can modify to put your captions and make
it look like you want.

cthumb actually has two modes of operation: "Album creation mode" and
"Regular mode". With the album creation mode you can come up with a
.album file, then tweak it, add the captions you want, and then, using
cthumb in regular mode, you can create a web album from the .album
file. The purpose of the first phase is to avoid having to write the
whole .album file by hand.

1.- Album Creation Mode
-----------------------

You could write a .album file by hand, but cthumb can help you
come up with one to work with automatically, given your pictures.

To create a default-looking album file, you can use the -c command
line option, which asks cthumb to run in album creation mode, followed
by the files you want displayed in the album. The resulting album file
is sent via the standard output. e.g.:

	bash$ cthumb -c *.gif *.jpg *.png > trip-to-cancun.album
	bash$

now, you can inspect and hack the trip-to-cancun.album, which is a
text file with a sime format and go from there.

2.- Regular Mode
----------------

When you are happy, and from then on, you then generate the HTML with
the actual web album:

	bash$ cthumb trip-to-cancun.album
	...
	bash$ <edit trip-to-cancun.album>
	bash$ cthumb trip-to-cancun.album
	...
	bash$ edit again ... repeat..

Where to put the Images and Thumbnails
======================================

Given an image called, say,

	cancun1.jpg

a thumbnail called

	cancun1-thumb.jpg

would be generated in the same directory that the image is in. If
a directory called "thumb" exists, then it is placed inside
that directory:

	thumb/cancun1-thumb.jpg

Note that you can group images in directories (with thumb/
subdirectories optionally in each one). e.g. you can have
images listed in the album file as:

	001205-cancun-trip/cancun1.jpg

and the thumbnail will be:

	001205-cancun-trip/cancun1-thumb.jpg

(or 001205-cancun-trip/thumb/cancun1-thumb.jpg if thumb/ exists).

Usage note: option -t will force cthumb to look at the tumbnails's
width and height and generate html IMG references that contain
HEIGHT=... and WIDTH=....  The purpose of this is that for large and
very large pages, knowing this information makes the rendering of the
thumbnail pages much faster. It makes cthumb much slower, because it
has to open and parse each and every thumbnail. This is a reasonable
step for the final pass before making the web pages available for a
while.

The .album Format
=================

To go a bit in detail, lines starting with a "#" are comments. Empty
lines are generally ignored.

Note that empty lines are ignored, unless they are following the Page
or filename lines (in which case the title of the page or caption of
the picture will be empty).

Notice that cthumb only generates html files that are needed,
i.e. pages that would be generated identical to existing pages are not
re-generated (to avoid unnecessary html cache reloads). Same thing
with images and thumbnails. See the example included, along with
pictures.

cthumb options and the ~/.cthumbrc file
=======================================

cthumb takes options in three possible ways, with this priority (most
first):

	command line flags	- at run time
	album file		- each album file its own 
	~/.cthumbrc		- personal to a user
	cthumb script		- defaults across users

For a list of command line options, invoke

	cthumb -h

The syntax in the album files can be gleaned from the sample album
file or from an album generated with the -c flag.

The syntax for the cthumbrc is that of Perl. The variables you can put
in there are these below (listed at the top of the cthumb script), and
listed here with their defaults at the time of writing this README
file. check the top of the cthumb script to see (or change) the
defaults:

	@Languages = ("English", "Espaol", "Valencian");
	$NLanguages = 3;    		# default number of "languages" to use

So, for example, you could have:

	bash$ cat ~/.cthumbrc
	$PicturesPerRow = 6;
	$Theme = neat-round
	bash$

to generate .album files or create web albums with 6 pictures per row.

Finally, note that when cthumb is invoked with -c to create an album,
it picks up the settings from ~/.cthumbrc because there is no album as
input. BTW, the -c option is only available in command line mode,
obviously.

Headers and Footers
===================

HTML files generated are now with the extension ".shtml". What this
does is allow server-side includes to happen. cthumb now autodetects a
header.html and footer.html file for all pages generated. If a header
(or footer) is detected when cthumb is run, a server-side include is
generated that includes the header at the top of the file and the
footer at the bottom. Files having includes have to be ".shtml".
Works on my default Linux/apache setting.

Starting in version 3.5.2, headers and footers can be inlined with the
InlineFiles. The motivation is that some ISPs do not provide server
side includes, so the header/footer feature with server side includes
cannot be used.

This new feature allows to inline the header/footer file instead of
using a server side include. One can use it from the command line or
from inside an album file or a ~/.cthumbrc

 - command line parameter "cthumb -s <dir>"
 - album file variable:

	InlineFiles: <dir>

It checks the given directory for header.html and footer.html and
includes their content instead of the server side include directive.

Automatic Slide Shows
=====================

To turn on automatic generation of slide shows, either turn

   AutoSlideShow: 1

in the album, or set AutoSlideShow 1 in your ~/.cthumbrc, or in the script, etc.
This makes automatic slide shows that change image every few seconds.

Picture Captions
===============

The album file allows one line of caption per language per picture, which
looks like this:

        - image001.jpg
                This is my first language
                This is my second language

        - image002.jpg
                ...

To annotate a picture with an additional longer text, create a text file in
the same directory as the picture file with the following schema:

	picturename.language

Using the example above, the name would be "image001.jpg.english", if
the first language is English. Please note, that the language is
always in lower case. To activate this feature, use the following
setting: StoryOn=1

Requirements
============

This program requires:
	
	perl, with the following:
		use URI::Escape;
		use HTML::Entities;
		use IO::Handle;
		use POSIX;
		use Getopt::Std;
	djpeg, cjpeg	(rpm: libjpeg-*.rpm)
	pnmscale	(rpm: libgr-progs-*.rpm)

Installing the Perl Modules
===========================

This is hard to do, unfortunately.

The perl modules are available in the project web page, however, here
are some instructions on how to use CPAN from the command line. This
would get you the latest (I *have* tried this myself and it works):

	bash$ perl -MCPAN -e shell
	shell> install HTML::Parser

Now, if you are like me, you don't like to do things like root or to
install things on top of rpms, screwing with your dependencies. I install
this modules in /opt/perl-modules, where I have permission as a user:

	bash$ echo $PERL5LIB
	/opt/perl-modules/lib/site_perl
	bash$

after running the perl -MCPAN -e shell once, you need to add these lines
to your ~/.cpan/CPAN/MyConfig.pm file:

'makepl_arg' => q[LIB=/opt/perl-modules/lib/site_perl
            INSTALLMAN1DIR=/opt/perl-modules/lib/site_perl/man/man1
            INSTALLMAN3DIR=/opt/perl-modules/lib/site_perl/man/man3],

all in one line. in my case, an empty line (just q[]) was there for
makepl_arg, so just add it there. All this, courtesy of Alexander Kourakos,
thanks!

CVS INFO
========

Get the directions at sourceforge on how to check out the latest
and greatest from the sourceforge server at:

	http://sourceforge.net/projects/cthumb/

In essence, you can checkout the sources this way:

	cvs -d:pserver:anonymous@cvs.cthumb.sourceforge.net:/cvsroot/cthumb login
	  (when prompted for a password for anonymous, simply press the Enter key)
	cvs -z3 -d:pserver:anonymous@cvs.cthumb.sourceforge.net:/cvsroot/cthumb co cthumb
	cvs -z3 -d:pserver:anonymous@cvs.cthumb.sourceforge.net:/cvsroot/cthumb co cthumb-examples

HOW TO HELP
===========

If you have some suggestions and improvements, please checkout the
latest cvs version and do a

	cvs diff -cN > your.diff

and then _attach_ the file your.diff to
cthumb-devel@lists.sourceforge.net for discussion.

Show me the code!! :-)

License
=======

This program is released under the GNU GPL license, v2.0 or later.
http://www.gnu.org/copyleft/gpl.html

(C) 1999-2002, Carlos Puchol, cpg+cthumb@nospam.puchol.com

	Home Page:	http://cthumb.sourceforge.net/
	Project Page:	http://sourceforge.net/projects/cthumb/