documentation and comments. Resolves https://github.com/tobixen/calendar-cli/issues/65

4 files changed, 56 insertions, 21 deletions

diff --git a/README.md b/README.md
index 9a09585..4f95800 100644
--- a/README.md
+++ b/README.md
@@ -10,8 +10,18 @@ There is another project out there, "Command-line Interface for Google Calendar"
 
 There is a "competing" project at https://github.com/geier/khal - you may want to check it out - it's more mature but probably more complex.  It's using a "vsyncdir" backend - if I've understood it correctly, that involves building a local copy of the calendar.  The philosophy behind calendar-cli is slightly different, calendar-cli is supposed to be a simple cli-based caldav+ical client.  No synchronization, no local storage, just client-side operations.
 
+Usage examples
+--------------
+
+The commands and options will be described further down, however examples often beats documentation.
+
+First, check the tests folder - the file tests.sh shows some basic usage examples.  If you have radicale installed (`sudo pip install radicale`), you can try executing test_calendar-cli.sh in that folder, it basically sets up a temporary radicale server and executes the tests.sh towards that server.  If test_calendar-cli.sh breaks then _please_ raise an issue on the github or try to reach out through other channels.
+
+In the examples folder there is a script I was using on a regular basis for task management for a while.
+
 Installation
 ------------
+
 calendar-cli depends on quite some python libraries, i.e. pytz, caldav, etc.  "sudo ./setup.py install" should take care of all those eventually.
 
 Support
@@ -19,15 +29,17 @@ Support
 
 \#calendar-cli at irc.freenode.org, eventually t-calendar-cli@tobixen.no, eventually the issue tracker at https://github.com/tobixen/calendar-cli/issues
 
+Before reaching out, please make sure all the dependencies are installed and that you've installed the latest version of the caldav python library.
+
 Rationale
 ---------
 
 GUIs and Web-UIs are nice for some purposes, but I really find the command line unbeatable when it comes to:
 
-* Minor stuff that are repeated often.  Writing something like "todo add make a calendar-cli system" or "calendar add 'tomorrow 15:40+2h' doctor appointment" is just very much faster than navigating into some web calendar interface and add an item there.
+* Minor stuff that are repeated often.  Writing something like "todo add make a calendar-cli system" or "calendar add 'tomorrow 15:40+2h' doctor appointment" is (for me) faster than navigating into some web calendar interface and add an item there.
 * Things that are outside the scope of the UI.  Here is one of many tasks I'd like to do: "go through the work calendar, find all new calendar events that are outside office hours, check up with the personal calendar if there are potential conflicts, add some information at the personal calendar if appropriate", and vice versa - it has to be handled very manually if doing it through any normal calendar application as far as I know, but if having some simple CLI or python library I could easily make some interactive script that would help me doing the operation above.
 
-I've been looking a bit around, all I could find was cadaver and CalDAVClientLibrary.  Both of those seems to be a bit shortcoming; they seem to miss the iCalendar parsing/generation, and there are things that simply cannot be done through those tools.
+When I started writing calendar-cli, all I could find was cadaver and the CalDAVClientLibrary.  Both of those seems to be a bit shortcoming; they seem to miss the iCalendar parsing/generation, and there are things that simply cannot be done through those tools.
 
 Synopsis
 --------
@@ -48,42 +60,61 @@ not be up-to-date and may contain features not implemented yet.
 
 * --interactive: stop and query the user rather often
 * --caldav-url, --caldav-user, --caldav-pass: how to connect to the CalDAV server.  Fits better into a configuration file.
-* --calendar-url: url to the calendar one wants to use.
+* --calendar-url: url to the calendar one wants to use.  A relative URL (path) or a calendar-id is also accepted.
 * --config-file: use a specific configuration file (default: $HOME/.config/calendar.conf)
 * --config-section: use a specific section from the config file (i.e. to select a different caldav-server to connect to)
 * --icalendar: Write or read icalendar to/from stdout/stdin
 * --nocaldav: don't connect to a caldav server
+* --timezone: any "naive" timestamp should be considered to belong to the given time zone, timestamps outputted should be in this time zone, timestamps given through options should be considered to be in this time zone (Olson database identifiers, like UTC or Europe/Helsinki). (default: local timezone)
 
-The caldav URL is supposed to be something like i.e. http://some.davical.server/caldav.php/ - it is only supposed to relay the server location, not the user or calendar.  It's a common mistake to use something like http://some.davical.server/caldav.php/tobixen/work-calendar/ - it will also work, but it will ignore the calendar part of it, and use first calendar it can find - perhaps tobixen/family-calendar/.  Use http://some.davical.server/caldav.php/ as the caldav URL, and tobixen/family-calendar as the calendar-url.
+The caldav URL is supposed to be something like i.e. http://some.davical.server/caldav.php/ - it is only supposed to relay the server location, not the user or calendar.  Things will most likely work if you give http://some.davical.server/caldav.php/tobixen/work-calendar/ - but it will ignore the calendar part of it, and use first calendar it can find - which perhaps may be tobixen/family-calendar/.  Use http://some.davical.server/caldav.php/ as the caldav URL, and /tobixen/family-calendar as the calendar-url.
 
 ### Commands
 
