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>

If you want to use the web-based administration pages, you will also need to
add

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

  Order Deny,Allow
  Deny From All
  Allow From localhost
</Location>

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

Note that LowCal does not currently handle its own security for the admin
interface.  If you wish to secure the admin pages (which would be a wise
thing to do), you will need to use apache's standard access control
mechanisms to do so.  In the example above, the admin pages are accessible
only to requests originating from the server itself, which may or may not be
appropriate to your situation.

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 manually
----------------------

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.


Creating recurring events manually
----------------------------------

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.


Web-based administration
------------------------

The web-based admin interface is currently pretty crude.  If you want to try
it out, set up the <Location> block as described above and copy the included
admin_options file to your event directory.  The event directory will also
need to be writable by the user and/or group that apache runs as.  (This is a
potential security risk, as an attacker who manages to compromise apache,
LowCal, or any other module may be able to deposit malicious code or data in
your event directory.  You have been warned.)

You'll still have to set up the meta tags manually, but at least you won't
need to worry about creating your files in the right place with the right
names.  Hopefully, the admin pages will be readily comprehensible, but I have
no delusions of greatness for them.  If you have any suggestions for
improving them, please send them to the LowCal mailing list
(lowcal-users@sherohman.org) or to me directly (dave@sherohman.org).

There is one thing on the admin pages which I know requires explanation:  In
the daily lists of events, the "U/L" column indicates whether an event is
[U]nique (a normal file) or a [L]ink to another file.


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!