First off, a note on AUPs and Licenses.

This software is licensed under the same terms as Perl itself.

However, the data that xmltv provides may have limitations on how you are
permitted to redistribute it.  In particular, the Zap2IT source for North
America rather clearly forbids this.  Please do not use this software to
violate those license agreements, as it may cause them to cease offering
their data to xmltv users for free, and this would be bad for all of us.

How to install:

You will need the following:
* PostgreSQL - a version with schema support is needed
* Perl - 5.8 is strongly recommended because of unicode support
* mod_perl
* xmltv data

And the following perl modules:
* DBI
* DBD::Pg
* Date::Parse
* Time::HiRes
* Image::Info

=========================== Creating the Database ===========================

First off, you'll want to create your database.  The schema.sql file contains
the basics you'll need.  The mkschema.sh will replace the placeholder schema
name within schema.sql with the value you pass it as an argument, and spit
the result out to stdout.  So, you might do something like:

./mkschema.sh xmltv | psql database xmltvuser

And assuming the xmltvuser has create schema privileges (important!) it
should create everything.  If you want separate users for schema ownership
versus reading/writing data, you'll have to setup the grants yourself.  The
pgadmin3 tool makes doing such mass grants easy.

============================= Loading the Data ==============================

Next, you'll want to load your data.  To do this, run the xmltv-pg-load
program with the source xmltv file as an argument.  I.e.:

./bin/xmltv-pg-load ~/.xmltv/na.xml

Be patient.  If it's a large file it may take a few minutes to load.  This
is something you'll probably want to schedule via cron to run after you
download the new listings.

============================ Configuring the Web ============================

Finally, you'll need to setup the mod_perl pages.  Assuming your Apache
server is already setup to use mod_perl, you'll just need to do a few
things.  First you'll need to put the TVListings modules somewhere where
mod_perl will find them.  On my system, /etc/apache/lib/perl (might be
/etc/httpd/lib/perl for you) is in the default search path, so you can copy
lib/TVListings there.  Otherwise you'll need to play with mod_perl
directives to adjust perl's @INC search path.

Next, you'll need to check the Config.pm for any changes you might need to
make.  The key items to check for are the DBI connection parameters and the
location of the CSS files.  The tv listings will not come out very nice if
the CSS cannot be pulled in.

When you put the CSS files in place, you will probably want to edit
tvcolors.css and tvprefs.css.  The first defines all the colors for the tv
listings, and the latter is a place for you to mark channels you don't want
to see, or want to have styled differently.

Once all this is done, you need to tell Apache about a location at which the
tv listings should appear.  Something like the following should work nicely:

<Location /tv>
	SetHandler perl-script
	PerlModule Apache::DBI
	PerlHandler TVListings::modperl
	Order deny,allow
	Deny from all
	Allow from 127.
</Location>

Other Apache options for authentication, adding local domains, etc. are left
as an exercise for the reader.  If you want to separate read and write
access to the system over the web, you can add a second Location directive
to further restrict access, like so:

<Location /tv/edit>
	AuthName restricted
	AuthType basic
	AuthUserFile /etc/apache/users
	AuthGroupFile /etc/apache/groups
	Require group tvedit
</Location>

Finally, if you want to save some memory and speed, you can add TVListings
to your mod_perl startup.pl (if you have one), by adding somsething like:

use Apache ();
use Apache::DBI ();
use TVListings::modperl ();

If you want info on how to setup such a script, look at the documentation
for the PerlRequire directive in the mod_perl documentation.

After doing all this, you'll need to restart/reload Apache.

============================ Using the Listings ============================

Now that all that is setup, you want to view the tv listings!  Assuming all
went well, you should be able to point your web browser at
http://localhost/tv/ and get your tv grid!  If you have Mozilla or Firefox,
you can add a sidebar for http://localhost/tv/now which will provide an
alternate tv grid specifically designed for the sidebar.

The "flag this as interesting" bit on the show details form allows you to
emphasize or de-emphasize shows you like or dislike.  Populating the
database with this information is probably the biggest customization you
will be applying.  The "Good Stuff" link will make use of this information
to show you a page with all the shows you like that are on now or on soon.

Hopefully most of the functions of the system should become self evident
after clicking a few links.  An approximate list of features to check for:

* Basic TV Grid
* Sidebar listings for what's on now
* Searching shows
* Show / Movie info on IMDB
* Listing interesting shows on now or soon
* Basic channel information and what's coming up on it

========================= If You're Really Curious =========================

There's some example code for a wxPerl application to show the current
listings in there.  If you're curious about such things, you might want to
take a look.
