XMLTV 0.5.70

Gather television listings, process them and organize your viewing.
XMLTV is a file format for storing TV listings, defined in xmltv.dtd.
Then there are several tools to produce and process these listings.

Please see doc/QuickStart for documentation on what each program does,
and xmltv.dtd for documentation on the file format.

* Major Changes in this release (0.5.70)

tv_grab_eu_egon - removed broken grabber
tv_grab_fi_sv   - re-enable Swidish language linstings of Finnish TV channels
tv_grab_sd_json - renamed to tv_grab_zz_sdjson (not country specific)

And lots of other changes (see ChangeLog for details)

* Installation

Note: Windows users are strongly advised to use the pre-built EXE as installing
all the prerequisites is non-trivial. For those who want to give it a go,
instructions are in doc/exe_build.html. Those instructions can be used for both
building xmltv.exe as well as a local install.

Basic installation instructions (Linux/Unix):

% perl Makefile.PL
% make
% make test
% make install

To install in a custom directory, replace the first line with
something like

% perl Makefile.PL PREFIX=/wherever/

The system requirements are Perl 5.6 or later, and a few Perl modules.
You will be asked about some optional components; if you choose not to
install them then there are fewer dependencies.  The full list of
required modules is:

LWP 5.65
XML::Parser 2.34
XML::Twig 3.10
XML::Writer 0.4.6
Date::Manip 5.42a
Memoize (included with Perl 5.8 and later)
Storable (included with Perl 5.8 and later)

Archive::Zip             (if you want to run tv_grab_uk_bleb)
CGI                      (if you want to run tv_pick_cgi)
Compress::Zlib           (if you want to run tv_grab_se_swedb)
Data::Dumper             (if you want to run tv_grab_dk_dr)
DateTime                 (if you want to run tv_grab_dk_dr)
HTML::Parser 3.34        (for grabbers which use HTML::Entities)
HTML::TableExtract       (if you want to run tv_grab_na_icons)
HTML::TreeBuilder        (for many of the grabbers)
HTTP::Cache::Transparent (for several of the grabbers)
HTTP::Cookies            (if you want to run tv_grab_br_net)
IO::File                 (if you want to run tv_grab_fr)
IO::Scalar               (if you want to run tv_grab_uk_bleb, tv_grab_in)
IO::Stringy              (if you want to run tv_grab_se_swedb)
JSON                     (if you want to run tv_grab_fi)
Parse::RecDescent        (if you want to run tv_grab_dk_dr)
SOAP::Lite               (if you want to run tv_grab_na_dd)
Term::ReadKey            (if you want to run tv_grab_na_dd)
Text::Kakasi             (if you want to run tv_grab_jp)
Tk                       (if you want to run tv_check)
Tk::TableMatrix          (if you want to run tv_check)
WWW::Mechanize           (if you want to run tv_grab_na_icons, tv_grab_br_net)
XML::LibXML              (if you want to run tv_grab_se_swedb, tv_grab_in)
Unicode::UTF8simple      (if you want to run tv_grab_pt)

You may have difficulty with the XML modules on Perl 5.8.0 - if so
send mail to the xmltv-users list.  Other Perl versions should be OK.

The following modules are recommended, but the software still works
without them:

Term::ProgressBar                (displays pretty progress meters)
PerlIO::gzip (for perl 5.8+)     (makes tv_imdb a bit faster)
Lingua::Preferred 0.2.4          (helps with multilingual listings)
Unicode::String                  (non-ASCII chars in LaTeX output)
Lingua::EN::Numbers::Ordinate    (not really needed, to be honest)

And the Log::TraceMessages module is useful for debugging, but not
needed for normal use.

All of these can be installed with tarballs downloaded from CPAN or
(hopefully) using the CPAN shell program: 'perl -MCPAN -e shell', then
'install XML::Twig' and so on.  But you may find it easier to search
for packaged versions from your OS vendor or others - places which
distribute a packaged version of XMLTV will often provide the modules
it needs too.

* Proxy servers

Proxy server support is provide by the LWP modules.
You can define a proxy server via the HTTP_PROXY enviornment variable.
    http_proxy=http://somehost.somedomain:port

For more information, see the the following:
http://search.cpan.org/~gaas/libwww-perl-5.803/lib/LWP/UserAgent.pm#$ua->env_proxy

* Known issues

tv_grab_se_swedb sometimes fails to work on Windows if there are spaces
in the path to your home-directory. This can be avoided by setting
the environment variable HOME to a path without spaces (e.g. c:\home).

