calmas: Calendar widget for Symbian^3

$Id: README.txt,v 1.12 2011/07/13 10:21:31 mas Exp $
Copyright (C) 2011 Marc Andre Selig

calmas 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 3 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, see <http://www.gnu.org/licenses/>.


Synopsis:

Reads the calendar from an emacs style diary file and displays it both
as a WRT app and as a home screen widget.

In the settings screen, you can choose the URL from which the diary is
read.  Both local and remote URLs work.  Data is cached locally and
only re-loaded after the "refresh data" timer (as set in the settings
dialogue) runs out.  The cache uses WRT persistent storage to store
data and its timestamp, thus surviving restarting or rebooting.

Updates respect the "widgets offline" setting.  If the diary URL is a
remote location, it is never updated automatically while widgets are
set to offline.  If a manual update is requested while widgets are
offline, a confirmation dialog is shown before going online.

Updating uses your webkit installation.  This means that frequent
updates might be fulfilled from the webkit cache instead of the net.
You can update manually in that case, which circumvents the cache and
forces a reload.

Due to limitations of the platform, the application refreshes only
upon interaction with you.  (The WRT runtime environment stops timers
once any WRT widget exists in the home screen, so we emulate timers
upon interaction with the user.  We still try to use the timer, in
addition to that.)

Note that Web Runtime has no support for signed wgz files.  An
external GnuPG signature has been provided for your security.


Diary:

The home screen widget displays events that are upcoming next.  It
reads from the beginning of your diary file, skipping all events that
are already in the past.  This way, you can push irrelevant events
(that should take no space on your home screen) to the end of the file
and have the program only display relevant events from the beginning
of the file.

Diary formatting is only relevant to select relevant lines for the
home screen widget.  If you plan to use the full screen view
exclusively, you can use any which format.

You decide whether your dates are in mm/dd or dd/mm format.  The
following examples all use dd/mm, but that changes with your setting.

The program understands a subset of the emacs diary format, handling
three kinds of events: (a) regular entries, (b) diary blocks, (c)
anniversaries.

(a) Regular entries should be formatted as follows:

[;&]date	[time]	[Todo] Text

A semicolon ";" at the beginning of a line marks a comment; the whole
line is ignored.

An ampersand "&" at the beginning of a line marks a non-printing item;
the & is ignored.

Valid formats for the date are:

dd/mm		for repeating items;
dd/mm/yy	for regular items

Valid formats for the time are:

hh:mm		for point-in-time events;
		they are hidden after this time has passed
hh:mm-hh:mm	for events with a duration;
		they are hidden after the end time has passed

Entries without a time are hidden after the given day has passed.

The string "Todo" (capitalization insensitive) at the beginning of the
event description marks an event as a todo item instead of a regular
event.  Depending on user preference, todo items that are still in the
diary file can be shown even after they have passed (in case you like
to keep todo items around until you have completed them, ignoring the
due date).

(b) There is also support for diary blocks that span several days:

[;&]%%(diary-block dd mm yyyy dd mm yyyy) Text

Again, leading semicolons ";" mark comments which are ignored, while
leading ampersands "&" mark non-printing entries which are kept.

Diary block items are displayed until the last day (given second) has
passed.  In the home screen view, they are slightly reformatted to
save space.

(c) Anniversaries take this form:

[;&]%%(diary-anniversary dd mm yyyy) Name

For home screen view, they are reformatted to display the date in
regular format and the name with a leading asterisk "*".