see the README for warnings about the instability of this code and the
fact that it's probably not ready for use outside my own private
server.

that said, here's a first stab at a document explaining how to install
and setup the thraxil engine.

REQUIREMENTS:

1)	a unix platform. thraxil has been tested on redhat and
	mandrake linux. should work on any similar platform though.

2)	perl 5.6.1

3)      apache. probably any release from the last couple years. Thraxil
        has not been tested under mod_perl (and i wouldn't expect it
        to work without some modifications).

4)	you must have a web accessible directory that maps .pl files to 
	perl. ie, "AddHandler cgi-script .pl" must be added to the proper 
	location in the httpd.conf file.

5)	the following perl modules are required:
	- HTML::Template
	- DBI
	- DBD::Pg
	- File::NCopy
	- HTML::TagFilter
	- XML::Simple

	DBI::Pg may require some special attention when
	installing. other than that, most of the modules can be
	installed by running (as root):

	# perl -MCPAN -e 'install Some::Module'

6)	postgreSQL 7+. depending on the exact version, some tweaks of the
	SQL may be required. 7.2 is recommended.

7)	you're definately going to need shell access to get it set up. 

8)	the ImageMagick software suite. see: http://www.imagemagick.org/
	in particular, the commandline tools 'identify', 'mogrify', and 
	'convert' that it gives you need to be available.

PROCEDURE:

1)	download the source code tarball
	http://thraxil.dhs.org/code/current.tar.gz

2)	place it in the web accessible directory where you want 
	it to live.

3)	take this opportunity to back up EVERYTHING else in that 
	directory. it would suck if you accidently overwrote 
	something important when you unpack it.

4)	unpack the tarball:  
	from in that directory, do
	$ tar zxvf thraxil_current.tar.gz

	this will dump a bunch of stuff into the directory you're in. 
	all the perl scripts, the modules, the templates, the sql and 
	install scripts.

5)	move the file 'thraxil_config.xml' to whatever location on
	the filesystem you want. the only restriction is that it must
	be readable by the user that the web server runs as. it's
	probably a good idea to move it somewhere outside the web root
	since it will contain the password to your database.

6)	edit Thraxil.pm and set the variable $CONFIG_FILE to the 
	full path of where you put the thraxil_config.xml file.

7)      at this point, you need to know the username and password
	for the postgres user that the scripts will be connecting 
	to the database as.

	i would recommend creating a postgres account specifically for
	thraxil to use. it will need permission to create new databases
	and to do add/delete/update/select stuff but doesn't need the
	ability to add users. how to do this is outside the scope of this
	document but should be pretty easy to figure out from the postgres
	docs.

	edit the config file ('thraxil_config.xml') and specify the
	database username and password.

	if your database is secured from the outside world, i'd
	recommend creating the thraxil user with no password (the
	default if you use the createuser command) as this simplifies
	the installation process. after installation you can set a 
	password.

8)	set permissions. those directories that you just created
	need to be writable by the user that the webserver runs as. 
	the recommended way to do this is to have root chown them 
	to the right user (usually 'nobody'). ie,
	
	# chown nobody:nobody thraxil_uploads thraxil_uploads/thumbs \
          user_cache users

	if you don't have root access, you can probably get away with 
	just doing: 
	
	$ chmod a+w thraxil_uploads thraxil_uploads/thumbs \
          user_cache users

	this is only recommended on a server where you trust all the
	other users with access to the box. 

9)	specify some paths. edit the config file to specify the 
	web base, and full paths for some utilities (identify,
	convert, mogrify, grep, etc).

	to point to the correct locations on your system. the web base
	should be the current directory (where everything was unpacked).
	use the 'which' command to locate the correct paths for the three
	executables. ie, do 

	$ which identify
	/usr/bin/identify

	etc.

10)	bootstrap the system. do this with the bootstrap script. the
	bootstrap script creates the necessary database structure and
	adds a default user for you to start with. WARNING! this
	script will remove any existing databases named 'thraxil' that
	it finds. that means that you should ONLY run the bootstrap
	script on a virgin system. if you run the bootstrap script
	after thraxil has been installed and used for a while, it will
	delete the database on you. that's not good.

	you must run this command from the directory where you
	unpacked the tarball. you'll need to specify the username of
	the database user you created as an argument. eg:

	$ perl scripts/bootstrap.pl anders

	it will ask you for a username, password and email address.
	this is for the default, seed user. this user is created with
	full posting permission and can be used to authorize other users.

	this script assumes that you created the database user with no
	password. if you gave it a password, the above will probably fail and
	you'll have to do the bootstrapping manually. it would basically go
	something like this:

	$ createdb thraxil -U thraxil_db_user
	$ psql -d thraxil -U thraxil_db_user < sql/thraxil.sql

	entering the password each time it asks for it. then you can
	run the bootstrap script again. it will give you some warning 
	messages at first but everything after creating a default user
	should be ok.

11)	set the diary template permissions for the default user. since the
	bootstrap script was most likely run as a regular user and not by 
	the user that apache runs as, some permissions need to be corrected.
	in the users/ subdirectory, you'll see a directory named after the
	default user you created in the last step. you need to set permissions
	on this directory so the webserver's user can write to it. similar to 
	step 6, either chown as root or chmod a+w depending on whether you
	have root access and whether you trust the other users on your system.

	eg,
	
	# chown nobody:nobody -R users/default_user/
	
	or 

	$ chmod a+w -R users/default_user

12)	now you should be set. load the index.pl page in a browser, log in 
	as the seed user and start playing. you'll want to edit the 
	template files in the templates/default/ and skel/
	directories to customize the site. read the documentation for 
	the HTML::Template module for an explanation of the template 
	syntax. i'll try to get around to documenting exactly what
	info is available to you from the templates at some point. for
	now, most things should be fairly intuitive from looking at
	the existing templates.

13) 	if you've made it this far, congratulations. you now have your
	own version of the thraxil weblog engine running. you are officially
	the coolest kid on the block.

# TODO: explain about migration from other formats. templates.