* Author and copying

This is free software distributed under the GPL, see COPYING.  But if
you would like to use the code under some other conditions, please do
ask.  There are many who have contributed code, they are credited in
individual source files.

There is a web page at http://www.xmltv.org  and a Sourceforge
project 'XMLTV'.  There are some mailing lists:

    xmltv-announce@lists.sourceforge.net
    xmltv-users@lists.sourceforge.net
    xmltv-devel@lists.sourceforge.net

You ought to subscribe to the announce list at least.  Contact the
users list with most problems.

-- Robert Eden, rmeden@yahoo.com, 2017-11-27
$Id: README,v 1.182 2017/11/28 05:28:04 rmeden Exp $

HOWTO: install XMLTV under Cygwin on Windows
-------------------------------------------

Introduction
------------

XMLTV works mostly fine under the Cygwin unix environment for Windows...

This allows you to use the normal Perl Source code XMLTV installation
without the need for the Windows executable version, giving the
following advantages:
    * faster download of new XMLTV versions (source dist is 1/10th the
      size of the Win32 version)
    * ability to develop, debug and test new grabbers
    * ability to quickly patch bugs in grabbers without waiting for
      the new Win32 EXE version..
    * ability to use grabbers that are not yet part of the Win32 EXE

The disadvantages are:

    - Cygwin gives a unix command line environment that is alien to
      most windows users,
    - the initial download is very large -- Cygwin itself with the
      required packages is about 40Mb and the XMLTV prereq file is
      another 4Mb.
    - Cygwin uses a large amount of disk space.

Also cygwin itself has a few odd features that can cause some issues
with XMLTV, and TK based XMLTV GUI apps do not work in cygwin (tv_check)

WARNING: I have not tested every XMLTV app and grabber under Cygwin...

WARNING: Unix command lines can be very powerful and provide very
little hand-holding (such as 'Are you sure' messages when you want to
delete things). For this reason it is relatively easy to delete files
unintentionally and to render your system non-operational..
Take care with command lines and make regular backups!


Scope
-----

This HOWTO only deals with how to get XMLTV running on Cygwin. It does
not deal in any way with how to use Cygwin itself other than
installing the required packages fro XMLTV, so knowledge of how to
work using the unix-style command line shell will be required.

Advanced usage, such as applying patch files and working with CVS
checkouts is not covered by this HOWTO.


Instructions
------------

1) Install Cygwin:
------------------

Download and run Cygwin's installer.
    http://www.cygwin.com/setup.exe

In the installer, select:
    Install from Internet
    -> Next
    Select a suitable installation directory, All Users, Unix file type
    -> Next
    Select Local Package directory = some temporary folder...
        there will be a folder created - named after the download server -
        which you can delete after installation.
    -> Next
    Select the correct HTTP/FTP proxy settings
    -> Next
    Select a nearby mirror server
    -> Next

The package list will now be downloaded and shown in a categorised
tree view.
-- Click on the (+) text button to expand / contract a branch
-- Click on the '() Skip' text-button on a package line to select a
   version to download. It will change from 'Skip' to the version
   number. If the package is already installed, the additional options
   'Keep', 'Reinstall', 'Uninstall' will also be shown

Apart from the default packages that are pre-selected by the
installer, you need to ensure that the following packages are selected
    Base/
        diffutils
	tar
    Devel/
	expat
	gcc
	make
    Interpreters/
	perl
    Libs/
	libiconv
	libiconv2
	libxml2  ** select version 2.5.11 or 2.6.7 or later ** see below
    Utils/
	bzip2
	patch
	patchutils
	rebase
    Web/
	wget

Other useful packages to install are editors:
    Editor/
	vim (vi clone)
	nano (pico clone)

If you want to have access to the pre-release, under-development
versions of XMLTV then the CVS package is also useful
    Devel/
	cvs

** Note Re libxml2:
The Perl XML::LibXML package is known not to work with certain versions
of libxml2.  This package is required for some of the grabbers (tv_grab_se)
At time of writing, libxml2 version 2.5.11 is known to be OK, as is 2.6.7.
At time of writing, Cygwin's default version is 2.6.4, which is known
not to work For more information on working versions see README in
xml_prereq_x/XML-LibXML-xxx.  For this reason you must make sure that
the correct version is selected here by clicking several times on the
() 'Skip'/'Version' button...


After a lot of downloading, (about 40Mb) and some installing you
should now have cygwin in your start menu... Running it gives you a
command window with a unix-style prompt:

