To use this package you will probably want to use a grabber to get
some listings, pipe them through some filter programs, and then use
one of the two chooser programs to select your viewing for the next
week.


* Grabbers

These are programs which fetch listings from somewhere 'out there' and
output them in XMLTV format.  Currently grabbers are included for the
following countries:

	UK and Ireland			tv_grab_uk_rt, tv_grab_uk_bleb
	Canada and United States        tv_grab_na_dd, tv_grab_na
	Germany				tv_grab_de_tvtoday
	Finland				tv_grab_fi
	Italy				tv_grab_it
	Spain				tv_grab_es, tv_grab_es_laguiatv
	Netherlands			tv_grab_nl, tv_grab_nl_wolf
        Denmark                         tv_grab_dk
        Hungary and Romania             tv_grab_huro
        Japan                           tv_grab_jp
        Sweden				tv_grab_se_swedb        
        France                          tv_grab_fr
        Norway                          tv_grab_no
        Portugal                        tv_grab_pt
	Belgium and Luxemburg		tv_grab_be
	Brazil				tv_grab_br
	Switzerland			tv_grab_ch_bluewin
	Estonia				tv_grab_ee
	Israel				tv_grab_il
	Iceland				tv_grab_is
	Reunion Island			tv_grab_re
	Argentina			tv_grab_ar


Contributions from other countries are welcome, of course.

Many of these grabbers have a configuration stage; once you've decided
what grabber to use, first run it with --configure, for example
'tv_grab_fi --configure'.  If the grabber does not need configuration
it will tell you so, otherwise you will be able to choose what
channels to download listings for (fewer is faster).

The grabbers print listings to standard output but you will want to
redirect output to a file, for example 'tv_grab_fi >fi.xml'.  The
default is to grab listings for the longest time period possible (one
or two weeks) but to speed up downloading you may want to specify
'--days 1' for one day only.


* Filters

There are some Unix-style filter programs which perform processing on
XMLTV listings files.  In particular the grabber output is not
guaranteed to be in any particular order and you probably want to sort
it.

Each filter is normally run with both input and output redirected, for
example 'tv_sort <fi.xml >fi_sorted.xml'.

Please see the programs' manual pages for more detailed instructions;
also each supports the --help convention to print a usage message.

* * tv_sort: sort listings into date order

Programmes are sorted based on their start time and date, and if those
are the same then their end time.  tv_sort also adds in the 'stop
time' field of a programme, if it is missing, by looking at when the
next thing starts on the same channel.  It also performs some sanity
checks such as checking that two programmes on the same channel do
not overlap.


* * tv_grep: filter listings by regexp matching

This is a tool to extract all programmes or channels that match a
given regular expression.  You can use tv_grep as a quick and dirty
way to filter for your favourite shows, but it is easier to use
tv_pick_cgi or tv_check for that.

The simple usage is with a single regular expression, for example
'tv_grep Countdown'.  It is also possible to match individual fields
of a programme, for example
'tv_grep --ignore-case --category drama'.  How effective this is
depends on how well the listings data is organized into different
fields.

There are also some tests which don't quite count as 'grepping':
--on-after TIME will remove all programmes which would already have
finished at time TIME.  So 'tv_grep --on-after now' will filter out
shows you have already missed.  You can combine tests with --or and
--and.


* * tv_split: split listings into separate files

If you want separate XML files for different time periods or channels,
pipe the listings into tv_split with a suitable template for the
output filename.  For example 'tv_split --output %channel-%Y%m%d.xml'
will generate one output file for each channel/date combination.


* * tv_extractinfo_en: extract info from English-language programmes

Often the listings source being grabbed won't be as machine-readable
as it could be.  For example instead of storing the director of a film
in a separate field, it may simply write 'Directed by William Wyler'.
Or separate programmes on at different times may be combined into a
single entry.  tv_extractinfo_en attempts to sort out this mess using
heuristics and regular expressions that match English-language
descriptions.

It was written for the UK listings, and some of the things corrected
(such as multipart programmes) are specific to that source.  But it
should work for any anglophone listings source.  The North American
programme descriptions are too terse to extract much information, but
tv_extractinfo_en occasionally manages to get the name of a
presenter.

Lots of details that could be handled are not, because any heuristic
for this kind of thing must occasionally get the wrong answer.  It's
more important to minimize the number of false positives.  You should
run a week's listings through tv_extractinfo_en and diff the results
against the original to decide whether you trust the program enough to
use it.


* * tv_imdb: enrich listings with data from the Internet Movie Database

