### dates-0.7 README file

    ****************************

    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.