= Jogger plugin =

== What is it for? ==

Jogger plugin was made to simplify the life of users of jogger.pl blogging system. It is meant to capture messages sent by joggerbot and offer nicer interface to its functions.

=== Features ===

 * divides comments by threads, each in its own window,
 * allows simpler responding to comments by just writing message to appriopriate window — entry ID is added automagically,
 * allows publishing entries from files with memorizing path and basic syntax checks.

== How to enable ==

First you have to load plugin and create new session with {{{jogger:]}} prefix. UID part may be anything, but I recommend to use Jogger account name.

{{{
plugin +jogger
session --add jogger:me
}}}

Then you'll have to set two important session variables. {{{used_session}}} should be set to jabber session, which accesses your primary jabber account (set in Jogger.pl admin panel). {{{used_uid}}} sets UID on which Joggerbot resides.

{{{
session jogger:me used_session xmpp:me@myjabberserver.net
session jogger:me used_uid xmpp:me@jogger.pl
}}}

''Note: jogger doesn't force any protocol, thus you'll need to explicitly specify {{{xmpp:}}} prefix. That also means you could use any other protocol, if you like — e.g. forward joggerbot messages through icq.''

If everything works fine, jogger session should now copy status of joggerbot.

== Comments ==

When someone posts a comment on entry you're subscribing, jogger plugin intercepts message from bot:

{{{
13:21:17 ::: (jogger:me) Query with http://me.jogger.pl/2008/09/01/some-example-entry/ started in 2
}}}

Jogger automagically gets EID and URL, transforming them into userlist entry with {{{jogger:<EID>}}} as UID and URL as nickname.

Inside the window, you will see comments as normal messages, but with 'prefix message' stripped.

{{{
13:50:38 .-- http://me.jogger.pl/2008/09/01/some-example-entry//jogger:909090 --- -- -
13:50:38 | Od: someone
13:50:38 | Some comment
13:50:38 `----- ---- --- -- -
}}}

You can now:
 * write another comment on that entry just by writing it in the window — the plugin will add {{{#909090}}} prefix automagically,
 * stop subscribing to the thread with {{{/unsub}}} command,
 * or subscribe it again with {{{/sub}}}.

== Entries ==

To post a new entry you can either:
 * send it to bot like always,
 * send it to {{{jogger:}}} UID in jogger session (which is gateway to bot),
 * use file-based interface described below.

If {{{ignore_outgoing_entries}}} session variable is set, jogger plugin will not display sent entries as messages. Else they'll appear as messages sent to {{{jogger:}}}.

=== File-based interface ===

First you need to write new entry and save it as a standard file. Here we'll assume that you named it {{{~/entry.html}}} (using .html extension triggers syntax highliting in many editors).

Then (in jogger session) you call:
{{{
/prepare ~/entry.html
}}}

Now if file can be read successfully, jogger plugin can output some warnings and then:
{{{
14:03:39 ::: File ~/entry.html is ready for submission.
}}}

If you want to modify the file and recheck it, just run {{{/prepare}}} again. It does memorize last used file, so you don't have to enter it again.

When your entry is ready for submission, use:
{{{
/publish
}}}

If file was modified after last {{{/prepare}}}, {{{/publish}}} will notify you about checksum change and refuse to publish it. You can then call {{{/prepare}}} to check the entry, or use {{{/publish}}} again to force submission.