******************************************************************************
* WORDPRESS TO MINDTOUCH DEKI POST SYNCHRONIZATION PLUGIN
*
* Authors: Roy Kim (royk@mindtouch.com), Karen Ananiev (karena@mindtouch.com)
* Version: 1.0
* Last updated: July 12th, 2008
* 
******************************************************************************

TABLE OF CONTENTS
	1. Introduction
	2. Requirements
	3. Installation
	4. Usage
	5. Caveats
	6. Credits
	7. Todos

------------------------------------------------------------------------------
INTRODUCTION

You have, in your hands, a WordPress plugin which will keep all your WordPress 
(WP) posts synchronized with a MindTouch Deki install. New WP posts will be 
created into a configurable location in your Deki, and subsequent updates to 
the WP entries will also keep the Deki pages synchronized. Moving your WP 
post (by changing the URL) will also move the Deki page, and deletions in 
WP are also respected by Deki. 

The goal of this plugin is to allow a couple use cases:
	(1) deeper collaboration on individual blog posts that are not afforded by 
		WP, but are a logical part of any wiki engine
	(2) content federation from scattered WordPress wikis into a single Deki 
		instance - this allows you to get a better broad overview of all posts 
		being created in your multiple WP installs and allows for innate Deki 
		features like searching
	(3) lays the groundwork for when Deki supports publishing hooks - once 
		Deki can effectively publish back to the WP installation that pushed 

------------------------------------------------------------------------------
REQUIREMENTS

You need a WordPress installation as well as a MindTouch Deki installation. 
If you do not have a Deki installation, you can get a free hosted Deki at 
http://wik.is/; otherwise you can download a copy for yourself at 
http://mindtouch.com/. If you do not have a WordPress installation, check out 
http://wordpress.com for hosted, and http://wordpress.org for a source 
download. 

Testing has only been done on Wordpress 2.5.1, but it should work as far back 
as WordPress 2.01. You will need a Deki instance running at least 8.05; 
earlier versions of Deki had a search bug which prohibits full usage of this 
plug-in (content creation will work, but subsequent synchronization fails). 

------------------------------------------------------------------------------
INSTALLATION

To install this plug-in, unzip the "mindtouch_deki" folder into the 
/wp-content/plugins/ folder of your WordPress installation. You will need to 
edit the mindtouch_deki.php file with your Deki information:

	DEKIHOST is the host name of your Deki's installation. If 
	you've gotten a Wik.is account, input something like: 

	mindtouch.wik.is
	
	DEKIUSERNAME/DEKIPASSWORD are the Deki account credentials used 
	to post content - I suggest you create a new user for this purpose. It 
	is *not* the WordPress account credentials!
	
	DEKIPATH is the location in Deki that all WordPress posts should be stored. 
	This can be overriden on a post-by-post basis. 

The WordPress server should be able to "see" the Deki installation - 
if the plug-in fails, check that first. You should be able to do a wget on 
http://{deki-host-name}/@api/deki/@about and receive a page which looks 
similar to http://wiki.developer.mindtouch.com/@api/deki/@about 

------------------------------------------------------------------------------
USAGE

If your installation was successful, the next time you publish publicly a WP 
post, the Deki should automatically pick up those changes. Subsequent edits 
and deletes will also synchronize, as well as URL changes. 

All categories and tags from a WP entry are collapsed into a single tag list 
for Deki; the plug-in will also respect custom tags which have been added to 
the page inside Deki. 

The Deki page will receive a few custom tags:

	wp-id:{int} is the Wordpress entry id; this is used to keep the Deki 
	entry associated with WordPress entry; if you ever wanted to "freeze" 
	the Deki page, simply remove this tag. 
	
	wp-from:{string} is the URL of the WordPress install. In the case that you 
	have multiple WP blogs pointing to the same Deki, there will be WP id 
	collisions; this allows the plug-in to know which page to affect. Being 
	a tag also allows you to identify inside Deki all the blog posts from a 
	given WordPress entry. 
	
	qp-author:{string} is the author name of the WordPress entry. Unless you are 
	running an account synchronization tool between WP and Deki, it's nearly 
	impossible to attribute Deki entries accurately. This data is here so that 
	later on, we can possibly merge them. If anything, it's usable metadata. 
	
If you want to re-target any individual WordPress entry to a different 
location in your Deki, use the "dekipath:{path as string}" tag in WP - this 
will override the DEKIPATH you set in your initial install. Note that if 
you attempt to target a location which already exists, and is not your WP 
entry, the save will fail. 

------------------------------------------------------------------------------
CAVEATS

Tags, when added in Deki, take up to 60 seconds to get into the search index, 
which is heavily used in this plug-in. This means that AFTER YOU CREATE A POST, 
SUBSEQUENT ACTIONS UNDERTAKEN BEFORE THE DEKI SEARCH INDEX CATCHES UP WILL 
CAUSE THE FAILURE OF THIS PLUG-IN. 

Be *sure* you wait for Deki to have successfully made the association or you'll 
end up with all sorts of problems. 

This should be resolved in future versions of Deki, where we'll update the 
tagging interface to be real-time instead of being delayed. 

------------------------------------------------------------------------------
CREDITS

This plug-in makes use of the Plug class, which Steve Bjorg ported over from 
C# and has been heavily bastardized by me (Roy Kim). The Result object wrapper 
comes from Guerric Sloan. 

On the off-chance that Australian actress Rose Byrne (Sunshine, 
28 Weeks Later, Wicker Park) is attempting to install this plugin, would you 
like to go out on a date with me?

And because it just rocks: http://icanhazcheeseburger.com

------------------------------------------------------------------------------
TODO

Here's a laundry list of things to do:
	
	1. Add hooks for WordPress' "Pages" as well (should be trivial)
	2. Add better explicit error messages for failed states - is there a way 
	   to do this cleanly in WordPress? (and appropriate i18n of the msgs)
	3. Also read and send attachments to posts as file attachments to Deki 
	4. Account synchronization (!)
	5. Add support for WordPress drafts - it should create a page, but use 
	   Deki's permissions to set to "Private" (this will probably require #5
	  
(if you'd like to help, email royk@mindtouch.com)

If you're interested in expanding this even further, please check out 
the MindTouch Deki Developer Center at http://developer.mindtouch.com; the 
wiki contains tons of documentation on all of Deki's features. 