.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TV_GRAB_UK_TVGUIDE 1p"
.TH TV_GRAB_UK_TVGUIDE 1p "2023-02-24" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
tv_grab_uk_tvguide \- Grab TV listings for UK from the TVGuide website.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
tv_grab_uk_tvguide \-\-usage
.PP
tv_grab_uk_tvguide \-\-version
.PP
tv_grab_uk_tvguide \-\-configure [\-\-config\-file \s-1FILE\s0] [\-\-gui \s-1OPTION\s0] [\-\-method N]
                   [\-\-makeignorelist \s-1FILE\s0] [\-\-useignorelist \s-1FILE\s0] [\-\-debug]
.PP
tv_grab_uk_tvguide [\-\-config\-file \s-1FILE\s0] [\-\-output \s-1FILE\s0] [\-\-days N]
                   [\-\-offset N] [\-\-nodetailspage]  [\-\-legacychannels]
                   [\-\-quiet] [\-\-debug]
.PP
tv_grab_uk_tvguide \-\-list\-channels [\-\-output \s-1FILE\s0] [\-\-method N] [\-\-debug]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Output \s-1TV\s0 listings in \s-1XMLTV\s0 format for many channels available in \s-1UK.\s0
The data come from tvguide.co.uk
.PP
First you must run \fBtv_grab_uk_tvguide \-\-configure\fR to choose which channels
you want to receive.
.PP
Then running \fBtv_grab_uk_tvguide\fR with no arguments will get programme listings 
in \s-1XML\s0 format for the channels you chose, for available days including today.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fB\-\-configure\fR Prompt for which channels to fetch the schedule for, 
and write the configuration file.
.PP
\&\fB\-\-config\-file \s-1FILE\s0\fR Set the name of the configuration file, the default 
is \fB~/.xmltv/tv_grab_uk_tvguide.conf\fR.  This is the file written by
\&\-\-configure and read when grabbing.
.PP
\&\fB\-\-gui \s-1OPTION\s0\fR Use this option to enable a graphical interface to be used.
\&\s-1OPTION\s0 may be 'Tk'. 
Additional allowed values of \s-1OPTION\s0 are 'Term' for normal terminal output (default)
 and 'TermNoProgressBar' to disable the use of Term::ProgressBar.
(May not work on Windows \s-1OS.\s0)
.PP
\&\fB\-\-days N\fR Grab N days. The default is 5 days.
.PP
\&\fB\-\-offset N\fR Start N days in the future.  The default is to start
from today.
.PP
\&\fB\-\-nodetailspage\fR Only fetch summary information for each programme. (See discussion below).
.PP
\&\fB\-\-legacychannels\fR Channel ids were made compliant with the \s-1XMLTV\s0 specification 
in December 2020. Use \-\-legacychannels to output channel ids in the previous format
 (i.e. number only).
