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 without help (and permission) from a system administrator.

First, you need to actually install the code to the appropriate directories.
Running install.pl in the directory where you unpacked the tarball will do
this.  By default, the LowCal module itself will install under
/usr/local/lib/site_perl and command-line utilities will be installed in
/usr/local/bin.  If these locations are not appropriate for your system, edit
the values of $module_dir and/or $util_dir near the top of the script before
running it.

Next, you need to tell apache to load the LowCal module.  If this is your
first perl module, you should edit apache's httpd.conf and 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 httpd.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>

(Add this Location block to httpd.conf if you chose to omit the Include line
above.)

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
directory where you unpacked LowCal.  They should at least be enough to get
you started with LowCal and perhaps even fix some minor problems.

If you have trouble beyond what they can help you with, 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!

