REM2ICS(1)

NAME
rem2ics - convert the output of "remind -s" into RFC2445 iCalendar format.

SYNOPSIS
TZ=timezone rem2ics [-man] [-do] [-norecur] [-usetag] <input >output

OPTIONS AND ARGUMENTS

-man
    Print the manual page and exit.

-do Actually do the conversion. Otherwise just print a brief help message and usage example, and then exit.

-norecur
    Do not attempt to detect and fold together recurring events.

-usetag
    Generate UIDs using remind TAG clauses.

Input is from standard input

Output is to standard output.

USAGE
  remind -s360 -irem2ics=1 ~/.reminders 1 Jan 1991 | TZ=PST8PDT rem2ics -do >reminders.ics

This tells remind to use ~/.reminders, and to process the entire range of dates it can handle (from Jan 1 1991 to Dec 31 2020), and to define a variable named "rem2ics", which can be used in "IF !defined("rem2ics")" / "ENDIF" pairs. rem2ics will use a timezone of PST8PDT, and will fold events that have the same name and duration into a single iCalendar VEVENT object.

NOTES

  Timezones and the TZ environment variable.
rem2ics uses the TZ environment variable to determine the value of the RFC2445 TZID property. If you are running on a Linux or other GNU libc based system, you probably don't (and probably shouldn't) normally have TZ set. You can confirm this by running "printenv TZ" at a shell prompt. If your remind data is in your "local time", and it probably is, you should probably set TZ to a good name for your local timezone just for the run of this script. You probably should NOT set TZ in your login scripts.

You can use TZ like this:

  remind -s ~/.reminders | TZ=PST8PDT rem2ics -do >reminders.ics

or

  remind -s ~/.reminders | TZ=US/Pacific rem2ics -do >reminders.ics

If, for some reason, your remind files are all in GMT instead of localtime (you smart person you!), you can do this:

  remind -s ~/.reminders | TZ=GMT rem2ics -do >reminders.ics

or

  remind -s ~/.reminders | TZ=0 rem2ics -do >reminders.ics

and rem2ics will use the ISO8601 "Z" notation for GMT time in the ics file. (Other synonyms for GMT are the empty string (not the same as the TZ not set), "0", "Z", "Zulu", "Greenwitch", "GMT", "GMT+0, and "GMT-0".)

If you leave TZ undefined and unset, rem2ics will use the ISO8601 "T" notation date strings with no TZID property, which RFC2445 calls a "floating time". Who knows, it might work for you!

The TZ string value is literally incorporated into the iCalendar stream, so whatever your iCalendar-using application needs is what you should use. You may have to experiment a bit.

You can look around in "/usr/share/zoneinfo" to get the names of every timezone anywhere. This is the "Olson database" that RFC2445 refers to. Read the man page for tzfile(5) for more than you ever wanted to know about the format of these files, and about GNU libc's handling of timezones. As complex as it is, it's certainly better than what POSIX defines or what most legacy UNIX systems do, and most certainly better than Microsoft, who in their "cutting edge" "state of the art" "server" OS, still hasn't figured out that daylight time rules might be different in different years.

If you just ran rem2ics without reading all this stuff, or if you don't want to worry about it at all, and somehow your iCalendar application manager is able to guess the proper timezone for you, just leave TZ undefined, and rem2ics will use the ISO8601 "T" notation date strings with no TZID property, which RFC2445 calls a "floating time". Who knows, it might work for you!

  Detecting recurring events
rem2ics tries to detect recurring events. If any multiple events appear with exactly the text and exactly the same duration (including "no duration"), instead of multiple VEVENT objects, there will be just one VEVENT object, that will have a RFC2445 "RDATE" property.

rem2ics is not yet smart enough to derive an "RRULE" based recurrance. If you really want that feature, either implement it and send in a patch, or contact the author and convince him to do it.

  Other iCalendar Properties
rem2ics does not generate "DESCRIPTION" or "LOCATION". One would have to heuristically parse them out of the text, and everyone uses a idiosyncratic way of putting things in remind.

If the -usetag option is not used or no "TAG" is set for a reminder, rem2ics will synthesize "UID" properties for each VEVENT, but the UIDs will be different (and unique) for each run of rem2ics. If you run rem2ics twice and import the two resulting ICS streams into your new scheduling program, your appointments will appear twice. If, however, you have set "TAG" clauses in your reminders and activated -usetag, these will be used. The same applies for tags synthesized by remind's -y option. Hence, it is more useful to use the -y option than to let rem2ics synthesize UIDs, because the UIDs will stay the same across multiple runs.

  Other iCalendar Perl objects
Why does't rem2ics use any of the iCalendar Perl stuff in CPAN? Because I don't trust them, and they are too big for this app. One links to a binary library. Another hasn't been maintained since 1991, and is full of notes as to how buggy and incomplete it is. And so forth. I am not at this moment interested in groveling around in Net::iCal, DateTime::Format::iCal, Tie::iCal, iCal::Parser, or "libical".

  Previous implementation
There is a working quick & dirty rem2ics written in awk by Anthony J. Chivetta <achivetta@gmail.com>.

But it has the following problems: it doesn't escape the text, it doesn't handle events that cross over midnight, it doesn't do timezones, it doesn't enforce the correct EOL sequence, and it doesn't fold long lines. This is a replacement for that script.

TODO
 If TZ not set, grab out of system config somewhere
 Detect recurring events.
  If I'm REALLY smart, derive RRULE
 Handle characters not in US-ASCII. Latin1? UTF8?

VERSION HISTORY

version 0.1 2007-02-08
    First cut.

version 0.2 2007-02-09
    Reorg into multipass over a data structure.

version 0.3 2007-02-10
    Collapse repeating events. Fold output lines.

version 0.9 2007-02-11
    POD. Command line options. First public release.

version 0.91 2007-02-14
    Bug fix, error message for non-recurring events

version 0.92 2008-01-28
    Bug fix,
     rem2ics 0.91 chokes on timed reminders with
     duration using `remind -s` as it functions in remind-03.01.03.
     Remind 3.01 changed how the -s data is formated for events that have a duration
     Patch by Paul Hinze <paul dot t dot hinze at gmail dot com>
      and Michael Schultz <mjschultz at gmail dot com>

version 0.93 2009-06-25
    Add -usetag option to allow for UIDs to stay the same across multiple runs
     by using the remind TAG clause.
     Patch by Tim Weber <scy at scytale dot name>

SEE ALSO
<http://mark.atwood.name/code/rem2ics>

<http://en.wikipedia.org/wiki/ICalendar>

<http://tools.ietf.org/html/rfc2445>

<http://www.roaringpenguin.com/en/penguin/openSourceProducts/remind>

remind(1)

AUTHOR
Copyright 2007,2008,2009 by Mark Atwood <me+rem2ics@mark.atwood.name>. <http://mark.atwood.name/>.

Please report bugs (with patches, if possible).

Inspired by Anthony J. Chivetta <achivetta@gmail.com>'s rem2ics in awk.

Thank you to David Skoll <dfs@roaringpengiun.com<gt> for Remind, and to the IETF calsch wg for the iCalendar specification.