diff options
| -rw-r--r-- | README.md | 43 |
1 files changed, 23 insertions, 20 deletions
@@ -47,7 +47,7 @@ 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 (for me) faster than navigating into some web calendar interface and add an item there. +* Minor stuff that is 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. 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. @@ -127,9 +127,11 @@ The file TASK_MANAGEMENT.md contains some thoughts on how to organize tasks. Configuration file ------------------ -Configuration file is by default located in $HOME/.config/calendar.conf. calendar-cli expects it to be in json syntax, kal also accepts yaml format. 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. +Configuration file is by default located in $HOME/.config/calendar.conf. calendar-cli expects it to be in json syntax, while kal supports both json and yaml. 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) +(I considered .ini, but I was told that it's actually not a standard. I'd like any calendar application to be able to access the file, hence calendar.conf and not calendar-cli.conf) + +### calendar-cli The file may look like this: @@ -179,9 +181,17 @@ Sections may also include calendar urls or ids, and sections may inherit other s } ``` -kal also accepts `calendar_name`, which should match with the display name. +### kal + +Anything that goes for calendar-cli will work for kal as well, but there are three improvements in kal: + +* kal will accept a parameter `calendar_name`, which should match with the display name of the calendar. + +* YAML seems to have more traction than JSON when it comes to configuration that is supposed to be read and edited by humans, hence kal will accept configuration files in yaml as well as json. (I'm considering to backport yaml support to the legacy calendar-cli as well). + +* Since kal may operate at many calendars at one time, I decided to add the keyword "contains" to have one config section refer to multiple other config sections. -kal may operate at many calendars at one time, hence it's possible to make a section refer to multiple other sections, like this: +Example: ```yaml --- @@ -198,18 +208,17 @@ private-calendar: caldav_user: mrhyde caldav_pass: hunter2 calendar_name: goodgames -brothel-appointments - inheritate private-calendar +brothel-appointments: + inherits: private-calendar calendar_name: badgames work: contains: [ 'work-calendar', 'work-appointments' ] private: - contains: [ 'privat-calendar', 'brothel-appointments' ] + contains: [ 'private-calendar', 'brothel-appointments' ] ``` -Remember to `chmod og-r ~/.config/calendar.conf` or `chmod 0600 ~/.config/calendar.conf` - -### Examples +Usage example +------------- Add a calendar item "testevent" at 2013-10-01: @@ -217,6 +226,8 @@ Add a calendar item "testevent" at 2013-10-01: (assumes that `caldav-url`, `caldav-pass` and `caldav-user` has been added into configuration file. Those may also be added as command line options) +See USAGE.MD for instructions on how to use kal. + Objectives ---------- @@ -227,13 +238,5 @@ Objectives Roadmap ------- -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 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 +See NEXT_LEVEL.md and NEW_CLI.md for the direction the project is heading. |