Package: khalorg
Click here for the GitHub page.ContentsIntroductionInstallationUsageNeovim pluginWorkflow for Office 365TroubleshootingContributingLicenseImprovementsIntroductionkhalorgis an interface between Org mode and Khal cli calendar.DefinitionsCalDav: internet standard for client access to calendarsDavmail: CalDav exchange gatewaykhal: command line calendar appkhalel: interface between emacs and khalnvim-orgmode: org mode for neovimorg: plain text system for keeping notes, agendas and morevdirsyncer: synchronizes calendars and addressbooks between servers and the local file systemMotivationI use org mode to manage my agenda and my notes. However, in a professional
setting, you are often required to use proprietary software for your agenda,
like Office 365. Luckily, programs exist that can synchronize agendas from
different sources, by implementing the CalDav standard. Personally, I like to
usevdirsyncerwithkhalto synchronize my agendas. To bridge the gap
betweenkhalandorg mode, only 1 program exists called:khalel. However,
this program is designed foremacs. Since there are also org mode users
outside ofemacs(e.g.neovim),khalorgaims to be a general interface
betweenvdirsyncer/khalandorg mode.Based on the above, the following workflow is desired:┌──────┐     
│CalDav│     
└┬─────┘     
┌▽─────────┐  
│vdirsyncer│  
└┬─────────┘  
┌▽───┐        
│khal│        
└┬───┘        
┌▽───────┐
│khalorg │
└┬───────┘
┌▽───────┐    
│org mode│    
└────────┘FeaturesCan be used by org mode for emacs, vim and neovim.Vdirsyncer calendars can be manipulated by using the cli ofkhalas the interface.khalorg new: convert an org agenda item into akhalagenda
item.khalorg list: convert akhalagenda item into an org agenda
item.khalorg edit: edit an existingkhalagenda item with org mode.khalorg delete: delete an existingkhalitem.Recurring items are supported by providing an org repeater in the
time stamp (e.g.,+1w). The following is supported:the follow org repeaters:+{integer}{d,w,m,y}khalorg newandkhalorg edit --edit-datessupport 1 time stamp
per org agenda item.khalorg listconcatenates timestamps that cannot be describes by
an org repeater, resulting in an org agenda item with multiple
timestamps.Supports anuntildate for recurring items. The until date can be
supplied through an org propertyUNTIL.Has unittestsIncludes an Office 365 workflow with a bash scriptSemantic versioningGifs with demosNeovim pluginIs available on PyPIInstallationFor safety, always make a back-up of your calendar before installing software
that is new to you.Make sure yourkhaldate format is compatible with org, otherwise it
will not work. When runningkhal printformatsyou should get:longdatetimeformat: 2013-12-21 Sat 21:45
datetimeformat: 2013-12-21 Sat 21:45
longdateformat: 2013-12-21 Sat
dateformat: 2013-12-21 Sat
timeformat: 21:45If not, check the documentation ofkhalon how to change this.PyPiInstall by running the following command:pipinstallkhalorgFrom sourceSet your current working directory to the root directory, i.e, the
directory containing thepyproject.tomlfile. Next, run:pipinstall.After this, the executablekhalorgwill be available.For developmentIf you want to develop the code, debug it, and test it, run:pipinstall-e'.[test,debug]'UsageUsekhalorg --helpto get information about the cli ofkhalorg. The
following section discuss thekhalorgcommands that are available.List: from khal to orgAgenda items fromkhalcan be converted to org items using thekhalorg listcommand. For examples:khalorglistmy_calendartoday90d>my_calendar.orgHere, thekhalagenda items of the calendarmy_calendarare
converted to org format and written to a file calledmy_calendar.org.
The range is specified fromtodaytill90d(90 days) in the future.
For more information about the allowed date formats, check thekhal listcommand, which is used for this functionality. It is assumed
that thekhalcalendar calledmy_calendarexists. Make suremy_calendaris a calendar that exists on your local file system.–formatIfkhalorg list --formatoption is not defined, the default one is
used which can be found at./khalorg/static/khalorg_format.txt. If you
want to define your own format, you have 2 options: you can use thekhalorg list --formatoption, or you can place your custom format at$HOME/.config/khalorg/khalorg_format.txtthis format will then be used
instead of the default one that is shown below.* {title}
  {timestamps}
  :PROPERTIES:
  :ATTENDEES: {attendees}
  :CALENDAR: {calendar}
  :CATEGORIES: {categories}
  :LOCATION: {location}
  :ORGANIZER: {organizer}
  :STATUS: {status}
  :UID: {uid}
  :URL: {url}
  :END:
  {description}the following keys are supported:{attendees}: a comma separated list of email addresses of attendees{calendar}: the name of the khal calendar{categories}: the categories property of the item{description}: the description of the item{location}: the location of the item{organizer}: the email of the organizer{status}: the status of the item, e.g., TENTATIVE or ACCEPTED{timestamps}: the timestamp of the item{title}: the summary of the item{uid}: the UID of the item{rrule_until}: the until value of the RRULE.{url}: the url propertythe following keys are supported but are typically reserved for internal use
