LowCal is a relatively featureful web calendar designed for apache and
mod_perl - and nothing else.  No PHP, no database engines, nothing.


Module installation
-------------------

These instructions assume you have root access to the machine you're
installing on.  If you don't, you're not likely to be able to install new
apache modules.

I haven't done the full CPAN-style install automation yet, so you get to go
to one of the directories in your perl include path (I would recommend
/usr/local/lib/site_perl/) and untar the archive with `tar xvzf
LowCal-x.y.z.tgz` (substituting the LowCal version number for x.y.z, of
course).

Alternately, if you have already untarred the archive, pick a perl include
directory, create an Apache/LowCal subdirectory (for example,
/usr/local/lib/site_perl/Apache/LowCal if you go by my recommendation above)
and copy all of LowCal's *.pm files there.

It will also make things easier for you later if, after untarring LowCal you
`cd Apache/LowCal/utils` and `ln -s lowcal-update.pl
/usr/local/bin/lowcal-update.pl`.  We'll be using lowcal-update.pl later to
set up some recurring events and it'll be easier if you don't have to enter
its full path all the time.  (And easier still if, once you're up and
running, you set up a cron job to run it monthly.)

Now that the module is in place, you need to tell apache about it.  If this
is your first perl module, you should make sure that mod_perl is being loaded
with

LoadModule perl_module /path/to/mod_perl.so

unless mod_perl is statically linked to your build of apache.  You'll also
probably want to add

<IfModule mod_perl.c>
  PerlFreshRestart On        

  Include conf/perl.conf
</IfModule>             

You can omit the "Include conf/perl.conf" if you'd rather just put your perl
settings into the main htpd.conf, but I prefer to separate them out.  Easier
to find them that way.

Now that apache knows how to deal with perl, we finally get to point a URI at
LowCal.  Make yourself a perl.conf in apache's conf directory that says

<Location /lowcal>
  SetHandler perl-script
  PerlHandler Apache::LowCal::LowCal
  PerlSetVar EventPath /tmp
</Location>

Save it, restart apache with `apachectl graceful`, and point a browser at
http://localhost/lowcal.  If you see a blank calendar for the current month,
congratulations!  It works!

If you don't get a blank calendar, send mail to lowcal-users@sherohman.org
and we'll see what can be done to get you up and running.


Adding events
-------------

Event data files are essentially HTML body fragments with a couple special
META tags in them.  To create a dummy event for testing, go to the directory
that you set as the EventPath (/tmp in the example above) and create a file
named 20001231-nye containing the text:

---
<meta eventname="New Millennium Party!" category="Party">

<h2 align=center>The 20th Century Ends...</h2>

<p>We celebrated having lots of zeros last year, now to celebrate the new
millennium!
---

Save it and point your broswer at http://localhost/lowcal?month=12&year=2000.
You should see "New Millennium Party!" listed on December 31.  Click on it,
and you'll get the rest of the information you entered above.


Recurring events
----------------

Now create a file named /tmp/evt-work containing

---
<meta eventname="Go to work" category="Job">
<meta repeat="* * * 1-5">

<p>It's a weekday...  Go to work!
---

Save it and run `lowcal-update.pl /tmp 200012`.  Take a look in /tmp and you
should see a bunch of symlinks with names like 20001201-work -
lowcal-update.pl just created links for your recurring event back to the
event definition file based on that <meta repeat="..."> tag.

Point your browser back at http://localhost/lowcal?month=12&year=2000 and all
the weekdays should have "Go to work" listed.  But I bet you have Christmas
off, don't you?  Just delete 20001225-work, refresh the page in your browser,
and you'll be safe.


Additional information
----------------------

The first place to look is the Args, Templates, and Tokens files in the
LowCal directory.  They should at least be enough to get you started with
LowCal and perhaps even fix some minor problems.

If you have serious trouble, you can check for relevant bug reports at
http://sherohman.org/lowcal-bugs.  If there isn't anything useful there,
send mail to lowcal-users@sherohman.org.  I read the list and will do what
I can to help you out.

There isn't a FAQ yet, but I'll put one together as soon as I start getting
questions.

Good luck, and have fun!

