adds readme

README.org

@@ -0,0 +1,133 @@
+#+TITLE: khalel
+
+=khalel=: Interacting through Emacs with locally-stored calendars via the console application =khal=.
+
+=khal= allows to access calendars stored in =.ics= files and provides means of
+listing existing events as well as to create new ones.
+
+Adjusting the output of =khal=, one can get something that already resembles an
+org-mode file (link to the online documentation: [[https://khal.readthedocs.io/en/latest/usage.html][khal usuage]]):
+
+#+begin_src bash :results output
+khal list --format "* {title} \n <{start-date} {start-time}-{end-time}> \n {location} \n {description}" --day-format "" today 10d
+#+end_src
+
+#+RESULTS:
+: * DnD mit den Toten Charaktären \n <2021-09-04 21:00-23:00> \n  \n
+: * DHL \n <2021-09-09 13:00-16:00> \n  \n
+: * Ge blod \n <2021-09-09 13:00-19:00> \n  \n
+: * Rebeckas släkt \n <2021-09-11 16:00-19:00> \n  \n
+: * Plocka 🍄 \n <2021-09-12 -> \n  \n
+: * IcewindDale DnD \n <2021-09-12 16:00-19:00> \n  \n
+
+This is showing the events in the coming 10 days from now. This gives us
+something to work with and means we don't have to touch the =.ics= files
+directly.
+
+=khalel= provides a wrapper around =khal= and =org-mode= export functionality to
+import upcoming events into an org-mode file or to create new events via
+org-mode capture templates.
+
+* Use case
+
+I sync my remote calendars using [[https://github.com/pimutils/vdirsyncer][vdirsyncer]] which mirrors all events from my
+CalDAV servers locally. This calendar store can be accessed through =khal= and
+=khalel=. I am mostly interested in seeing upcoming events in the org-mode
+agenda and to quickly create new events with the familiar org-capture mechanism.
+
+This requires a small chain of steps: most notably, in my setup, events created
+through =khalel= require an additional import step to be visible in org-mode.
+
+#+begin_src ditaa :file sync_scheme.png
+  +-------+    +----------+    +-------+    +-------+    +---------+
+  |       |--->|          |--->|       |--->|       |--->|         |
+  | remote|    |vdirsyncer|    |  khal |    |khalel |    | org mode|
+  |       |<===|          |<===|       |===>|       |===>|         |
+  +-------+    +----------+    +-------+    +-------+    +---------+
+                                   ^
+                                   :
+                                   :
+               +----------+    +--------+
+               |          |    |        |       --> existing events
+               | org mode |===>| khalel |
+               |          |    |        |       ==> new events
+               +----------+    +--------+
+
+#+end_src
+
+#+RESULTS:
+[[file:sync_scheme.png]]
+
+Advantages:
+- integrates neatly into my work-flow
+- easy to customize
+- local stores can easily be backed up
+- synchronization can be done manually (when online) or automatized via cron job
+
+Disadvantages:
+- several manual steps to update if not automatized
+- more initial set-up work
+
+Besides calendars, this setup can be extended to contacts using:
+- [[https://github.com/pimutils/vdirsyncer][vdirsyncer]] (again) to mirror contacts from CardDAV server locally,
+- [[https://github.com/scheibler/khard][khard]] to access them via the command line, and
+- [[https://github.com/DamienCassou/khardel][khardel]] for integration into Emacs (not by me).
+
+* Getting started
+** Installing =khal=
+
+Simply download the package for your preferred distribution or [[https://khal.readthedocs.io/en/latest/install.html][follow the installation instructions]].
+
+** Configuring =khal=
+
+You can create a configuration interactively by running =khal configure= or simply use the one below and save it to =~/.config/khal/config=:
+
+#+begin_src conf
+[calendars]
+
+[[my_calendar_local]]
+path = ~/.calendar/*
+type = discover
+
+[locale]
+timeformat = %H:%M
+dateformat = %Y-%m-%d
+longdateformat = %Y-%m-%d
+datetimeformat = %Y-%m-%d %H:%M
+longdatetimeformat = %Y-%m-%d %H:%M
+#+end_src
+
+You might want to set up a default calendar as well.
+** Install =khalel=
+
+** Configuring =khalel=
+First, make sure that the right =khal= binary will be used:
+#+begin_src emacs-lisp
+(setq khalel-khal-command "~/.local/bin/khal")
+#+end_src
+
+You might want to customize the values for default calendar, capture file and import file for khalel:
+#+begin_src emacs-lisp
+(setq khalel-default-calendar "privat")
+(setq khalel-capture-key "e")
+(setq khalel-import-org-file (concat org-directory "calendar.org"))
+(setq khalel-capture-org-file (concat org-directory "new_events.org"))
+#+end_src
+
+In my setup, the =new_events.org= file is mostly a temporary file as it is not part of my org-agenda. =calendar.org=, on the other hand, is. There the new events will end up in after the next sync.
+
+And I never plan too long into the future, so the next three months will be more than enough to fill my agenda view:
+#+begin_src emacs-lisp
+(setq khalel-import-time-delta "90d")
+#+end_src
+
+Using these settings, we can now set up a capture template using a helper routine:
+#+begin_src emacs-lisp
+(khalel-add-capture-template)
+#+end_src
+This will also register an export hook that is run when the capture is finalized.
+
+** First steps
+You can import upcoming events through =khalel-import-upcoming-events= or create new ones through =org-capture= and pressing "e" for a new calendar event.
+
+You might want to consider adding the org file with the imported events (=calendar.org= in the above example) to your org agenda.