username@hostname WorkingDir
$

Tips:
    The Tab key will complete the remains of a filename/directory
    name if unique. If not unique, it will complete as much as
    possible, and a second Tab will indicate the possible matches.

    ~/ is shorthand for your home directory. You can always go to
    this directory with cd ~/

    Your PC's drives now appear with unix paths as:
	 /cygdrive/c/
    but the cd command accepts
	cd c:
    as a shortcut.

    The cygwin installation directory: (c:/cygwin by default) is mapped
    to the cygwin 'root' directory: '/'


Note: If your PC does not have access to a broadband internet
connection, and you don't want to spend several hours downloading 40Mb
of Cygwin, but you have access to another PC that does have broadband,
the cygwin installer has the option 'Download from Internet' to just
download the required packages into the 'Local Package Directory'.
You then write the contents of the directory to CD or a Flash disk,
then use the 'Install from Local Directory' option on your target PC.


2) Download and unpack XMLTV source
-----------------------------------

Now download the XMLTV source distribution, and the _prereq files from
sourceforge
    http://files.xmltv.org
Save them in your Cygwin Home directory: c:/cygwin/home/username

At the Cygwin command prompt, Unpack the 2 tar.bz2 files using the
command lines:
   bunzip2 -c xmltv-x.x.x.tar.bz2 |  tar -xvf -
   bunzip2 -c xmltv_prereq-x.tar.bz2 |  tar -xvf -

Where x is replaced by the version numbers of the files you downloaded


3) Install the XMLTV prereq packages:
-------------------------------------

Change directory to the prereq directory created by unpacking the
tar.bz2 file and list the packages therein.
    cd xmltv_prereq-x
    ls

For more info check the README:
    less README

Note that the packages with TK cannot be installed in the current
version of Cygwin, as PERL/TK is not yet part of Cygwin... This is not
important, and only means that the XMLTV tv_check command cannot be
installed

The packages need to be installed in alphanumeric order -- ie all
packages with 00 first, then 01 then A-Z then a-z
So, For each directory starting with 00 (apart from 00_tk*) do:
    cd directory
    perl Makefile.PL; make test install
    cd ..
Do the same for each directory starting with 01, then for each of the
remaining directories (apart from those with Tk*)...


Note: Some of the prerequisite modules (such as PerlIO-gzip, and
libwww-perl) might fail some of its tests and will not install with the
above command. These will need to be installed by running
    make install
in the package directory. I have not found the failed tests to cause a
problem yet.


Note: When installing XML-LibXML I got an error:
    C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\bin\cygiconv-2.dll
    to same address as parent...
If this is the case, close all other Cygwin windows and run the command:
    rebaseall -v
then try again.


Note: When installing HTML-Parser, answer No to the question:
    Do you want decoding on unicode entities? [no] no
I have had problems with decoded Unicode characters in Perl/Cygwin.


Note: When installing libwww-perl, answer NO to the questions:
    Do you want to install the GET alias? [y] n
    Do you want to install the HEAD alias? [y] n
    Do you want to install the POST alias? [y] n
this is because installing these aliases failed on my system!


Note: you will not be able to install Text-Kakasi (required for Japan
grabber) without downloading, building and installing the Kakasi
library. See README in the xmltv_prereq directory for more details. If
you don't need this, just skip the package.


cd back to your home directory when complete
    cd ~/

4) Configure TimeZone
---------------------

XMLTV (actually the PERL Date::Manip module) needs the TZ variable set
correctly for the time and date handling for summer and winter time to
work. Date::Manip has internal knowledge of some time zone values.

If the TZ variable is not set, some XMLTV grabbers and the tv_split
command will not work.

Cygwin has its own idea of the time zone (from windows), and
overriding the time zone with TZ can show confusing output from some
Cygwin commands that display the time and date...

eg: No TZ set, my time zone in windows is CET == GMT+1, the current
local time is 11:15)
    $ date
    Tue Mar  9 11:15:06 RST 2004
Setting TZ to CET
    $ export TZ=CET
    $ date
    Tue Mar  9 10:15:25 GMT 2004
as you can see setting a TZ variable makes Cygwin report all times as GMT...

NOTE Setting TZ does not change the date of the system, merely the
*display* of the dates...

To avoid this confusion, it is best only to set the TZ variable when
you are running the XMLTV tools.

To set your time zone, run.
    export TZ=EST
or whatever your time zone is...
This will set the time zone for all future commands run in this Cygwin
window. If you use another window, you will need to rerun this
command...