.PP
\&\fB\-\-output \s-1FILE\s0\fR Write to \s-1FILE\s0 rather than standard output.
.PP
\&\fB\-\-method N\fR This program has three methods for fetching the list of
channels available. The preferred method can be overridden with an option of
either \-\-method 1 or \-\-method 2 to use one of the two alternative methods.
.PP
If no \-\-method parameter is supplied then the various methods will be tried in 
sequence until a channels list is obtained. A parameter of \-\-method 0 will run 
the preferred method only.
.PP
Normally you should omit this parameter.
.PP
\&\fB\-\-makeignorelist \s-1FILE\s0\fR The source channel list contains many channels which
have no programme listings available. By using a local file of channel ids
these can be filtered out during the configure process. This option creates 
a list of channel ids which can be excluded from your config file
.PP
makeignorelist can take over an hour to run but you only need run it 
infrequently (not every time you run \-\-configure).
.PP
\&\fB\-\-useignorelist \s-1FILE\s0\fR Specify the file containing a list of channel ids 
to be removed during the configure stage.
.PP
This may be the file just created with \-\-makeignorelist
(e.g. \-\-configure \-\-makeignorelist myfile \-\-useignorelist myfile )
.PP
\&\fB\-\-quiet\fR Suppress the progress messages normally written to the console.
.PP
\&\fB\-\-debug\fR Provide more information on progress to standard error to help in
debugging.
.PP
\&\fB\-\-list\-channels\fR Output a list (in xmltv format) of all channels that can be fetched.
.PP
\&\fB\-\-version\fR Show the version of the grabber.
.PP
\&\fB\-\-usage\fR Print a help message and exit.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
The file \fItv_grab_uk_tvguide.map.conf\fR has two purposes.  Firstly you can map the channel ids used by the site into something more meaningful to your \s-1PVR. E\s0.g.
.PP
.Vb 1
\&      map==74==BBC 1
.Ve
.PP
will change \*(L"74\*(R" to \*(L"\s-1BBC 1\*(R"\s0 in the output \s-1XML.\s0
.PP
Note: the lines are of the form \*(L"map=={channel id}=={my name}\*(R".
.PP
The second purpose is to likewise translate genre names.  So if your \s-1PVR\s0 doesn\*(L"t have a category for \*(R"Science Fiction\*(L" but uses \*(R"Sci-fi" instead, then you can specify
.PP
.Vb 1
\&      cat==Science Fiction==Sci\-fi
.Ve
.PP
and the output \s-1XML\s0 will have \*(L"Sci-fi\*(R".
.PP
\&\s-1IMPORTANT:\s0 the downloaded \*(L"tv_grab_uk_tvguide.map.conf\*(R" contains example lines to illustrate the format \- you should edit this file to suit your own purposes!
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
If the grabber fails to download data for some channel on a specific day,
it will print an errormessage to \s-1STDERR\s0 and then continue with the other
channels and days. The grabber will exit with a status code of 1 to indicate
that the data is incomplete.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The environment variable \s-1HOME\s0 can be set to change where configuration
files are stored. All configuration is stored in \f(CW$HOME\fR/.xmltv/. On Windows,
it might be necessary to set \s-1HOME\s0 to a path without spaces in it.
.SH "SUPPORTED CHANNELS"
.IX Header "SUPPORTED CHANNELS"
For information on supported channels, see http://tvguide.co.uk/
.SH "XMLTV VALIDATION"
.IX Header "XMLTV VALIDATION"
\&\fBtv_validate_grabber\fR may report an error similar to:
.PP
.Vb 1
\&      "Line 5 Invalid channel\-id BBC 1"
.Ve
.PP
This is a because ValidateFile.pm insists the channel-id adheres to \s-1RFC2838\s0 despite the xmltv.dtd only saying \*(L"preferably\*(R" not \*(L"\s-1SHOULD\*(R".\s0
(Having channel ids of the form \*(L"bbc1.bbc.co.uk\*(R" will be rejected by many PVRs since they require the data to match their own list.)
.PP
It may also report:
.PP
.Vb 1
\&      "tv_sort failed on the concatenated data. Probably due to overlapping data between days."
.Ve
.PP
Both these errors can be ignored.
.SH "USING \-\-nodetailspage"
.IX Header "USING --nodetailspage"
This option may be useful if you have problems accessing the tvguide website:
it will considerably speed up your grabbing, but at the expense of data richness.
The details page has a better list of actors, as well as director's names, 
film classifications, and background images.
.PP
More significantly, the details page includes programme duration and programme end time. If you don't include the details page then your output programmes will not have stop times. Although stop times are an optional \s-1XMLTV\s0 element, many downstream programs expect them and break without them.
.PP
Fortunately, these can be added by piping your xml file through the tv_sort filter: this will add stop times to all programmes except for the last programme on every channel. For example:
.PP
.Vb 1
\&      tv_grab_uk_tvguide \-\-days 3 \-\-nodetailspage | tv_sort \-\-by\-channel \-\-output myprogrammes.xml
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR As at January 2022 it seems the actor/director names and film classification
is no longer present in the website, although it may be there for some channels(?). 
Therefore you may find the \-\-nodetailspage option useful to significantly reduce your run time.
\&\fBHowever\fR, the details page does include background image(s) of the programme, which is
not present in your xml file when using \-\-nodetailspage
.SH "BE KIND"
.IX Header "BE KIND"
If using the details page from the website then your grabbing might benefit from a more targeted strategy, rather than blithely getting all days for all channels.
.PP
Since the published schedule rarely changes, a strategy of grabbing the next 3 days plus the 1 newest day would give you any new programmes as well as any last minute changes. Simply fetch \*(L"\-\-offset 0 \-\-days 3\*(R" and concatenate it with a separate fetch of \*(L"\-\-offset 7 \-\-days 1\*(R".
.PP
For example:
.Sp
.RS 6
( tv_grab_uk_tvguide \-\-days 3 \-\-offset 0 \-\-output temp.xml ) && ( tv_grab_uk_tvguide \-\-days 1 \-\-offset 7 | tv_cat \-\-output myprogrammes.xml temp.xml \- ) && ( rm \-f temp.xml )
.RE
.PP
A similar strategy could be employed when using \-\-nodetailspage if you have a lot of channels:
.Sp
.RS 6
( tv_grab_uk_tvguide \-\-days 3 \-\-offset 0 \-\-nodetailspage | tv_sort \-\-by\-channel >temp.xml ) && ( tv_grab_uk_tvguide \-\-days 1 \-\-offset 7 \-\-nodetailspage | tv_sort \-\-by\-channel | tv_cat \-\-output myprogrammes.xml temp.xml \- ) && ( rm \-f temp.xml )
.RE
.PP
This avoids overloading the TVGuide website, and significantly reduces your runtime with minimal impact on your viewing schedule.
.PP
TVGuide provide this data for free, so let's not abuse their generosity.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
The TVGuide website's license for these data does not allow non-personal use.
.PP
Certainly, any commercial use of listings data obtained by using this grabber will breach copyright law, but if you are just using the data for your own personal use then you are probably fine.
.PP
By using this grabber you aver you are using the listings data for your own personal use only and you absolve the author(s) from any liability under copyright law or otherwise.
.SH "AUTHOR"
.IX Header "AUTHOR"
Geoff Westcott. This documentation and parts of the code
based on various other tv_grabbers from the XMLTV-project.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBxmltv\fR\|(5).