+As of 0.12, there are two or three distinct commands - calendar (for management of events) and todo (for task management), with quite different code paths.  The third thing is journal ... but as far as I know, it's not much common to use caldav servers for keeping journals, the journal thing is not much tested nor much rich on features.
+
+There will be code refactorings in v1.0, applying quite some of the logic in the task management to the calendar management.
+
 * calendar - access/modify a calendar
-    * subcommands: add, addics (for uploading events in ical format), agenda, delete
+    * subcommands: add, addics (for uploading events in ical format), agenda, delete, create (for creating a new calendar)
 * todo - access/modify a todo-list
-    * subcommands: add, list, edit, postpone, complete, delete
+    * subcommands: add, list, edit, postpone, complete, delete, addlist
+
+todo addlist: for creating a new task list.  Most caldav servers don't make any difference between a task list and a calendar.  Zimbra is an exception.  addlist hasn't been tested as of version 0.12, perhaps it works, perhaps not)
 
 ### Event time specification
 
-Supported in v0.8:
+Supported in v0.12:
 
 * anything recognized by dateutil.parser.parse()
 * An iso time stamp, followed with the duration, using either + or space as separator.  Duration is a number postfixed by s for seconds, m for minutes, h for hours, d for days, w for weeks and y for years (i.e. 2013-09-10T13:37+30d)
+* ISO dates.  For full day events, make sure to specify the duration in days.
 
 All of those would eventually be supported in future versions if it's not too difficult to achieve:
 
 * Two ISO timestamps separated by a dash (-)
-* ISO dates without times (default duration will be one day, for two dates full days up to and including the end date is counted)
 * "tomorrow" instead of an ISO date
 * weekday instead of an ISO date (this seems supported already by dateutil.parser.parse)
 * clock time without the date; event will be assumed to start within 24 hours.
 
-Alternatively, endtime or duration can be given through options (not supported as of 0.9)
+Alternatively, endtime or duration can be given through options (not supported as of 0.12)
+
+### Getting out customized information through --todo-template and --event-template
+
+This is a string containing variables enclosed in curly braces, like "uid: {uid}".  Full documentation of the available variables will be given in version 1.0.
+
+Particularly the uid can be useful, as one may want to use the uid for things like deleting events and postponing tasks.
+
+In the examples folder there is a task management script which will use the --todo-template to create a new shell script for postponing all overdue tasks.  This shell script can then be edited interactively and run.
+
+### Task management
+
+With the todo-command, there are quite some options available (i.e. --categories, --limit, --todo-uid, etc) to select or filter tasks.  Those are used by the commands list, edit, postpone, complete and delete.  A typical use-case scenario is to first use the "list" command, tweak the filtering options to get a list containing the tasks one wants to operate with, and then use either edit, postpone, complete or delete.
 
 Configuration file
 ------------------
 
