WAT - WAT: a Todo
=================

Last edited: $Date: 2001/07/30 02:53:21 $

LATEST VERSION
You can find the latest version of WAT at
http://www.oblomovka.com/code/wat/

The latest version of this document lives at
http://www.oblomovka.com/code/wat/README

To find out the version of your copy of wat, type 'wat -V'

REQUIREMENTS

You'll need PDA::Pilot which should come with your version of pilot-link. Er,
which you'll need too. Get it from <URL:http://www.gnu-designs.com/pilot-link/>

Debian users should apt-get install pilot-link libpalm-perl


INSTALLATION

Copy 'wat' to your bin directory, and wat.vim to where'er you keep your vim
files (I keep them in ~/.vim ).

If you use Vim 6, you'll need to add these lines to your .vimrc to get the
wat.vim to autoload when you edit ~/.wat

augroup wat
    au! 
    autocmd BufRead,BufNewFile *.wat so WHEREYOUKEEPIT/wat.vim
augroup END

There's a better, more vim6-ish way of doing this, but I haven't quite worked
it out yet.

USE

Running wat for the first time will download all your current uncompleted todo
entries and store them in a file called ".wat" in your home directory. After
you've done this, load up the ~/.wat file in vim. As a plain file, it should
give you some idea of the .wat files structure. If you're using the folding
version under Vim 6, you should be able to open and close folded entries by
using the "za" command. Type ':help fold.txt' in Vim 6 to find out more
commands.

Thereafter, 'wat' at the command line or hitting '\S' while editing the ~/.wat
file will synchronize the ~/.wat file with your Palm's ToDo database. Entries
you've changed in the .wat file will be altered on the Palm. Items you've
ticked off as complete or deleted on either should be removed from the other.
New entries on Palm or PC will be replicated on the other machine.

To enter new entries on the PC, just start a new line beginning with two
spaces, a priority number, another space and your description. End it by
putting a "%" as the first character on a fresh line.

When editing existing entries, take care not to delete or mess with the "%"
line. The number after the % is used by wat to identify which Palm ToDo entry
this PC entry refers to.


BUGS

Wat's not very tolerant of errors in the todo list structure, or errors during
the syncing process. You shouldn't lose anything, but you may be left with a
few unwanted extra entries. No guarantees.

Syncronization isn't ideal. It's always hard to tell which changes to give
priority to - especially as we can't tell from the text file whether there
have *been* any changes. Here's how wat decides:

Assume that the PC's version is correct, *unless*:

a) the 'modified' flag is set on the Palm. This is a good guide, except I
assume that it gets reset when synced via other programs. It'd be great if wat
could sit as a conduit from another more general syncing program like jpilot
or coldsync.

b) the 'complete' or 'deleted' flag is set on the Palm. If you've deleted or
ticked the todo item, it's unlikely that you'll want it overwritten with a
"not completed" version. This works the other way, too - if a Palm entry is
modified, but it's been ticked on the PC, we assumed the ticked PC entry takes
back precedence.

Deleting on the PC still isn't working at all well.

Folding messes up after syncing - I'm not sure how you can preverse the
folding state of a file that will gain and lose lines outside of vim.

Any problems (or improvements or suggestions), send them along to
danny@spesh.com.


$Id: README,v 1.3 2001/07/30 02:53:21 danny Exp $