To see the list of the time zones understood by Date::Manip:
    http://search.cpan.org/~sbeck/DateManip-5.42a/Manip.pod#TIMEZONES
or if a newer version has been released, go to
    http://search.cpan.org/~sbeck
    click on Date::Manip
    Click on Date::Manip in the Modules list to see the docs
    Click on TIMEZONES to see the TZ list


To check that this TZ works with Date::Manip, run the command:
    $ perl -e 'use Date::Manip; print Date_TimeZone;'

If all is OK, and Date::Manip recognised your TZ, this should print
out the time zone. If not you will get some
errors such as "ERROR: Date::Manip unable to determine TimeZone."

The actual value of the time zone should not affect the results of most
of the XMLTV commands, grabbers and tools *EXCEPT*  for tv_grab_na --
which requires the time zone to be correctly set.


5) Install XMLTV
----------------
cd to the unpacked xmltv-x.x.x directory and run

    perl Makefile.PL

The defaults will list all the grabbers that you can install and that
are compatible with the Perl modules on your system. Either accept the
defaults, or customise the grabbers/tools that you want to install..

Note tv_check will not work due to TK not being available.

Build and test:
    make test
Normally, all tests should pass successfully.

Install:
    make install

That?s it. You can now delete the downloaded xmltv files and unpacked
directories if you want to.

You now can use XMLTV like you would normally on unix:

eg
    tv_grab_uk_rt --configure
    tv_grab_uk_rt --days 1 > uk_today.xml




6) Automation of grabbing (optional)
------------------------------------

If you need to automate the grabbing, you can use a Windows scheduled
task to run a Bash shell script as follows:

Create a file in your Cygwin home directory called
xmltv_scheduled_grab.sh containing:

-- START OF FILE -- CUT-HERE --
#!/usr/bin/bash
# IMPORTANT! previous line must be first line of file!
#
# Set up environment
. /etc/profile
. ~/.bash_profile

# cd to home directory
cd

# Set up TZ variable
# CHANGE THIS TO MATCH YOUR TIME ZONE
#
export TZ=CET

# Run grabber get 5 days listings, sending log messages to a logfile
# CHANGE THE GRABBER COMMAND LINE TO WHAT YOU REQUIRE
#
tv_grab_uk_rt --days 5 --output uk_rt_xmltv.xml | tee grab_uk_rt_xmltv.log 2>&1

-- END OF FILE -- CUT-HERE --

(Obviously, as indicated, you need to change the grabber command line
and the setting of TZ to what you require...)

Make this command  executable:
    chmod +x xmltv_scheduled_grab.sh

Test this command at the cygwin command line
    xmltv_scheduled_grab.sh

If it is OK, you should get 2 files in your cygwin home
    uk_rt_xmltv.xml containing the XMLTV output
    grab_uk_rt_xmltv.log containing the log messages from the grabber

You now need to create a Windows scheduled task to run this script
    (Win XP: Start
	  -> Control Panel
	  -> Performance and Maintenance
	  -> Scheduled tasks
	  -> Add Scheduled task
     Win 2000: Start
	  -> Control Panel
	  -> Scheduled tasks
	  -> Add Scheduled task)


Select ANY program from the list (you will change the actual command
line later).
Select a schedule (you can also change this later)
Ignore the username/password screen for the moment.
Select 'Open advanced properties for this task' before clicking OK to
allow you set the real command line in the Task Properties window...


The problem with this command is that it will want to create a console
window that will pop up on top of everything else when it runs...

You can either create this window minimised (via a transient window
that will pop up and disappear -- also annoying, but less so) using the scheduled
command:
    cmd /c start /min c:\cygwin\bin\bash.exe ~/xmltv_scheduled_grab.sh

or if you download and install the program runhide from:
   http://www.extendingflash.com/utilities/runhide.html
and then use the scheduled command line
    runhide.exe c:\cygwin\bin\bash.exe ~/xmltv_scheduled_grab.sh
then the window will never appear...

You can test these command lines by pasting them into the start->Run box.


Enter the required command line in the Scheduled Task Properties window.
Click the 'Set password' button, and enter your password (if you have one).
Check the Schedule and Settings tabs.
Finally click OK.

You can test the scheduled task by right-clicking it and selecting Run.

======================================================================

HISTORY
-------

$Id: README.cygwin,v 1.2 2015/07/12 00:46:37 knowledgejunkie Exp $

09/03/2004 Niel Markwick
	   initial version
11/03/2004 Niel Markwick
	   added more information on Time Zones, corrected typo's