add a README explaining how to install and run journal2webdav

It's in WikiCreole [1] format.

[1] http://wikicreole.org/

1 files changed, 99 insertions, 0 deletions

diff --git a/README.creole b/README.creole
new file mode 100644
index 0000000..8a390f5
--- /dev/null
+++ b/README.creole
@@ -0,0 +1,99 @@
+= journal2webdav =
+
+journal2webdav publishes content from the Sugar Journal (or rather from
+the underlying data store) via WebDAV.
+
+The content to be published can be adjusted by choosing a suitable data
+store query. Write access is currently not supported.
+
+
+== Dependencies ==
+
+On a system that's already running Sugar, you only need to install
+[[http://code.google.com/p/pywebdav/ pywebdav]]. It's available in
+Debian as python-webdav and in Fedora as pywebdav.
+
+
+== Installation ==
+
+You can use setup.py like for most other Python applications:
+
+{{{
+./setup.py install --user
+}}}
+
+
+== Running ==
+
+As journal2webdav connects to the Sugar data store, it needs to be run
+within a Sugar session (at least if you intend to run Sugar while
+journal2webdav is running). For trying it out, the easiest way is to
+invoke it from within the Terminal activity:
+
+{{{
+journal2webdav
+}}}
+
+You can start journal2webdav automatically with your Sugar session by
+placing it in {{{~/.sugar/debug}}}. That file isn't really intended for
+this kind of use, but it's the only thing that will currently work if
+you use {{{sugar-emulator}}}. If you're running Sugar as a regular X
+session, {{{~/.xsession}}} may be a better place (if your system uses
+it).
+
+
+=== Browsing ===
+
+If you used the defaults, you can start browsing using your favourite
+WebDAV client by pointing it at [[http://localhost:8009]]. E.g. using
+cadaver:
+
+{{{
+$ cadaver http://localhost:8009/
+dav:/> ls
+Listing collection `/': succeeded.
+Coll:   by-id                                  0  Apr  3 13:10
+Coll:   by-tags                                0  Apr  3 13:10
+Coll:   by-title                               0  Apr  3 13:10
+dav:/> ls /by-tags
+Listing collection `/by-tags/': succeeded.
+Coll:   example                                0  Apr  3 13:10
+Coll:   test                                   0  Apr  3 13:10
+dav:/> ls /by-tags/example
+Listing collection `/by-tags/example/': succeeded.
+        dots - 2011-06-12 18:37:17.ta       9981  Jun 12  2011
+dav:/> ls /by-title
+Listing collection `/by-title/': succeeded.
+        dots - 2011-06-12 18:37:17.ta       9981  Jun 12  2011
+}}}
+
+
+=== Selecting what to publish ===
+
+By default, journal2webdav will show all your favourite Journal entries
+(i.e. those with the favourite star ticked). This conflates what you
+want to keep with what you want to export, so you can tell
+journal2webdav what to export by providing a different root
+query. E.g. to export all TurtleArt instances:
+
+{{{
+journal2webdav --root-query '{"activity": "org.laptop.TurtleArtActivity"}'
+}}}
+
+Please note that current versions of sugar-datastore (up to and
+including at least 0.96) only support queries based on a very small set
+of properties. Unfortunately, neither 'tags' nor anything else more
+suitable for selecting which entries to export is included this subset.
+
+
+=== Exposing your Journal to the world ===
+
+To prevent others from browsing your Journal while you're trying out
+journal2webdav, by default only local applications will be allowed to
+connect. To allow other users to access journal2webdav, you need to let
+it bind to all interfaces:
+
+{{{
+journal2webdav --host ''
+}}}
+