
                              Almanak

                     (c) 1992-96 Tormod Tjaberg

Almanak is free software, distributed under the terms of the
GNU General Public License. Almanak comes with no warranty at
all. For details see the file COPYING.

Almanak is a program for keeping track of important dates and events.
With almanak you can remember all those birthdays and wedding dates
that you usually forget. Almanak is also great for keeping track or
repeating events i.e. every year on the 29'th of September you go on
a 'hunting' trip with some pals.

Almanak works by processing an event file of predefined events. If an
event is close to the current date, a format string depicting the nature 
of the event is displayed. The format string is defined by the user and 
can contain all sorts of information (see below for details). The only
system dependant part of almanak is that it requires a system clock that
is set to the correct date.

When almanak is invoked it first tries to find it's default event file, 
called 'almanak.evt'. Almanak does this by first looking in the current
directory, the execution directory ( only in DOS ver 3.0  & above ) and 
then along the directories in your 'path' environment variable. If almanak
can't find it's default file using any of these methods, and there is not
an alternate file specified on the command line, almanak fails and displays
an error message. If an alternate file is specified on the command line 
almanak uses that file instead of trying to find 'almanak.evt'. Multiple
files can be specified on the command line.

In addition to specifying alternate files on the command line almanak
has the following command line parameters. A command line parameter is 
specified by the prefix '-'.

-h    - Display a short usage summary of the program

-d<n> - Display format string when it's 'n' or less days left until event.
        This option overrides all offsets specified in the event file(s).
 
-b<n> - Sound bell when it's 'n' or less days left until event.

-o    - Process event file only once a day. A check is made to see if the
        event file has the same date as todays date. If it has, the event
        file is ignored. If not, the file is 'stamped' with todays date
        and processed. With this option specified you will only be informed
        of events once a day. Great to have in your login script. 
   
-r    - Run the program 'prg' if an event is today. This is typically
        used to get some more attention. The program in only run once
        even if many events occur on the same day.

example of command line usage:

almanak friends.evt -o -d10 -b5   

processes file 'friends.evt' only once a day, only displays events that
are 10 days away and beeps when it's 5 or less days until event.

almanak -d10 -b2
 
processes default file 'almanak.evt', only displays events that
are 10 days away and beep if 2 or less days until event.

almanak -d10 -b3 -r "c:\util\wplay warning.wav"

processes default file 'almanak.evt', only displays events that
are 10 days away and beep if 3 or less days until event. If an event
is today play the sound file 'warning.wav'
     

When creating almanak great emphasis was put on the output format string.
It is extremely user definable, see the following section for details.


Almanak event file format:

A valid event file consists of comments, blank lines and event entries.
Comments, blank lines and event entries can be freely interchanged.


Format of event entry: 

Each of the 'tokens' in an event entry string must be separated 
by one or several whitespace characters.

'Offset' 'Day' 'Month' 'Year' 'Format'


Offset - Display format string when it's 'Offset' or less days until
         event. This value can be overridden by the command line parameter
         '-d<n>'. Offset must be in the range 0 to 365.
Day    - Day of the month that the event took place.     ( 1..31 )
Month  - Month that the event took place.                ( 1..12 )
Year   - Year that the event took place, if year is unknown enter ??
         note that the year cannot be in the future. However one is allowed
         to specify todays date and negative years. Ie a value of -30
         is 30 years B.C. 
Format - A format string which determines how the output message will be 
         presented. A format string consists of ASCII characters and
         special conversion characters. The special conversion characters
         are always preceded by a '\' or a '%'. The conversion character 
         is case sensitive ie. '%C' is not the same as '%c'. Multiple 
         occurrences of a conversion character is allowed in the format 
         string.  
    
         Example: %C - expands to year the event took place if available
                  %c - expands to appropriate date and time for locale

Description of special characters

';'  - the rest of the line is a comment and is ignored, comments can be 
       placed anywhere. Great for keeping addresses and small reminders.
