REM2ICS(1)                                                          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 recurrence.
       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 doesn'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 formatted 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>

       <https://dianne.skoll.ca/projects/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 Dianne Skoll <dianne@skoll.ca<gt> for Remind, and to the
       IETF calsch wg for the iCalendar specification.



perl v5.34.0                      2022-06-14                        REM2ICS(1)