and are therefore less informative:{until}: the until property value. Is empty when usingkhalorg list.{rrule}: the ICal RRULE of the item.Recurring itemsThekhalorg listcommand relies on thekhal listcommand. Using this
command theRRULEof each item is retrieved to created the correct org
repeater. Only simple org repeaters are supported that have the
following form:+[number][h,w,m,y]. ComplexRRULEsare described by
concatenating the corresponding timestamps within 1 agenda item,
resulting in a list of items. For example, the agenda item below
represents a weekly recurring event where the first meeting was moved to
another date, resulting in a timestamp without a repeater, and one with
a repeater.* Meeting
  <2023-01-05 Thu 01:00-02:00>
  <2023-01-08 Sun 01:00-02:00 +1w>
  :PROPERTIES:
  :UID: 123
  :LOCATION: Somewhere
  :ORGANIZER: Someone (someone@outlook.com)
  :ATTENDEES: test@test.com, test2@test.com
  :URL: www.test.com
  :END:
  Hello,
  
  Lets have a meeting.
  
  Regards,
  
  
  SomeoneNew: from org to khalAn org agenda item can be converted to a newkhalagenda item by
feeding the org item through stdin tokhalorg newand specifying the
khal calendar name as a positional argument. For example, the consider
the org item below, which is saved asmeeting.org.* Meeting
  <2023-01-01 Sun 01:00-02:00 +1w>
  :PROPERTIES:
  :UID: 123
  :LOCATION: Somewhere
  :ORGANIZER: Someone (someone@outlook.com)
  :ATTENDEES: test@test.com, test2@test.com
  :URL: www.test.com
  :END:
  Hello,
  
  Lets have a meeting.
  
  Regards,
  
  
  SomeoneThis item can be converted to thekhalcalendar called
"mycalendar" as follows:catmeeting.org|khalorgnewmy_calendarIt is assumed that thekhalcalendar called "mycalendar"
exists. Make sure "mycalendar" is a calendar that exists on
your local file system.Recurring itemsOnly 1 timestamp per org item is supported. Note that the meeting above
is repeated every week (+1w). Only simple org repeaters are supported
that have the following form:+[number][h,w,m,y]. These events repeat
forever, unless you specify an end date using the `UNTIL` property in
the org file.Personally, when I need to create a complex repeat pattern (or when I
need outlook specific items like a Teams invite), I create the event in
outlook first. Next, I usekhalorg editto change the fields that need
editing (e.g., the description).AttendeesOptionally, attendees can be added to theATTENDEESproperty field.
The attendees will be added to theAttendeesfield ofkhal. Once you
synchronizekhalwith a server (e.g., outlook) an invitation will be
send to the attendees.Edit: from org to khalExistingkhalevents can be updates by feeding an org file with the
corresponding UID through stdin to thekhalorg editcommand. For
example, the org agenda item ofNewcan be altered and used as an input forkhalorg edit, as long as the UID remains untouched.* Edited meeting
  <2023-01-01 Sun 01:00-02:00 +1w>
  :PROPERTIES:
  :UID: 123
  :ORGANIZER: Someone (someone@outlook.com)
  :ATTENDEES: other@test.com
  :END:
  Hello,
  
  I edited the meeting by removing the location and url. I also changed the
  title and the attendees field.
  
  Regards,
  
  
  SomeoneNext, run the following command:catmeeting.org|khalorgeditmy_calendarWhen usingkhalorg editplease consider the following:Editing an existing event is different from creating a new one as the
originalicalendarfile is retained. Only parts of it are altered.
This is convienent when the icalendar file contains information that
cannot be generated bykhalorg. For example, a Microsoft Team
meeting.Only the PROTO event is edited, i.e., the whole series is altered not
only the occurence.khal editwill only update the dates + recurrence if the--edit-datesflag is passed. This avoids editing the start-stop date
when editing an event that contains multiple timestamps (which are not
supported).Delete: from org to khalAn event can be deleted from a khal calendar by feeding an org file to thekhalorg deletecommand through stdin. The org file must contain an agenda
item with a non-empty UID property. For example, the khal event that was
created using theNewcommand
above can be removed by feeding the same file tokhalorg delete:catmeeting.org|khalorgdeletemy_calendarRecurring itemsWhen deleting recurring items the whole series will be removed. Removing
occurrences is not supported.Neovim pluginThe neovim plugin can be found here:nvim-khalorg.Workflow for Office 365The diagram below illustrates the workflow than can be achieved when usingkhalorg. The folderextras, on theGitHubpage, contains abashscript
calledcalsync, that synchronizesvdirsyncercalendars and exports them as
an org file using thekhalorg listcommand. Davmail is used as the CalDav
server in this specific example.┌──────────┐  
│Office 365│  
└┬─────────┘  
┌▽──────┐     
│Davmail│     
└┬──────┘     
┌▽─────────┐  
│vdirsyncer│  
└┬─────────┘  
┌▽───┐        
│khal│        
└┬───┘        
┌▽───────┐
│khalorg │
└┬───────┘
┌▽───────┐    
│org mode│    
└────────┘TroubleshootingIf you encounter any issues, please report them on the issue tracker at:khalorg issuesContributingContributions are welcome! Please seeCONTRIBUTINGfor
more information.LicenseDistributed under theMIT License.Improvements:Timezones are not yet supported, sokhalorgwill only work when
you agenda remain in the timezone that you specified within yourkhalconfig.Running khal commands directly from a script in not
straightforward. Therefore, khal is executed as a subprocess, by using
its command line interface.khalorg newandkhal editonly support 1 timestamp per item.
However, it is desired that all timestamps within 1 org agenda item,
end up in 1 khal event, as is the case for theorgagenda. To achieve
this the following could be build:When multiple timestamps without an org repeater are provided,
find theRRULEthat describes them. Also, set theUNTILdate to
the last date. If noRRULEcan be found, raise an error. Another
option could be to use theRDATEoption of ICal.When multiple timestamps with an org repeater are presented, try
to find theRRULEthat describes them.