                   ========================================
                     Package "Date::DateCalc" Version 3.1
                   ========================================
                       for Perl version 5.000 and higher


     Copyright (c) 1995, 1996, 1997 by Steffen Beyer. All rights reserved.
     This package is free software; you can redistribute it and/or modify
     it under the same terms as Perl itself.


Prerequisites:
--------------

Perl version 5.000 or higher, a C compiler capable of the ANSI C standard (!)
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Preliminary steps for use with Perl prior to version 5.002:
-----------------------------------------------------------

Edit the file "Makefile.PL" and change the line

    'VERSION_FROM'	=> 'DateCalc.pm',
to
    'VERSION'		=> '3.1',

Then edit the file "DateCalc.pm" and change the line

    bootstrap Date::DateCalc $VERSION;
to
    bootstrap Date::DateCalc;

Finally, edit the file "DateCalc.xs" and delete the line

    PROTOTYPES: DISABLE


How to install it:
------------------

Please unpack and build this package OUTSIDE the Perl source and distribution
tree!!

 1) Change directory to the directory that has been created by unpacking this
    package ("DateCalc-3.1/").

 2) Type "perl Makefile.PL" (or whatever the name and path of your Perl 5
    binary is).

    This will create a "Makefile" with the appropriate parameters for your
    system (for instance, where the install directories are, and so on).

 3) Type "make".

    This will create a dynamically linkable library file that will be linked
    to Perl later, at runtime, provided your system supports dynamic linking.

    Please refer to the MakeMaker documentation for instructions on how
    to build a new Perl with statically linked libraries (invoke "perldoc
    ExtUtils::MakeMaker" for this), if your system does NOT support dynamic
    linking!

    Should you encounter any compiler warnings or errors (like the redefi-
    nition of certain types already defined by your system), please contact
    me by mail at <sb@sdm.de>, sending me your compiler output (both STDOUT
    and STDERR). Thank you!

    ======================================================================
    Be aware that you need a C compiler which supports ANSI C in order to
    successfully compile this package!
    ======================================================================

    Also note that problems may arise with the c89 compiler of HP, although
    it allegedly supports ANSI C!

    I recommend the GNU gcc compiler, which is available for free on the
    Internet.

    (HP users are strongly recommended to install the GNU assembler GAS
    first before installing GNU gcc)

    Should you get the error messages

    DateCalc.c: 15: Unable to find include file 'EXTERN.h'.
    DateCalc.c: 16: Unable to find include file 'perl.h'.
    DateCalc.c: 17: Unable to find include file 'XSUB.h'.

    then edit the file "Makefile.PL" and change the line

    'INC'	=> '',     # e.g., '-I/opt/pkg/perl5.003/dist'

    in such a way that it points to your Perl 5 distribution tree, e.g.,

    'INC'	=> '-I/usr/ctr/dlt/private/perl/perl5.003',

    or the like, and start over with the generation of the "Makefile" at 2).

 4) Now issue "make test".

    The output should look somewhat like this:

    PERL_DL_NONLAZY=1 /usr/bin/perl -I./blib/arch -I./blib/lib
    -I/e/www/sw/pkg/perl/ lib/i386-freebsd/5.003 -I/e/www/sw/pkg/perl/lib
    -e 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;'
    t/*.t
    t/f000..............ok
    t/f001..............ok
    t/f002..............ok
    t/f003..............ok
    t/f004..............ok
    t/f005..............ok
    t/f006..............ok
    t/f007..............ok
    t/f008..............ok
    t/f009..............ok
    t/f010..............ok
    t/f011..............ok
    t/f012..............ok
    t/f013..............ok
    t/f014..............ok
    t/f015..............ok
    t/f016..............ok
    t/f017..............ok
    t/f018..............ok
    t/f019..............ok
    t/f020..............ok
    t/f021..............ok
    t/f022..............ok
    t/f023..............ok
    t/f024..............ok
    t/f025..............ok
    t/g000..............ok
    t/g001..............ok
    t/g002..............ok
    t/g003..............ok
    t/g004..............ok
    t/g005..............ok
    t/g006..............ok
    t/g007..............ok
    All tests successful.
    Files=34,  Tests=1178,  3 secs ( 5.70 cusr  1.27 csys =  6.97 cpu)

 5) At last, type "make install".

 6) Now you can try to run the "demo". Start it with "perl demo" (or what-
    ever the name and path of your Perl 5 binary is).

    It will ask you for your birthday and the current date and calculate your
    age in days. You may enter the dates in almost any format, provided that
    you enter them in the order day - month - year. You may also use an (up
    to 3 letters) abbreviation for the month. You might try "03-Jan-1964",
    for example. Experiment!

    "demo_us" is (in principle) the same program as "demo", but it expects
    dates in U.S. american format in the order month - day - year. Moreover,
    the decoding is done almost entirely in Perl, whereas "demo" uses the
    package's C function "decode_date".

    Finally, the program "demo2" lets you find out about, for instance,
    the second thursday of a given month and year.

    The program takes four numeric arguments: n for the n-th day (1..5),
    the day of week (1=Monday..7=Sunday), the month (1..12) and the year
    (1..*):

    > perl demo2 2 4 4 1996
    The 2nd Thursday in April 1996 is Thursday, 11 April 1996

    > perl demo2 4 1 4 1996
    The 4th Monday in April 1996 is Monday, 22 April 1996

    > perl demo2 5 1 4 1996
    The 5th Monday in April 1996 is Monday, 29 April 1996

    > perl demo2 5 3 4 1996
    The 5th Wednesday in April 1996 is <no date>

    > cal 4 1996
       April 1996
     S  M Tu  W Th  F  S
        1  2  3  4  5  6
     7  8  9 10 11 12 13
    14 15 16 17 18 19 20
    21 22 23 24 25 26 27
    28 29 30

    There is also a piece of C source code in this distribution ("cal.c_")
    which demonstrates how one can use the C library "lib_date.c" of this
    package stand-alone.

    To compile and link this file, use the following commands:
    (Assuming that you are using the GNU C compiler "gcc")

    % mv cal.c_ cal.c
    % gcc -ansi -o cal cal.c lib_date.c
    % mv cal.c cal.c_
    % chmod 555 cal

    (This will also need the two files "lib_date.h" and "lib_defs.h"!)

    (Note that "lib_date.o" instead of "lib_date.c" in the command line
    above invoking the compiler will also work provided that this package
    has already been built!)

    The resulting binary is an (albeit less versatile) analogue of the
    UNIX "cal" command. Call it as follows (example):

    ./cal 6 1997

    The output should look like this:

             June 1997
    Mon Tue Wed Thu Fri Sat Sun
                              1
      2   3   4   5   6   7   8
      9  10  11  12  13  14  15
     16  17  18  19  20  21  22
     23  24  25  26  27  28  29
     30

 7) Share and enjoy!


