Skip to content

Commit 8d141b9

Browse files
author
Robert Horn
committed
Updated README and usage
1 parent 21b111b commit 8d141b9

File tree

1 file changed

+77
-29
lines changed

1 file changed

+77
-29
lines changed

README.md

Lines changed: 77 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -52,32 +52,37 @@ Example output:
5252
5353
```
5454

55+
### Dependencies
56+
57+
ical2org depends upon the forked library in
58+
https://github.com/rjhorniii/ics-golang. When the fork/pull request
59+
are processed this will be changed.
5560

5661
### Duplicates Management
5762

58-
If the duplicates option is present and provides a file, that
59-
file contains events that are already in org format. Duplicates of
60-
these events should not be generated as output. The duplicates file
61-
is scanned for ORGUIDs inside an ICALCONTENTS drawer. When the input
62-
files are processed the generated event ORGUIDs are compared with these
63-
ORGUIDs. Events with matching ORGUIDs are not output.
63+
If the duplicates option is present and provides a file, that file
64+
contains events that are already in org format. Duplicates of these
65+
events will not be generated as output. The duplicates file is
66+
scanned for ORGUIDs inside an ICALCONTENTS drawer. When the input
67+
files are processed, their event ORGUIDs are compared with the
68+
ORGUIDs from the duplicates file. Input events with matching ORGUIDs are
69+
not output.
6470

65-
The matching rule permits you to decide whether modified events are
71+
This matching rule permits you to decide whether modified events are
6672
treated as duplicates or not. If you remove the ORGUID from the
6773
drawer, a modified event will be treated as different, and a new org
68-
headline generated.
69-
70-
ical2org does not compare event contents. It only looks at the
71-
ORGUIDs.
74+
headline generated when that Ical event is processed again. If the
75+
ORGUID matches, no matter what other changes are made, a new org
76+
headline will not be generated.
7277

7378
This means that by you can change task status to DONE, etc., and the
74-
modified event will still be considered a duplicate. This way you
75-
need not ensure that all Ical sources are also updated when you change
76-
the org file. This should allow repeated conversion of old email
77-
attachments and calendars that show historical events. New events
78-
will not be created in the org file.
79+
modified event will still be considered a duplicate. You need not
80+
ensure that all Ical sources are also updated when you change the org
81+
file. This allows later conversion of old email attachments
82+
and calendars that contain historical events. New events will not be
83+
created in the org file for those duplicates.
7984

80-
The duplicates file can also be an orgmode file that is being manually
85+
The duplicates file can also be an orgmode file that is manually
8186
mainatined. In the manually maintained org drawer you list the ORGUIDs
8287
that should be considered duplicate:
8388

@@ -99,17 +104,14 @@ file with duplicates. The internal logic waits for duplicates file
99104
processing to complete before it begins event generation, so it is
100105
safe to have the output file and duplicates file be the same file.
101106

102-
ical2org depends upon the forked library in
103-
https://github.com/rjhorniii/ics-golang. Switch to the ical2org
104-
branch.
105107

106108
### Repeating events
107109

108110
There are good reasons to convert a repeating event into a single org
109111
headline, and good reasons to replicate the repeating event as
110112
multiple separate headlines. The flag ```repeats``` is used to
111113
control this. If missing, or present with ```repeats=true``` multiple
112-
org headlines will be generated. If ```repeasts=false```, only one
114+
org headlines will be generated. If ```repeats=false```, only one
113115
headline will be generated. In either case, the ```ICALCONTENTS```
114116
will contain the repeat rule, e.g., ```:RRULE:
115117
FREQ=WEEKLY;UNTIL=20180325T035959Z;BYDAY=SA```.
@@ -136,11 +138,57 @@ don't want to worry about whether at that time and location it is
136138
summer time or not. I find org agendas are most useful this way, even
137139
though different days and events are different time zones.
138140

139-
Therefore, this program converts everything assuming that the event
140-
creator local time zone is the one that matches my rule of "then/there
141-
time". This is not always correct. It is especially a problem for
142-
teleconferences across time zones. In the property ```TZIDS``` are the
143-
creator specified time zone(s) for the event. This allows a human to
144-
know what was sent. I then assume that between the description, the
145-
zones, and the times, a person can decide whether and how to adjust
146-
the active timestamps in the org file.
141+
This program converts everything assuming that the event creator local
142+
time zone is the one that matches my rule of "then/there time". This
143+
is most often, but not always, correct. It is especially a problem for
144+
teleconferences across time zones. In the property ```TZIDS``` are
145+
the creator specified time zone(s) for the event. This allows a human
146+
to know what was sent. I then assume that between the description,
147+
the zones, and the times, a person can decide whether and how to
148+
adjust the timestamps in the org file.
149+
150+
### Systemd example
151+
152+
The following files specify using `ical2org` to fetch a calendar from
153+
Google and update `events.org` at specified times.
154+
155+
Google-fetch.sh
156+
```
157+
#!/bin/bash
158+
cd ~/org-directory
159+
export https_proxy=https://192.168.1.1:8000
160+
/home/rjhorniii/bin/ical2org -d=events-g.org -a=events-g.org https://calendar.google.com/google-stuff
161+
```
162+
163+
google-fetch.service
164+
```
165+
[Unit]
166+
Description=Fetch events from my google calendar into events-g.org
167+
168+
[Service]
169+
Type=oneshot
170+
ExecStart=/home/rjhorniii/org-directory/google-fetch.sh
171+
```
172+
173+
google-fetch.timer, this example shows an irregular polling interval
174+
```
175+
[Unit]
176+
Description=Fetch events timer
177+
178+
[Timer]
179+
OnCalendar=*-*-* 6,8,10,12,13,14,16,18,23:10
180+
Unit=google-fetch.service
181+
Persistent=true
182+
183+
[Install]
184+
WantedBy=timers.target
185+
```
186+
187+
Put the `service` and `timer` in `~/.config/systemd/user`. To run it immediately
188+
and then at the usual schedule use the commands:
189+
190+
```
191+
systemctl --user daemon-reload
192+
systemctl --user start google-fetch.timer
193+
systemctl --user enable google-fetch.timer
194+
```

0 commit comments

Comments
 (0)