';;' - the character ';'
'\'  - followed by a new line, format string is continued 
       on the next line
'\\' - the character '\'
'%'  - the start of a format conversion character
'%%' - the character '%'
'\n' - output a new line 


Description of conversion characters regarding the event.

%C - year of event if available, if year not available '????'
%e - 'in X days' ( X is number of days left ) or 'tomorrow' or 
     'today' depending on how many days left until event.
%E - 'In X days' ( X is number of days left ) or 'Tomorrow' or 
     'Today' depending on how many days left until event.
%n - number of days left until event ( 1..365 )
%o - 'day' or 'days' according to number of days left until event. 
%O - 'Day' or 'Days' according to number of days left until event.
%l - length of life span ( age ), calculated from year of the event 
     ( if available ) subtracted from current year. If year of event
     is unavailable it's expanded to '??'.
%t - 'year' or 'years' according to age, if age is unknown: 'year(s)'.
%T - 'Year' or 'Years' according to age, if age is unknown: 'Year(s)'.


Description of date & time format conversion characters. 

Note: time is current time, date is date of event.
Note: C programmers, the conversion characters are the
      same as used by the function strftime.

%a - abbreviated weekday name
%A - full weekday name
%b - abbreviated month name
%B - full month name
%c - appropriate date and time for locale
%d - day of the month as a decimal
%H - hour (24-hour clock) as a decimal
%I - hour (12-hour clock) as a decimal
%j - Julian day of the year ( 001-366 )
%m - month as a decimal number
%M - minute as a decimal number
%p - locales equivalent of AM or PM.
%S - second as a decimal number
%U - week number of the year, with Sunday taken as the first day of the
     week, as a decimal number (00-53)
%w - weekday as a decimal number (0(Sunday)-6).
%W - week number of the year, with Monday taken as the first day of
     the week, as a decimal number (00-53)
%x - locales appropriate date representation
%X - locales appropriate time representation
%y - year (without century) as a decimal (00-99)
%Y - year (with century) as a decimal
%Z - time zone name or by no characters if no time zone is determinable

example 1:

65 29 10 1966 %E, %a %b %d %Y some person will be %l %t ( born %C )
|  |  |  |
|  |  |  year of event
|  |  month of event
|  day of event
display format string when it's 65 days or less to event

For sake of argument todays date is the 28/10/1992

%E is expanded to 'Tomorrow'
%a is expanded to 'Thu'
%b is expanded to 'Oct'
%d is expanded to '29'
%Y is expanded to '1992'
%l is expanded to '26'
%t is expanded to 'years'
%C is expanded to '1966'

The whole format string becomes:
Tomorrow, Thu Oct 29 1992 some person will be 26 years ( born 1966 )

example 2:

365 24 12 ???? \n\		       ; date of the event, note newline!
+---------------------------------+\n\ ; output a new line 
| On the %d/%m it's Christmas Eve |\n\ ; output format string
+---------------------------------+    ; remember presents !!!

Will produce the following:

+---------------------------------+
| On the 24/12 it's Christmas Eve |
+---------------------------------+

Note: CTRL G's can be included in the format string. When the format string
      is displayed the CTRL G's will sound the bell. On the PC one can use
      line drawing characters and the extended ASCII set as well. Even 
      ANSI escape characters can be used to provide different colours. 
 
Limitations: max length of line in event file: 512 bytes
             max length of expanded format string: 1024 bytes



Getting in touch....

If you have any comments, bug fixes or whatever, I can be
reached through email at tjaberg@online.no 

Author credits:

Almanak was conceived, created and written by Tormod Tjaberg using
the best PC compiler in the world: Zortech C++.
The Julian day number routines were written by Bob Twilling

Other credits:

Hans Peter Verne for the use of 'the other machines' and just
for being a nice guy..

Annette, for being what she is...
