****************************
NB:
This quick doc was written for DATES v0.3 and must be read keeping in
mind that. The program options grew in number without changing of names
since then and the file formats described here are still valid.
Issuing "dates -h" you'll have a list of the currently supported
options. I hope it is enough self explainatory after you have read the
QUICK PROGRAM USAGE OVERVIEW part of this file.
The INSTALLATION part is good too.
****************************
COMPATIBILITY:
--------------
This program was developed using:
Linux 1.2.13 (Slackware release)
gcc 2.7.0
NCurses 1.9.7a (with forms compiled in) (optional)
and was tested also with DOS & Turbo C++ 3.0 (without NCurses).
It works also with
Linux 2.0.6 (Debian 1.1 release)
NCurses 1.9.9 (with forms compiled in) (optional)
without problems.
I can't say anything about other systems/compilers or older releases
of the above; anyway there shouldn't be much trouble since
excluding the NCurses edit interface the program uses for the 95% only ANSI C
library functions. The other 5% are only libc/unix functions.
I strongly advise you to use the NCurses edit interface since it's very
comfortable and you don't have to remember the Dates' file format.
If you find troubles compiling for your
configuration and want to make a (quick?) port/fix please mail us before
starting (our addresses are somewhere in this file ... fidonet only, sorry)
so you'll be sure to work on the latest release and to stop us from working
on it until you're not finished (kind of human rcs :-)).
COPYRIGHT:
----------
Copyright (C) 1997 Marco Rivellino & Fabio Menegoni
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., 675 Mass Ave, Cambridge, MA 02139, USA.
INSTALLATION:
-------------
*** Linux ***
If you have NCurses installed just issue the command:
make
then you'll have the 'dates' binary which includes the edit interface.
NB: in order to use the NCurses edit interface you have to install NCurses
with the "forms" facility compiled in! (see the NCurses docs for
details) otherwise you'll get gcc complaining you miss the "forms.h"
header file (and related code) and then aborting compilation.
If you don't have NCurses or for some reason don't want the edit
interface just issue:
make noedit
then you'll have the 'dates' binary without the edit interface.
If you want to install it to /usr/local/bin then issue (with root
privilege usually...):
make install
To clean up the directory from object files and backups issue:
make clean
*** DOS ***
Just issue the command:
make -fMAKEFILE.DOS
then you'll have the DATES.EXE executable.
QUICK PROGRAM USAGE OVERVIEW:
-----------------------------
This program reminds you of recurrences/dates that are coming in the next
days or that are past since a few days. If you issue the command
dates -h
you will have a brief help text.
You can specify how many days to look forward and backward with the "-d"
option. So
dates -d15
will look for important dates (in the default data file) that are coming in
the next 15 days or that are past since no more than 15 days. The default
value is 7.
If you issue:
dates -d90 mylist.dat
the program will look for dates to remind you in the file "mylist.dat". The
distance to look through is 90 days so you'll be reminded of dates that are
coming in the next 90 days or that are past since no more than 90 days.
Dates to be reminded of must be stored in a data file.
Linux default data file is "~/.dates.lst".
DOS default data file is "dates.lst" searched through all DOS path.
If you are running DATES under Linux (with ncurses library) issuing the
command
dates -e
you can edit the (default) data file. Use the command
dates -e /usr/pop/duck
to edit the "/usr/pop/duck" data file.
Instead if you're a brave wild 'vi guy' or just an unlucky DOS user
you'll have to use a text editor and stick to the following format
(the file is ASCII and line order is significant
...names included between square brackets denote an optional parameter):
[comment]
day[/month[/year]]
date_type
look_distance
date_comment
where:
comment = one or more lines of text beginning with one of the
characters: # ; *
or one or more empty lines. These are just comments to the
file itself for the humans and will be ignored by the program.
day = date's day number (1-31)
month = date's month number (1-12) (optional)
year = date's year number a.C. (1-32767) (optional)
(NB: 1990 = 1990 a.C. and 88 = 88 a.C. !)
date_type = one of the strings: "DATE", "RECU"
where DATE states that the date is a future one
(e.g. appointments)
and RECU states that the date is a past one
(i.e. a recurrence: birthday, anniversary...).
look_distance = the program will start reminding you of this date
"look_distance" days before the date occurs and stop
doing so "look_distance" days after the date has passed
(just in case you don't run this program daily).
date_comment = string that you want to be printed to
remind you of that date.
The month and year numbers are optional.
If you have a date entry with just the day number as in:
20
DATE
3
remember to pay taxes
the program will start reminding you about the 20th of every month from 3
days before the 20th to 3 days after it (from the 17th to the 23rd included
of every month). E.g. if today is the 18th of July and you run
dates
you will get the message:
in 2 days time it is 20 Jul: remember to pay taxes
Instead if today is the 22nd of July you'll see:
2 days ago it was 20 Jul: remember to pay taxes
If you have a date entry with just the day and month numbers
as in:
14/2
RECU
7
St Valentine's day, remember your valentine!
the program will remind you about every 14th of February (from the 7th to the
21st of February) with the message
"St Valentine's day, remember your valentine!" together with the number of
days it misses to that date or since that date has passed.
If you have stated a full date (day+month+year numbers) as in:
16/12/1770
RECU
12
Schroeder reminds: "it's Beethoven's birthday" :-)
the program will remind you about every 16th of December (starting on the
4th of December and ending on the 28th) with the chosen message
and will tell you how many years are gone since that date's year
(so if it's a birthday like the one in the example you'll know how many
years that person will be on that day). For example if today is the 15th of
December 1996, running dates you'll see the message:
tomorrow it recurs 16 Dec 1770: Schroeder reminds: "it's Beethoven's birthday" :-) (226 years)
NB: Of course if the message is longer than your current terminal width it
will be split in more than one line (this file is written in an 80 cols
term so that anyone can read it..).
You can have a look at the "dates.lst" file included to have a complete view
of all the (six) possibilities.
Issuing the command:
dates dates.lst
here's what the program reports today (29th of July 1996):
in 2 days time it is 31 Jul: monthly appointment
in 2 days time it is 31 Jul: annual appointment
in 2 days time it is 31 Jul 1996: fixed-date appointment
in 2 days time it recurs 31 Jul: monthly recurrence
in 2 days time it recurs 31 Jul: annual recurrence
in 2 days time it recurs 31 Jul 1996: fixed-date recurrence (0 years)
For a good result on very busy/absent minded people (like me: Marco) I
suggest a drastic measure (which happen to be my own measure :-| ): run dates
in your shell init file (or AUTOEXEC.BAT if you're a DOSsian :-) ) so you
won't forget anything important. The drawback is that you'll hate the
program after the first two days of use (please don't blame me, I told you
it was a drastic one :-)). If instead you're not so busy/absent minded you
can run dates from a system startup file (like /etc/rc.local if you're using
Linux). I wouldn't advise to run dates manually, since I know (from my own
experience) you'll forget it sooner or later... :-)
NOTE: the date format is day/month/year. So 1/4/1990 means the 1st of April
1990 a.C. I'm sorry with people using a different date standard. If
there will be lots of feedback about this I'll consider
implementing the more requested date formats.
NOTE2: here's an anectode about the Gregorian Calendar quoted from the cal
(Linux command) manpage for those of you interested:
The Gregorian Reformation is assumed to have occurred in 1752 on the 3rd
of September. By this time, most countries had recognized the reforma-
tion (although a few did not recognize it until the early 1900's.) Ten
days following that date were eliminated by the reformation, so the cal-
endar for that month is a bit unusual.
CREDITS:
--------
This silly program was made by Marco Rivellino (2:335/317.15@fidonet.org) and
Fabio Menegoni (2:335/317.4@fidonet.org). If you want to e-mail us please
consider the idea that probably you won't get a light speed answer :-)
(this is dued also to the Fidonet Speed which is known to be approximately
1-E30 times that of light ;-) ). Anyway every message will get an answer in
a finite amount of time :-).
Thanks to the authors of the BSD 'cal' command that I (Marco) used as a source
of informations (but not of code since it's copyrighted) about the
Reformation.
KNOWN BUGS:
-----------
The program handles correctly only dates >= 14 Sept 1752 (after the Gregorian
Reformation). This is due to the "hole" of 11 days from the 3rd of September
to the 13th of September 1752 (included). I apologise if you have
recurrencies of dates before that period but I discovered this only when the
program was finished and I accidentally found the 'cal' utility.
If someone will (gently :-) ) ask i'll try to find some time to fix that.
Another bug is caused by the NCurses' forms input routine. In some cases it
shows a weird character instead of what it should print. For example try
entering the editor and keep pressed the right cursor key ... This doesn't
show up if you enter some valid input first and then try to give it an
invalid one...
NB: this bug is fixed in NCurses 1.9.9 so you'd better upgrade if you have
an old version.
