# Khalorg
[Click here for the GitHub page.](https://github.com/BartSte/khalorg)
<img src="./demo/logo.jpg" width=50%>
## Demo
The demo below demonstrates the following features using the neovim plugin
called [nvim-khalorg](https://github.com/BartSte/nvim-khalorg):
- `khalorg new`: convert an org agenda item into a `khal` agenda item.
- `khalorg list`: convert a `khal` agenda item into an org agenda item.
- `khalorg edit`: edit an existing `khal` agenda item with org mode.
- `khalorg delete`: delete an existing `khal` item.
## Contents
<!--toc:start-->
- [Demo](#demo)
- [Contents](#contents)
- [Introduction](#introduction)
- [Definitions](#definitions)
- [Motivation](#motivation)
- [Features](#features)
- [Installation](#installation)
- [PyPi](#pypi)
- [From source](#from-source)
- [For development](#for-development)
- [Usage](#usage)
- [List: from khal to org](#list-from-khal-to-org)
- [–format](#format)
- [Recurring items](#recurring-items)
- [New: from org to khal](#new-from-org-to-khal)
- [Recurring items](#recurring-items)
- [Attendees](#attendees)
- [Edit: from org to khal](#edit-from-org-to-khal)
- [Delete: from org to khal](#delete-from-org-to-khal)
- [Recurring items](#recurring-items)
- [Neovim plugin](#neovim-plugin)
- [Workflow for Office 365](#workflow-for-office-365)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
- [Improvements:](#improvements)
<!--toc:end-->
## Introduction
`khalorg` is an interface between Org mode and Khal cli calendar.
### Definitions
- [CalDav](https://en.wikipedia.org/wiki/CalDAV): internet standard for client access to calendars
- [Davmail](https://davmail.sourceforge.net/e): CalDav exchange gateway
- [khal](https://github.com/pimutils/khal): command line calendar app
- [khalel](https://gitlab.com/hperrey/khalel): interface between emacs and khal
- [nvim-orgmode](https://github.com/nvim-orgmode/orgmode): org mode for neovim
- [org](https://orgmode.org): plain text system for keeping notes, agendas and more
- [vdirsyncer](https://github.com/pimutils/vdirsyncer): synchronizes calendars and addressbooks between servers and the local file system
### Motivation
I 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
use `vdirsyncer` with `khal` to synchronize my agendas. To bridge the gap
between `khal` and `org mode`, only 1 program exists called: `khalel`. However,
this program is designed for `emacs`. Since there are also org mode users
outside of `emacs` (e.g. `neovim`), `khalorg` aims to be a general interface
between `vdirsyncer`/`khal` and `org mode`.
Based on the above, the following workflow is desired:
```example
┌──────┐
│CalDav│
└┬─────┘
┌▽─────────┐
│vdirsyncer│
└┬─────────┘
┌▽───┐
│khal│
└┬───┘
┌▽───────┐
│khalorg │
└┬───────┘
┌▽───────┐
│org mode│
└────────┘
```
### Features
- [x] Can be used by org mode for emacs, vim and neovim.
- [x] Vdirsyncer calendars can be manipulated by using the cli of `khal`
as the interface.
- [x] `khalorg new`: convert an org agenda item into a `khal` agenda
item.
- [x] `khalorg list`: convert a `khal` agenda item into an org agenda
item.
- [x] `khalorg edit`: edit an existing `khal` agenda item with org mode.
- [x] `khalorg delete`: delete an existing `khal` item.
- [x] 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 new` and `khalorg edit --edit-dates` support 1 time stamp
per org agenda item.
- `khalorg list` concatenates timestamps that cannot be describes by
an org repeater, resulting in an org agenda item with multiple
timestamps.
- Supports an `until` date for recurring items. The until date can be
supplied through an org property `UNTIL`.
- [x] Has unittests
- [x] Includes an Office 365 workflow with a bash script
- [x] Semantic versioning
- [x] Gifs with demos
- [x] Neovim plugin
- [x] Is available on PyPI
## Installation
For safety, always make a back-up of your calendar before installing software
that is new to you.
Make sure your `khal` date format is compatible with org, otherwise it
will not work. When running `khal printformats` you should get:
```example
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:45
```
If not, check the documentation of `khal` on how to change this.
### PyPi
Install by running the following command:
```bash
pip install khalorg
```
### From source
Set your current working directory to the root directory, i.e, the
directory containing the `pyproject.toml` file. Next, run:
```bash
pip install .
```
After this, the executable `khalorg` will be available.
### For development
If you want to develop the code, debug it, and test it, run:
```bash
pip install -e '.[test,debug]'
```
## Usage
Use `khalorg --help` to get information about the cli of `khalorg`. The
following section discuss the `khalorg` commands that are available.
### List: from khal to org
Agenda items from `khal` can be converted to org items using the
`khalorg list` command. For examples:
```bash
khalorg list my_calendar today 90d > my_calendar.org
```
Here, the `khal` agenda items of the calendar `my_calendar` are
converted to org format and written to a file called `my_calendar.org`.
The range is specified from `today` till `90d` (90 days) in the future.
For more information about the allowed date formats, check the
`khal list` command, which is used for this functionality. It is assumed
that the `khal` calendar called `my_calendar` exists. Make sure
`my_calendar` is a calendar that exists on your local file system.
#### –format
If `khalorg list --format` option 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 the
`khalorg list --format` option, or you can place your custom format at
`$HOME/.config/khalorg/khalorg_format.txt` this format will then be used
instead of the default one that is shown below.
```org
* {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 property
the following keys are supported but are typically reserved for internal use
and are therefore less informative:
- `{until}`: the until property value. Is empty when using `khalorg list`.
- `{rrule}`: the ICal RRULE of the item.
#### Recurring items
The `khalorg list` command relies on the `khal list` command. Using this
command the `RRULE` of 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]`. Complex `RRULEs` are 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.
```org
* 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,
Someone
```
### New: from org to khal
An org agenda item can be converted to a new `khal` agenda item by
feeding the org item through stdin to `khalorg new` and specifying the
khal calendar name as a positional argument. For example, the consider
the org item below, which is saved as `meeting.org`.
```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,
Someone
```
This item can be converted to the `khal` calendar called
"my<sub>calendar</sub>" as follows:
```bash
cat meeting.org | khalorg new my_calendar
```
It is assumed that the `khal` calendar called "my<sub>calendar</sub>"
exists. Make sure "my<sub>calendar</sub>" is a calendar that exists on
your local file system.
#### Recurring items
Only 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 use `khalorg edit` to change the fields that need
editing (e.g., the description).
#### Attendees
Optionally, attendees can be added to the `ATTENDEES` property field.
The attendees will be added to the `Attendees` field of `khal`. Once you
synchronize `khal` with a server (e.g., outlook) an invitation will be
send to the attendees.
### Edit: from org to khal
Existing `khal` events can be updates by feeding an org file with the
corresponding UID through stdin to the `khalorg edit` command. For
example, the org agenda item of <span class="spurious-link"
target="New">_New_</span> can be altered and used as an input for
`khalorg edit`, as long as the UID remains untouched.
```org
* 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,
Someone
```
Next, run the following command:
```bash
cat meeting.org | khalorg edit my_calendar
```
When using `khalorg edit` please consider the following:
- Editing an existing event is different from creating a new one as the
original `icalendar` file is retained. Only parts of it are altered.
This is convienent when the icalendar file contains information that
cannot be generated by `khalorg`. For example, a Microsoft Team
meeting.
- Only the PROTO event is edited, i.e., the whole series is altered not
only the occurence.
- `khal edit` will only update the dates + recurrence if the
`--edit-dates` flag 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 khal
An event can be deleted from a khal calendar by feeding an org file to the
`khalorg delete` command 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 the <span class="spurious-link" target="New">_New_</span> command
above can be removed by feeding the same file to `khalorg delete`:
```bash
cat meeting.org | khalorg delete my_calendar
```
#### Recurring items
When deleting recurring items the whole series will be removed. Removing
occurrences is not supported.
## Neovim plugin
The neovim plugin can be found here:
[nvim-khalorg](https://github.com/BartSte/nvim-khalorg). Check out the demo at
the top of the [page](#demo).
## Workflow for Office 365
The diagram below illustrates the workflow than can be achieved when using
`khalorg`. The folder `extras`, on the
[GitHub](https://github.com/BartSte/khalorg) page, contains a `bash` script
called `calsync`, that synchronizes `vdirsyncer` calendars and exports them as
an org file using the `khalorg list` command. Davmail is used as the CalDav
server in this specific example.
```example
┌──────────┐
│Office 365│
└┬─────────┘
┌▽──────┐
│Davmail│
└┬──────┘
┌▽─────────┐
│vdirsyncer│
└┬─────────┘
┌▽───┐
│khal│
└┬───┘
┌▽───────┐
│khalorg │
└┬───────┘
┌▽───────┐
│org mode│
└────────┘
```
## Troubleshooting
If you encounter any issues, please report them on the issue tracker at:
[khalorg issues](https://github.com/BartSte/khalorg/issues)
## Contributing
Contributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for
more information.
## License
Distributed under the [MIT License](./LICENCE).
## Improvements:
- [ ] Timezones are not yet supported, so `khalorg` will only work when
you agenda remain in the timezone that you specified within your
`khal` config.
- [ ] Running khal commands directly from a script in not
straightforward. Therefore, khal is executed as a subprocess, by using
its command line interface.
- [ ] `khalorg new` and `khal edit` only 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 the `orgagenda`. To achieve
this the following could be build:
- [ ] When multiple timestamps without an org repeater are provided,
find the `RRULE` that describes them. Also, set the `UNTIL` date to
the last date. If no `RRULE` can be found, raise an error. Another
option could be to use the `RDATE` option of ICal.
- [ ] When multiple timestamps with an org repeater are presented, try
to find the `RRULE` that describes them.
Raw data
{
"_id": null,
"home_page": null,
"name": "khalorg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "khal, org mode, vdirsyncer, CalDav, agenda, emacs, neovim, orgmode-nvim",
"author": "BartSte",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1f/d7/f1fef871c7149bfd87d973ba4772f8183b3c008d5608a0d19e1aa920e997/khalorg-0.0.3.tar.gz",
"platform": null,
"description": "# Khalorg\n\n[Click here for the GitHub page.](https://github.com/BartSte/khalorg)\n\n<img src=\"./demo/logo.jpg\" width=50%>\n\n## Demo\n\nThe demo below demonstrates the following features using the neovim plugin\ncalled [nvim-khalorg](https://github.com/BartSte/nvim-khalorg):\n\n- `khalorg new`: convert an org agenda item into a `khal` agenda item.\n- `khalorg list`: convert a `khal` agenda item into an org agenda item.\n- `khalorg edit`: edit an existing `khal` agenda item with org mode.\n- `khalorg delete`: delete an existing `khal` item.\n\n\n\n## Contents\n\n<!--toc:start-->\n\n- [Demo](#demo)\n- [Contents](#contents)\n- [Introduction](#introduction)\n - [Definitions](#definitions)\n - [Motivation](#motivation)\n - [Features](#features)\n- [Installation](#installation)\n - [PyPi](#pypi)\n - [From source](#from-source)\n - [For development](#for-development)\n- [Usage](#usage)\n - [List: from khal to org](#list-from-khal-to-org)\n - [\u2013format](#format)\n - [Recurring items](#recurring-items)\n - [New: from org to khal](#new-from-org-to-khal)\n - [Recurring items](#recurring-items)\n - [Attendees](#attendees)\n - [Edit: from org to khal](#edit-from-org-to-khal)\n - [Delete: from org to khal](#delete-from-org-to-khal)\n - [Recurring items](#recurring-items)\n- [Neovim plugin](#neovim-plugin)\n- [Workflow for Office 365](#workflow-for-office-365)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n- [Improvements:](#improvements)\n\n<!--toc:end-->\n\n## Introduction\n\n`khalorg` is an interface between Org mode and Khal cli calendar.\n\n### Definitions\n\n- [CalDav](https://en.wikipedia.org/wiki/CalDAV): internet standard for client access to calendars\n- [Davmail](https://davmail.sourceforge.net/e): CalDav exchange gateway\n- [khal](https://github.com/pimutils/khal): command line calendar app\n- [khalel](https://gitlab.com/hperrey/khalel): interface between emacs and khal\n- [nvim-orgmode](https://github.com/nvim-orgmode/orgmode): org mode for neovim\n- [org](https://orgmode.org): plain text system for keeping notes, agendas and more\n- [vdirsyncer](https://github.com/pimutils/vdirsyncer): synchronizes calendars and addressbooks between servers and the local file system\n\n### Motivation\n\nI use org mode to manage my agenda and my notes. However, in a professional\nsetting, you are often required to use proprietary software for your agenda,\nlike Office 365. Luckily, programs exist that can synchronize agendas from\ndifferent sources, by implementing the CalDav standard. Personally, I like to\nuse `vdirsyncer` with `khal` to synchronize my agendas. To bridge the gap\nbetween `khal` and `org mode`, only 1 program exists called: `khalel`. However,\nthis program is designed for `emacs`. Since there are also org mode users\noutside of `emacs` (e.g. `neovim`), `khalorg` aims to be a general interface\nbetween `vdirsyncer`/`khal` and `org mode`.\n\nBased on the above, the following workflow is desired:\n\n```example\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502CalDav\u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502vdirsyncer\u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2510\n\u2502khal\u2502\n\u2514\u252c\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502khalorg \u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502org mode\u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### Features\n\n- [x] Can be used by org mode for emacs, vim and neovim.\n- [x] Vdirsyncer calendars can be manipulated by using the cli of `khal`\n as the interface.\n- [x] `khalorg new`: convert an org agenda item into a `khal` agenda\n item.\n- [x] `khalorg list`: convert a `khal` agenda item into an org agenda\n item.\n- [x] `khalorg edit`: edit an existing `khal` agenda item with org mode.\n- [x] `khalorg delete`: delete an existing `khal` item.\n- [x] Recurring items are supported by providing an org repeater in the\n time stamp (e.g., `+1w`). The following is supported:\n - the follow org repeaters: `+{integer}{d,w,m,y}`\n - `khalorg new` and `khalorg edit --edit-dates` support 1 time stamp\n per org agenda item.\n - `khalorg list` concatenates timestamps that cannot be describes by\n an org repeater, resulting in an org agenda item with multiple\n timestamps.\n - Supports an `until` date for recurring items. The until date can be\n supplied through an org property `UNTIL`.\n- [x] Has unittests\n- [x] Includes an Office 365 workflow with a bash script\n- [x] Semantic versioning\n- [x] Gifs with demos\n- [x] Neovim plugin\n- [x] Is available on PyPI\n\n## Installation\n\nFor safety, always make a back-up of your calendar before installing software\nthat is new to you.\n\nMake sure your `khal` date format is compatible with org, otherwise it\nwill not work. When running `khal printformats` you should get:\n\n```example\nlongdatetimeformat: 2013-12-21 Sat 21:45\ndatetimeformat: 2013-12-21 Sat 21:45\nlongdateformat: 2013-12-21 Sat\ndateformat: 2013-12-21 Sat\ntimeformat: 21:45\n```\n\nIf not, check the documentation of `khal` on how to change this.\n\n### PyPi\n\nInstall by running the following command:\n\n```bash\npip install khalorg\n```\n\n### From source\n\nSet your current working directory to the root directory, i.e, the\ndirectory containing the `pyproject.toml` file. Next, run:\n\n```bash\npip install .\n```\n\nAfter this, the executable `khalorg` will be available.\n\n### For development\n\nIf you want to develop the code, debug it, and test it, run:\n\n```bash\npip install -e '.[test,debug]'\n```\n\n## Usage\n\nUse `khalorg --help` to get information about the cli of `khalorg`. The\nfollowing section discuss the `khalorg` commands that are available.\n\n### List: from khal to org\n\n\n\nAgenda items from `khal` can be converted to org items using the\n`khalorg list` command. For examples:\n\n```bash\nkhalorg list my_calendar today 90d > my_calendar.org\n```\n\nHere, the `khal` agenda items of the calendar `my_calendar` are\nconverted to org format and written to a file called `my_calendar.org`.\nThe range is specified from `today` till `90d` (90 days) in the future.\nFor more information about the allowed date formats, check the\n`khal list` command, which is used for this functionality. It is assumed\nthat the `khal` calendar called `my_calendar` exists. Make sure\n`my_calendar` is a calendar that exists on your local file system.\n\n#### \u2013format\n\nIf `khalorg list --format` option is not defined, the default one is\nused which can be found at `./khalorg/static/khalorg_format.txt`. If you\nwant to define your own format, you have 2 options: you can use the\n`khalorg list --format` option, or you can place your custom format at\n`$HOME/.config/khalorg/khalorg_format.txt` this format will then be used\ninstead of the default one that is shown below.\n\n```org\n* {title}\n {timestamps}\n :PROPERTIES:\n :ATTENDEES: {attendees}\n :CALENDAR: {calendar}\n :CATEGORIES: {categories}\n :LOCATION: {location}\n :ORGANIZER: {organizer}\n :STATUS: {status}\n :UID: {uid}\n :URL: {url}\n :END:\n {description}\n```\n\nthe following keys are supported:\n\n- `{attendees}`: a comma separated list of email addresses of attendees\n- `{calendar}`: the name of the khal calendar\n- `{categories}`: the categories property of the item\n- `{description}`: the description of the item\n- `{location}`: the location of the item\n- `{organizer}`: the email of the organizer\n- `{status}`: the status of the item, e.g., TENTATIVE or ACCEPTED\n- `{timestamps}`: the timestamp of the item\n- `{title}`: the summary of the item\n- `{uid}`: the UID of the item\n- `{rrule_until}`: the until value of the RRULE.\n- `{url}`: the url property\n\nthe following keys are supported but are typically reserved for internal use\nand are therefore less informative:\n\n- `{until}`: the until property value. Is empty when using `khalorg list`.\n- `{rrule}`: the ICal RRULE of the item.\n\n#### Recurring items\n\nThe `khalorg list` command relies on the `khal list` command. Using this\ncommand the `RRULE` of each item is retrieved to created the correct org\nrepeater. Only simple org repeaters are supported that have the\nfollowing form: `+[number][h,w,m,y]`. Complex `RRULEs` are described by\nconcatenating the corresponding timestamps within 1 agenda item,\nresulting in a list of items. For example, the agenda item below\nrepresents a weekly recurring event where the first meeting was moved to\nanother date, resulting in a timestamp without a repeater, and one with\na repeater.\n\n```org\n* Meeting\n <2023-01-05 Thu 01:00-02:00>\n <2023-01-08 Sun 01:00-02:00 +1w>\n :PROPERTIES:\n :UID: 123\n :LOCATION: Somewhere\n :ORGANIZER: Someone (someone@outlook.com)\n :ATTENDEES: test@test.com, test2@test.com\n :URL: www.test.com\n :END:\n Hello,\n\n Lets have a meeting.\n\n Regards,\n\n\n Someone\n```\n\n### New: from org to khal\n\n\n\nAn org agenda item can be converted to a new `khal` agenda item by\nfeeding the org item through stdin to `khalorg new` and specifying the\nkhal calendar name as a positional argument. For example, the consider\nthe org item below, which is saved as `meeting.org`.\n\n```org\n* Meeting\n <2023-01-01 Sun 01:00-02:00 +1w>\n :PROPERTIES:\n :UID: 123\n :LOCATION: Somewhere\n :ORGANIZER: Someone (someone@outlook.com)\n :ATTENDEES: test@test.com, test2@test.com\n :URL: www.test.com\n :END:\n Hello,\n\n Lets have a meeting.\n\n Regards,\n\n\n Someone\n```\n\nThis item can be converted to the `khal` calendar called\n\"my<sub>calendar</sub>\" as follows:\n\n```bash\ncat meeting.org | khalorg new my_calendar\n```\n\nIt is assumed that the `khal` calendar called \"my<sub>calendar</sub>\"\nexists. Make sure \"my<sub>calendar</sub>\" is a calendar that exists on\nyour local file system.\n\n#### Recurring items\n\nOnly 1 timestamp per org item is supported. Note that the meeting above\nis repeated every week (`+1w`). Only simple org repeaters are supported\nthat have the following form: `+[number][h,w,m,y]`. These events repeat\nforever, unless you specify an end date using the \\`UNTIL\\` property in\nthe org file.\n\nPersonally, when I need to create a complex repeat pattern (or when I\nneed outlook specific items like a Teams invite), I create the event in\noutlook first. Next, I use `khalorg edit` to change the fields that need\nediting (e.g., the description).\n\n#### Attendees\n\nOptionally, attendees can be added to the `ATTENDEES` property field.\nThe attendees will be added to the `Attendees` field of `khal`. Once you\nsynchronize `khal` with a server (e.g., outlook) an invitation will be\nsend to the attendees.\n\n### Edit: from org to khal\n\n\n\nExisting `khal` events can be updates by feeding an org file with the\ncorresponding UID through stdin to the `khalorg edit` command. For\nexample, the org agenda item of <span class=\"spurious-link\"\ntarget=\"New\">_New_</span> can be altered and used as an input for\n`khalorg edit`, as long as the UID remains untouched.\n\n```org\n* Edited meeting\n <2023-01-01 Sun 01:00-02:00 +1w>\n :PROPERTIES:\n :UID: 123\n :ORGANIZER: Someone (someone@outlook.com)\n :ATTENDEES: other@test.com\n :END:\n Hello,\n\n I edited the meeting by removing the location and url. I also changed the\n title and the attendees field.\n\n Regards,\n\n\n Someone\n```\n\nNext, run the following command:\n\n```bash\ncat meeting.org | khalorg edit my_calendar\n```\n\nWhen using `khalorg edit` please consider the following:\n\n- Editing an existing event is different from creating a new one as the\n original `icalendar` file is retained. Only parts of it are altered.\n This is convienent when the icalendar file contains information that\n cannot be generated by `khalorg`. For example, a Microsoft Team\n meeting.\n- Only the PROTO event is edited, i.e., the whole series is altered not\n only the occurence.\n- `khal edit` will only update the dates + recurrence if the\n `--edit-dates` flag is passed. This avoids editing the start-stop date\n when editing an event that contains multiple timestamps (which are not\n supported).\n\n### Delete: from org to khal\n\n\n\nAn event can be deleted from a khal calendar by feeding an org file to the\n`khalorg delete` command through stdin. The org file must contain an agenda\nitem with a non-empty UID property. For example, the khal event that was\ncreated using the <span class=\"spurious-link\" target=\"New\">_New_</span> command\nabove can be removed by feeding the same file to `khalorg delete`:\n\n```bash\ncat meeting.org | khalorg delete my_calendar\n```\n\n#### Recurring items\n\nWhen deleting recurring items the whole series will be removed. Removing\noccurrences is not supported.\n\n## Neovim plugin\n\nThe neovim plugin can be found here:\n[nvim-khalorg](https://github.com/BartSte/nvim-khalorg). Check out the demo at\nthe top of the [page](#demo).\n\n## Workflow for Office 365\n\nThe diagram below illustrates the workflow than can be achieved when using\n`khalorg`. The folder `extras`, on the\n[GitHub](https://github.com/BartSte/khalorg) page, contains a `bash` script\ncalled `calsync`, that synchronizes `vdirsyncer` calendars and exports them as\nan org file using the `khalorg list` command. Davmail is used as the CalDav\nserver in this specific example.\n\n```example\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502Office 365\u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502Davmail\u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502vdirsyncer\u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2510\n\u2502khal\u2502\n\u2514\u252c\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502khalorg \u2502\n\u2514\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u25bd\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502org mode\u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Troubleshooting\n\nIf you encounter any issues, please report them on the issue tracker at:\n[khalorg issues](https://github.com/BartSte/khalorg/issues)\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING](./CONTRIBUTING.md) for\nmore information.\n\n## License\n\nDistributed under the [MIT License](./LICENCE).\n\n## Improvements:\n\n- [ ] Timezones are not yet supported, so `khalorg` will only work when\n you agenda remain in the timezone that you specified within your\n `khal` config.\n- [ ] Running khal commands directly from a script in not\n straightforward. Therefore, khal is executed as a subprocess, by using\n its command line interface.\n- [ ] `khalorg new` and `khal edit` only support 1 timestamp per item.\n However, it is desired that all timestamps within 1 org agenda item,\n end up in 1 khal event, as is the case for the `orgagenda`. To achieve\n this the following could be build:\n - [ ] When multiple timestamps without an org repeater are provided,\n find the `RRULE` that describes them. Also, set the `UNTIL` date to\n the last date. If no `RRULE` can be found, raise an error. Another\n option could be to use the `RDATE` option of ICal.\n - [ ] When multiple timestamps with an org repeater are presented, try\n to find the `RRULE` that describes them.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "An interface between Org mode and Khal cli calendar.",
"version": "0.0.3",
"project_urls": null,
"split_keywords": [
"khal",
" org mode",
" vdirsyncer",
" caldav",
" agenda",
" emacs",
" neovim",
" orgmode-nvim"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c02de0fe4710a3579d5135fc5ad810c22342d0f436a292f4452fefb0b238e019",
"md5": "3e698614f61ee08bafbf8ddebe1163ad",
"sha256": "1935453c16d6cfe069fc61507dead3d10faea5160131e7dfb473eff128a0a04a"
},
"downloads": -1,
"filename": "khalorg-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e698614f61ee08bafbf8ddebe1163ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 31091,
"upload_time": "2024-04-16T10:40:46",
"upload_time_iso_8601": "2024-04-16T10:40:46.132145Z",
"url": "https://files.pythonhosted.org/packages/c0/2d/e0fe4710a3579d5135fc5ad810c22342d0f436a292f4452fefb0b238e019/khalorg-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1fd7f1fef871c7149bfd87d973ba4772f8183b3c008d5608a0d19e1aa920e997",
"md5": "2ec6443a431cbf4d58e0160bd77f0673",
"sha256": "d2fad79f1e58d44f63f1966b8109de1a0cffcdc76992320ae9a3d69f381f4c71"
},
"downloads": -1,
"filename": "khalorg-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "2ec6443a431cbf4d58e0160bd77f0673",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 5841236,
"upload_time": "2024-04-16T10:40:48",
"upload_time_iso_8601": "2024-04-16T10:40:48.380628Z",
"url": "https://files.pythonhosted.org/packages/1f/d7/f1fef871c7149bfd87d973ba4772f8183b3c008d5608a0d19e1aa920e997/khalorg-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-16 10:40:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "khalorg"
}
JSON