-Configuration file is by default located in $HOME/.config/calendar.conf and should be in json syntax.  As of version 0.8 you may run `calendar-cli --interactive-config` if you don't feel comfortable with hand-crafting configuration in json syntax.
+Configuration file is by default located in $HOME/.config/calendar.conf and should be in json syntax.  You may run `calendar-cli --interactive-config` if you don't feel comfortable with hand-crafting configuration in json syntax, though this feature is not tested regularly.
 
 (I considered a configuration file in .ini-format, having a "default"-section with default values for any global options, and optionally other sections for different CalDAV-servers.  Asking a bit around for recommendations on config file format as well as location, I was told that the .ini-format is not a standard, I'd be better off using a standard like yaml, json or xml.  Personally I like json a bit better than yaml - after consulting with a friend I ended up with json.  Location ... I think it's "cleaner" to keep it in ~/.config/, and I'd like any calendar application to be able to access the file, hence it got ~/.config/calendar.conf rather than ~/.calendar-cli.conf)
 
@@ -134,9 +165,13 @@ Objectives
 
 Roadmap
 -------
-This is being moved out to the issues section in github.
+Eventually, the issues section in the github will probably be more up-to-date on the upcoming plans for enhancements and bug fixes.
+
+Possibly the next version after 0.12 will be 1.0.  One of the important things there is to refactor the calendar code, the filtering options available for tasks should also be available for the calendar.
+
+Other features that I eventually would like to add:
 
-* Allow pulling out an agenda for all calendars at once (though, with the current design it's so much easier to do it through a bash loop rather than in the python code, so this is postponed for a while)
+* Allow pulling out an agenda for several calendars at once (though, with the current design it's so much easier to do it through a bash loop rather than in the python code, so this is postponed for a while)
 * Allow specification of event duration and/or event end time through options
 * Fix easy-to-use symlinks (or alternatively wrapper scripts)
 * Make some nosetests
diff --git a/EXAMPLES b/examples/task-management-examples
index fb474fa..4bdc708 100644
--- a/EXAMPLES
+++ b/examples/task-management-examples
@@ -1,6 +1,6 @@
-## Eventually I'd like to make calendar-cli easier to use, so some of the "external logic" in those examples will eventually be moved into the tool itself.  Anyway, some of the power of having a command-line utility is that it's possible to do just anything ...
+## This was my daily task management workflow for a while.
 
-## TODO: still some hard-coded personal stuff in the script.  Should move it out to a config section.
+## Eventually I'd like to make calendar-cli easier to use, so some of the "external logic" in those examples will eventually be moved into the tool itself.  Anyway, some of the power of having a command-line utility is that it's possible to do just anything ...
 
 [ -z "$EDITOR" ] && EDITOR=vi
 
diff --git a/tests/README b/tests/README
index 406ea8e..a6f9605 100644
--- a/tests/README
+++ b/tests/README
@@ -1,7 +1,7 @@
-TL;DR: run test_calendar-cli.sh, don't run tests.sh.
+TL;DR: do run test_calendar-cli.sh, don't run tests.sh - unless you know what you're doing.
 
-Probably we should add some standard python test code here that can be run through nose or tox, but after all this is a command line utility - hence I found it appropriate to start with functional tests written to be executed from through a shell.
+test_calendar-cli.sh will attempt to set up a radicale server and a xandikos server, and run tests.sh towards those two.  At least one of those should be installed for the tests to work.  It will bind up some hard coded ports on localhost, tests will fail if those ports are already in use. (Oups - xandikos doesn't work very well together with calendar-cli at the moment, so it has been skipped).
 
-The file tests.sh will run towards whatever calendar server is configured in .config/calendar.conf, and it has potential side effects, it will wipe out any prior events within the time range 2010-10-10 and 2010-10-14.
+The actual tests are in tests.sh.  You'll have to run this one if you want to check compatibility with other calendar servers, but it requires either that the $calendar_cli environmental variable is set, or that some calendar server is configured in .config/calendar.conf.  If you choose to run the tests towards some old, existing calendar, then be aware that the test code may eventually delete some historic data from 2010.
 
-The file test_calendar-cli.sh will set up a radicale calendar server, run the tests.sh towards radicale, then set up xandikos and run tests.sh towards xandikos.
+Probably we should add some standard python test code here that can be run through nose or tox, but after all this is a command line utility - hence I found it appropriate to start with functional tests written to be executed from through a shell.
diff --git a/tests/tests.sh b/tests/tests.sh
index fa2ff3d..7f8d136 100755
--- a/tests/tests.sh
+++ b/tests/tests.sh
@@ -34,7 +34,7 @@ echo "## EVENTS"
 
 echo "## testing $calendar_cli"
 echo "## this is a very simple test script without advanced error handling"
-echo "## if this test script doesn't output 'all tests completed' in the end, something went wrong"
+echo "## if this test script doesn't output 'ALL TESTS COMPLETED!  YAY!' in the end, something went wrong"
 
 echo "## Attempting to add an event at 2010-10-09 20:00:00, 2 hours duration"
 calendar_cli calendar add '2010-10-09 20:00:00+2h' 'testing testing'
@@ -46,7 +46,7 @@ calendar_cli calendar add '2010-10-10 20:00:00+01:00' 'testing testing' --set-de
 uid2=$(echo $output | perl -ne '/uid=(.*)$/ && print $1')
 [ -n "$uid2" ] || error "got no UID back"
 
-echo "## Attempting to add a past event at 2010-10-11 20:00:00, CET, 3h duration"
+echo "## Attempting to add an event at 2010-10-11 20:00:00, CET, 3h duration"
 calendar_cli calendar add '2010-10-11 20:00:00+01:00+3h' 'testing testing'
 uid3=$(echo $output | perl -ne '/uid=(.*)$/ && print $1')
 echo "## OK: Added the event, uid is $uid"
@@ -181,4 +181,4 @@ calendar_cli todo --hide-parents --categories scripttest complete
 calendar_cli todo --hide-parents --categories scripttest list
 [ -z "$output" ] && echo "## OK: found no tasks now"
 
-echo "## all tests completed"
+echo "## ALL TESTS COMPLETED!  YAY!"