Copyright: Jedd Rashbrooke, 2011.

Released under the GPL v2 or later at your preference.


Contents:
	1.  Overview
	2.  Prerequisites
	3.  Installation and configuration
	4.  Usage / workflow

1. Overview

	Phoko is a PHP / web application that is useful if (and only if)
	you currently use KPhotoAlbum to manage your photo collection, and
	want an easy way of publishing some of your photos to the web.

	To be crystal clear - if you don't use KPhotoAlbum, this isn't
	of any use to you at all.  Seriously.  None.

	Phoko is a display-only gallery.  There are no facilities to add
	tags, change image information, or for users to add comments.


2.  Prerequisites
	
	KDE's KPhotoAlbum application ( http://www.kphotoalbum.org/ ).  
	As above, this is the tagging and management system that Phoko 
	relies upon.  

	Apache/PHP, with php5 modules for imagick, gd (at least).


3.  Installation and configuration

3.1 Grab the software


	Best way is using git, as described on the project web site.
	Go into your web root, and then run:

		git clone [email protected]:jedd/phoko.git

	You can later update with 'git pull', of course.

3.2 Set up the cache sub-directories.

	We need some world (or at least apache-user) writable
	directories - at the moment the former is easier, so:

		cd phoko
		./mkcachedir.sh

3.3 Fix up .htaccess

	I apologies for this - it's a bizarre CodeIgniter-ism 
	that I haven't worked out yet.  The .htaccess has, on
	the last line, the path that I use.  We need a .htaccess 
	to get rid of CI's 'index.php' that would otherwise 
	appear in every URL.

	You just need to edit that last line of .htaccess 

	It's currently set to:
	   	RewriteRule ^(.*)$ /~jedd/phoko/index.php/$1 [L]

	If you are not using a ~/user/ directory under Apache,
	then this line usuall works just fine - so try this first:
		RewriteRule ^(.*)$ ./index.php/$1 [L]

3.4 Configure the configuration file

	Pretty much all the useful configuration stuff is done in
		phoko/app/config/phoko.php

	It is *heavily* documented inline, so just work through it
	and change the things it says desperately need changing,
	and try not to change the things that it says will likely
	break if you sneeze near them.

	The really important things are:
		repository - where it can find your KPA index.xml basically
		publish_keyword - the magic tag that will publish an image
		category_abbreviations - IFF you have custom categories
		shoosh_tags - if you want to hide any tags

	And that should be it at this end - you should be able to
	see it in your web browser, though it will be empty until
	you've added the publish_keyword (as above) to a few of
	the images in your KPhotoAlbum collection *and* saved.


4.  Usage / workflow

4.1 Basic usage

	Go into KPhotoAlbum and tag a few images with your nominated
	tag ($publish_keyword, as defined in config/phoko.php) and
	then browse to your URL, and wait for the server to thumbnail
	the first 7 images, and generate a medium-sized version of
	your first image.

4.2 Showing your gallery on a box that doesn't contain your images

	This is how I use the application mostly - though on my dev
	machine (my main desktop) of course I have the full set of 
	images.  I add the PUBLISH tag to images, then browse to the
	localhost's phoko site, click through to make sure they look
	okay, and then do an 'rsync -av --delete' of the project dir
	to my web server(s).  This means that on my web server, there
	is no requirement to have my full gallery collection (about
	70GB, so not really feasible to reproduce everywhere).

	On the web interface, in the footer, far right, there is also
	a Cache Management link.  This will give some stats on number
	of images - small and large - and any extra images that are no
	longer part of the PUBLISH set.  There's also a link in that
	page to create any out-standing cache files, and clean up the
	extras.  It's worth doing this before you do the rsync, so you
	can be sure you've got all the thumbs and cached images actually
	present.

4.3 Customising the 'how to use this gallery' image

	I've shipped my how_to_use_this_gallery.xcf - a GIMP native
	format file that has two layers - one showing the arrows and
	text describing what's what, and the other is the actual
	screen shot of a gallery page.

	You can easily make your own screen shot, adjust to size, then
	layer that into the GIMP image, adjust any text as you see
	fit, and then export that as the how_to_use_this_gallery.png
	files into the theme/ subdirectories.


5.  Problems, bugs, feature requests, words of praise?

	You can hit the project page to find out how to contact me,
	if you have any problems or suggestions on ways of improving
	this documentation or the application.