
{~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~}

    gpcalendar : A calendar for programmers (and others...)
    Copyright (C) 2002-5 Andrew Robertson <critter_75075@yahoo.com>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

{~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~}

For more information, see my website at http://www.geocities.com/critter_75075/,
http://64.81.113.250/os.html, or email me at critter_75075@yahoo.com

GPCalendar, or Gtk Programmers Calendar, is intended for technical people who
do not think about days in terms of events and tasks, but think about them in
terms of files and projects.  Also, it is intended for people who 'log' their
activities every day but may not know what they will do tomorrow.

This started as a project several years ago in Gtk-Perl.  But, that fell by the
wayside when I could not get it working under Windows.  This new version
(written in several months) is in GTK-Freepascal and compiles equally well on
Linux and Windows!  For more information, please see http://www.freepascal.org/.

The default (and currently only) calendar format is a simple directory.
Within the directory are files and sub directories.  Files and sub directories
(at the first level) are named with a DTS (date time stamp) prefix, following
ISO 8601 style times.  If the entries are files, they have a suffix that allows
intelligent handling (GVim for .txt, Mozilla for .html etc).  Directories only
have a date and a topic.  Every file and directory has a topic in it's name.
Date prefixes, topics, and type suffixes are or will be optional.  So, you may
have a directory named Journal in your home directory (or Projects, or
Calendar) for all of the calendar/log entries.  An example sub directory may be
named 20020826.gpcalendar .  An example file may be named
20020826.staff_meeting.txt .  Another valid file may be named 20020826.txt .
Or, even just txt .  However, files that have only one element in their names
will not be parsed for now.  An example directory listing is:

/home/andy/Journal/20020805.gpcalendar/
/home/andy/Journal/20020806.party_pictures/
/home/andy/Journal/20020807.txt
/home/andy/Journal/20021005.staff_meeting.html
/home/andy/Journal/20031031.company_party/

You may have multiple calendar directories.  Future entries (entries with
dates greater than today) are valid.

Time of day support is in progress.  You can have entries such as
2004-06-12T13:42 representing 1:42 PM on June 12th, and the entry will show
up on June 12th, however nothing will be done with the time.

You may also use some shortened ISO 8601 style dates as date wildcards.  So,
---7 would match any/every Saturday.  --07 the seventh of any month.  And, -0612
would match June 12th of any year.  Useful for birthdays, hollidays, and other
important dates.  Once diference here is that day 1 is Sunday, not Monday.
So, you could have a directory representing bills due like:
/home/andy/Bills/--05.Rent_Due
/home/andy/Bills/--06.Phone_Bill.txt
/home/andy/Bills/--17.Power_Bill.txt
/home/andy/Bills/---6.Check_Stocks/
Where Rent_Due shows up as an entry on the fifth of every month, Power_Bill.txt
shows up as an entry on the 17th of every month, and Check_Stocks shows up as
an entry every Friday.  Clicking on an entry in any period will always edit
the same entry.

Periods are now supported as well.  ISO 8601 periods are denoted with a P
after date/time.  The periods are then represented by an integer and a
type.  Supported periods are hmsywd for Hours, Minutes, Seconds, Years, Weeks,
Days respectively.  To add a period of four days to an entry, post the suffix
4d to the date-time stamp.  For a period of 9 hours, post the suffix 9h to the
date-time stamp and so on.  For example, you should have an entry called
20050902P4d.Anime_Fest for an entry four days long starting on 2005-09-02.
With this, an entry called Anime_Fest will show up in each of the four days
starting September 2nd.  Periods in the standard may be denoted with a / and
a additional date time stamp.  However, that is not really supported as Unix
does not like forward slashes in file names.

For more information on ISO 8601 style dates, please see 
http://www.cl.cam.ac.uk/~mgk25/iso-time.html .  In the standard, and soon
in GPCalendar, not only are dates supported, but times, time periods, time
zones and repetition are all handled.  Also, punctuation may be included or
left out.  So, 2004-06-10 10:12 -06:00 6H is just as good as
200406101012-06:00P6H for representing "Six hours, in GMT -6, starting at
10:12 AM on June 10th, 2004".  However, time zones/periods/times are not
yet supported in GPCalendar.

Entries are opened by 'handlers', external applications which are executed in
the background by gpcalendar.  Copying entries is also handled by external
commands.  So, when you click on a file entry, GPCalendar attempts to
determine which program should open that file, then loads that file with that
application.  .html for Mozilla, .txt for GVim, etc.

When you are starting with gpcalendar, you will need to copy the supplied
gpc_config.dat file to your home directory, and edit the entries to have your
calendar paths/handlers.

Any ideas/flames/code are welcome.

Enjoy!
     andy
