From 0aa717c83d03c249e56d8f216895424d9550d68f Mon Sep 17 00:00:00 2001 From: Randy Ramos Date: Mon, 4 Sep 2017 19:29:42 -0400 Subject: Rename README to README.md This ensures that the Markdown syntax is properly displayed by Github and other Markdown readers. Also added quotes to a couple of paths and a flag. Signed-off-by: Randy Ramos Signed-off-by: Lukas Fleischer --- contrib/caldav/README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 contrib/caldav/README.md (limited to 'contrib/caldav/README.md') diff --git a/contrib/caldav/README.md b/contrib/caldav/README.md new file mode 100644 index 0000000..c35813d --- /dev/null +++ b/contrib/caldav/README.md @@ -0,0 +1,67 @@ +calcurse-caldav +=============== + +calcurse-caldav is a simple Python script that can be used to synchronize +calcurse with a CalDAV server. Please note that the script is alpha software! +This means that: + +* We are eagerly looking for testers to run the script and give feedback! If + you find any bugs, please report them to the calcurse mailing lists or to the + GitHub bug tracker. If the script works fine for you, please report back as + well! + +* The script might still have bugs. MAKE BACKUPS, especially before running + calcurse-caldav for the first time! + +Usage +----- + +calcurse-caldav requires an up-to-date version of calcurse and a configuration +file located at ~/.calcurse/caldav/config. An example configuration file can be +found under contrib/caldav/config.sample in the calcurse source tree. You will +also need to install *httplib2* for Python 3 using *pip* (e.g. `pip3 install +--user httplib2`) or your distribution's package manager. + +If you run calcurse-caldav for the first time, you need to provide the `--init` +argument. You can choose between the following initialization modes: + + --init=keep-remote Remove all local calcurse items and import remote objects + --init=keep-local Remove all remote objects and push local calcurse items + --init=two-way Copy local objects to the CalDAV server and vice versa + +For subsequent calcurse-caldav invocations, you don't need to specify any +additional parameters. + +Hooks +----- + +You can place scripts in `$HOME/.calcurse/caldav/hooks/` to trigger actions at +certain events. To enable a hook, add a script with one of the following names +to this directory. Also make sure the scripts are executable. + +*pre-sync*:: + Executed before the data files are synchronized. +*post-sync*:: + Executed after the data files are synchronized. + +Some examples can be found in the `contrib/caldav/hooks/` directory of the +calcurse source tree. + +How It Works +------------ + +calcurse-caldav creates a so-called synchronization database at +`~/.calcurse/caldav/sync.db` that always keeps a snapshot of the last time the +script was executed. When running the script, it compares the objects on the +server and the local objects with that snapshot to identify items that were +added or deleted. It then + +* downloads new objects from the server and imports them into calcurse, +* deletes local objects that no longer exist on the server, +* uploads objects to the server that were added locally, +* deleted objects from the server that were deleted locally, +* updates the synchronization database with a new snapshot. + +Note: Since calcurse does not use unique identifiers for items, it cannot keep +track of moved/edited items. Thus, modifying an item is equivalent to deleting +the old item and creating a new one. -- cgit v1.2.3-54-g00ecf