$Id: README.tv_check,v 1.12 2004/03/22 22:04:25 epaepa Exp $

This file describes the tv_check module of XMLTV.

TV-CHECK is a Perl script that reads in a file with show information and
checks it against a TV guide listing, alerting you to unexpected episodes
or schedule changes.

New for this release is a --myreplaytv option.  For those lucky enough
to enjoy that PVR, the shows.xml file can be automatically populated
with data from the myreplaytv.com website.

Questions/Comments/Suggestions/Thanks are, of course welcome.
	XMLTV - users        xmltv-users@lists.sourceforge.net. 
	XMLTV - developers   xmltv-devel@lists.sourceforge.net
	tv_check author	     reden@cpan.org

Documentation is available in "tv_check_doc.html"


Quick-start guide ( run tv-check w/o parameters for options )
-------------------------------------------------------------

The default show  file name is shows.xml
The default guide file name is guide.xml

Windows EXE users should add "xmltv.exe" to the beginning of each tv_ command

1. set timezone if not set ( this should not be necessary if using the EXE version)
            set TZ=CST6CDT
            
2. download listings using any XMLTV grabber, for example using
   tv_grab_fi for Finnish listings:
            tv_grab_fi --configure
            tv_grab_fi --output guide.xml


3. (non-ReplayTV users) use tv_check to create a "show file"
            tv_check --configure

   Pick some shows to track, Click Add to add to the list.
   exit tv_check

3a. (ReplayTV users) use tv_check to scan the guide (and grab myreplaytv.com)
            tv_check --myreplaytv=1,username,password --scan --html --out=a.html
            
	The "1" is a Replay unit number in case you have >1 replay.

	You can also run --configure mode to set paramters or edit the show file.


3b. (non-ReplayTV users) use tv_check to scan the guide
	tv_check --scan --html --out=a.html


Sample shows.xml file
=======================
<tv-check>
  <lang>en_US</lang>
  <shows device="VCR1"   day="Sun" channel="10402" hhmm="2000" len="60" title="The X-Files"  />
  <shows device="Replay" day="Mon" channel="10402" hhmm="1900" len="30" title="That '70s Show" dayonly="1" />
</tv-check>

Parameters
====================
 lang   : preferred language.  Optional, can have multiple, in order of preferences
 shows  : list of shows you're interested in

Show attributes:
====================
 day    : day of the week and Sun,Mon,Tue,Wed,Thu,Fri,Sat
 channel: channelID used by the guide
 title  : *EXACT* title of show.
 hhmm   : start time of show (hhmm)
 len    : expected length of show in minutes ( this may become optional )
 device : device that records the show.  Reports recording conflicts.
        : If the device contains "replay" takes into account ReplayTV's fuzzy recording logic
 
Optional attributes:
====================
 chanonly: if 1, episode scan ignores shows on other channels
 dayonly : if 1, episode scan ignores shows on other days
 timeonly: if 1, episode scan ignores shows at other times
 neartime: if 1, episode scan only reports shows within a 3 hour window


Notes: 
----------------------
"No Guide Info" means no guide information was found for that channel at that time.
		something may be wrong with the channel ID,listing fetch, or the 
		guide file is just old.

A "--html" option is available that outputs HTML output with color flagging. 

After processing shows, a check is made for recording conflicts.  Only shows with the same "device"
are checked for conflicts.  VCR's probably would never give a conflict, but ReplayTV tries
to find your show if it moves.  If the device contains the string "REPLAY" (case insensitive)
during the title scan, a recording is expected if the show within 1 timeslot of the requested
time.  This mimic's ReplayTV's recording logic and detects conflicts due to a show moving.

The --myreplay import by default includes only guaranteed show channels.  The non-guaranteed
option can be used to have it include both types.  Theme and Zone channels are not currently
supported.

Episodes before today and more than a week old are excluded from the title scan.

Known bugs:
---------------------
If you select a title in the title selection list and then try and select a blank day 
or channel the field doesn't blank.  I have no clue.  The variable doesn't match the
displayed value... looks like a TK bug to me.

Sometimes the GUI doesn't take focus at startup.  Not sure why, and what can be done.
if it shows up minimized, just click to bring it up.

When using the "compiled" Windows EXE code on windows 98, the command window minimizes.
No idea why.  Seems to work fine on Win2k.