tv_imdb is a filter program which tries to look up programmes in the
publicly available imdb data and add information to them before
writing them out again.  At present it requires you to download some
(rather large) data files from the imdb ftp site.  See the manual page
for more details.


* * tv_to_latex: convert listings to LaTeX source

To print out listings in a concise format run them through tv_to_latex
and then LaTeX, for example:

% tv_to_latex <listings_sorted.xml >tv.tex
% latex tv.tex
% dvips tv.dvi

and then print tv.ps if it hasn't printed already.  You may want to do
this on the full sorted listings for a complete TV guide (which will
run to many pages), or on the output from tv_pick_cgi or tv_grep for a
personal TV guide.

Tools exist to convert XMLTV data to HTML or to PDFs, but they are not
included in this release.


* * tv_to_text: convert TV listings to plain text

This filter generates a plain text summary of listings.  The
information included in the summary is the same as with tv_to_latex.


* * tv_imdb: augment TV listings with imdb.com data

This filter builds and uses a title indexed database of imdb plain
text files (see http://www.imdb.com/interfaces) and inserts actors/
actresses/directors/categories based on what imdb.com knows about
the movies in the tv listings.

* Choosers

The real point of getting a TV guide in machine-readable form is to
let the computer do the work of looking through it finding things for
you to watch.  Two programs are distributed to do this.  tv_check is a
GUI-based program where you select some shows and then generate a
printed report which flags any deviations from the normal weekly
schedule.  tv_pick_cgi is a Web-based program which takes a different
approach: it shows you all the programmes that are on and asks what to
do with each one, then generates a personal TV guide with the shows
chosen.  However preferences are remembered for the next run, so next
time you'll only be asked about new programmes.

See README.tv_check for instructions on using tv_check.

To use tv_pick_cgi, you will need an environment for running CGI
scripts.  If you're lucky enough to have a web server handy, copy the
file as tv_pick.cgi to a directory somewhere, copy XMLTV.pm and the
XMLTV/ directory (which contains more Perl modules) to the same place,
and copy a listings file there as tv.xml.  It is best for the listings
to be sorted.

If you have no web server, you can still run tv_pick_cgi using the
'CGI emulation' mode of the Lynx text-based web browser.  Run 'lynx
lynxcgi:tv_pick_cgi'.  This assumes your Lynx has the CGI emulation
compiled in - if not, suggest it to your vendor.  Quick guide to Lynx:
move between radio buttons using up-arrow and down-arrow.  Press
right-arrow to select a radio button, to press an on-screen button
like 'Submit' move the highlight to it and press Enter.

You should now be presented with a list of all programmes you haven't
seen before (on the first run, this will be everything).  For each
programme there are four choices:

  never  - no, I don't want to watch it, and don't ask me about
	   programmes with this title ever again.

  no     - I won't watch it this time, but ask me again next time.

  yes    - I might watch it (put it in the output listings), but ask me
           again next time.

  always - whenever a programme with this title	appears, always put it
           in the output without asking.

The default option for unrecognized titles is 'never', reflecting the
fact that most things on TV are rubbish.  Because something marked as
'never' is effectively censored from all future sessions with
tv_pick_cgi, you should be sure to change this for any programme you
might want to watch in the future.  Saying 'no' is a safe choice for
things you don't want to watch.

when you've chosen your preferences for everything on the page, press
'Submit' and a page will appear confirming your preferences and
listing which of the programmes will appear in the output ('planning
to watch').  There will probably be several pages of listings, so go
to 'Next page' and repeat as necessary.  Take comfort in the thought
that you'll never have to deal with most of these shows ever
again :-).

At the end a personal listings file towatch.xml is generated, which
you can download with your browser if you want, and your preferences
are stored for next time in the file tvprefs.  It is worth checking
this file after your first use of pick_cgi in case you accidentally
marked something as 'never'.


* Using the tools together

It's probably easiest, once you get used to the tools, to run them
together in a pipeline.  For example,

% tv_grab_fi | tv_sort | tv_extractinfo_en \
  | tv_sort | tv_grep --on-after now >guide.xml

This gets listings, sorts them, munges them through
tv_extractinfo_en to see what it finds (in this case it will probably
break up 'Open University' into subprogrammes, among other things),
sorts again and filters out those programmes already missed.  The
first sorting is needed to add stop times to programmes to give
tv_extractinfo_en the most information to work on; the second sorting
because tv_extractinfo_en does not necessarily produce fully sorted
output.  Most of the XMLTV tools do not strictly require that the
input be sorted, but they tend to work a bit better if it is.

Then run 'tv_check --scan' or use tv_pick_cgi to generate a text
report or a personal TV listing.