#
# Sample "rules" file for use with tv_augment
#
###############################################################################
#
# This file contains the rules used by XMLTV::Augment.
#
# The objective is to fix errors and inconsistencies in the incoming data from
# a grabber, and to enhance the programme xml where certain data are missing.
#
# For example:
# Some programme entries in the listings data may contain subtitle/episode
# information in the title field, others may contain the programme title
# and subtitle reversed, and yet more may contain 'episode' information that
# should be in the episode-num field.
#
# Rules are divided into a number of 'types' according to what they do.
# Individual types (rule sets) can be switched off in the augmentation config
# file.
#
# Matching is usually (but not exclusively) done by comparing the incoming
# <title> against the title specified in the rule below.
#
# A 'rule' definition consists of the rule 'type' separated rom the rule
# content by a pipe character ('|'). The rule content has a variable (but fixed
# for any given rule type) number of fields separated by tilde characters ('~')
#
# The action taken depends on the rule type:
#
# 1)  non_title_info
#     The content is text that is to be removed from any programme titles where
#     this text occurs at the beginning of the <title> element followed by
#     any of : ; or ,
#     e.g.
#       1|Action Heroes Season
#       "Action Heroes Season: Rambo" --> "Rambo"
#
# 2)  mixed_title_subtitle
#     The content is the desired title of a programme when the incoming title
#     contains both the programme's title *and* episode separated by : ; or -
#     ($title:$episode). We reassign the episode information to the <episode>
#     element, leaving only the programme title in the <title> element.
#     e.g.
#       2|Blackadder II
#       "Blackadder II: Potato / " --> "Blackadder II / Potato"
#
# 3)  mixed_subtitle_title
#     The content is the desired title of a programme when the incoming title
#     contains both the programme's episode *and* title separated by : ; or -
#     ($episode:$title). We reassign the episode information to the <episode>
#     element, leaving only the programme title in the <title> element.
#     e.g.
#       3|Storyville
#       "Kings of Pastry: Storyville / " --> "Storyville / Kings of Pastry"
#
# 4)  reversed_title_subtitle
#     The content is the desired title of a programme which is listed as the
#     programme's episode (i.e. the title and episode details have been
#     reversed). We therefore reverse the <title> and <episode> elements.
#     e.g.
#       4|Storyville
#       "Kings of Pastry / Storyville" --> "Storyville / Kings of Pastry"
#
# 5)  replacement_titles
#     The content contains two programme titles, separated by a
#     tilde (~). The first title is replaced by the second in the listings
#     output.
#     This is useful to fix inconsistent naming (e.g. "Law and Order" vs.
#     "Law & Order") or inconsistent grammar ("xxxx's" vs. "xxxxs'")
#     e.g.
#       5|A Time Team Special~Time Team
#       "A Time Team Special / Doncaster" --> "Time Team / Doncaster"
#
# 6)  replacement_genres
#     The content contains a programme title and a programme category(-ies)
#     (genres), separated by tilde (~). Categories can be assigned to
#     uncategorised programmes (which can be seen in the stats log).
#     (Note that *all* categories are replaced for the title.)
#     e.g.
#       6|Antiques Roadshow~Entertainment~Arts~Shopping
#       "Antiques Roadshow / " category "Reality" -->
#       "Antiques Roadshow / " category "Entertainment" + "Arts" + "Shopping"
#
# 7)  replacement_episodes
#     The content contains a programme title, an old episode value and a new
#     episode value, separated by tildes (~).
#     e.g.
#       7|Time Team~Time Team Special: Doncaster~Doncaster
#       "Time Team / Time Team Special: Doncaster" --> "Time Team / Doncaster"
#
# 8)  replacement_titles_episodes
#     The content contains an old programme title, an old episode value, a new
#     programme title and a new episode value. The old and new titles MUST be
#     given, the episode fields can be left empty but the field itself must be
#     present.
#     e.g.
#       8|Top Gear USA Special~Detroit~Top Gear~USA Special
#       "Top Gear USA Special / Detroit" --> "Top Gear / USA Special"
#
#       8|Top Gear USA Special~~Top Gear~USA Special
#       "Top Gear USA Special / " --> "Top Gear / USA Special"
#
# 9)  replacement_ep_from_desc
#     The content contains a programme title, a new episode value to update,
#     and a description (or at least the start of it) to match against. When
#     title matches incoming data and the incoming description startswith the
#     text given then the episode value will be replaced.
#     e.g.
#       9|Heroes of Comedy~The Goons~The series celebrating great British
#           comics pays tribute to the Goons.
#       "Heroes of Comedy / " desc> =  "The series celebrating great British
#           comics pays tribute to the Goons."
#         --> "Heroes of Comedy / The Goons"
#     Should be used with care; e.g.
#       "Heroes of Comedy / Spike Milligan" desc> =  "The series celebrating
#           great British comics pays tribute to the Goons."
#     would *also* become
#       "Heroes of Comedy / The Goons"
#     this may not be what you want!
#
# 10) replacement_titles_desc
#     The content contains an old programme title, an old episode value, a new
#     programme title, a new episode value and the episode description (or at
#     least the start of it) to match against.
#     The old and new titles and description MUST be given, the episode fields
#     can be left empty but the field itself must be present.
#     This is useful to fix episodes where the series is unknown but can be
#     pre-determined from the programme's description.
#     e.g.
#       10|Which Doctor~~Gunsmoke~Which Doctor~Festus and Doc go fishing, but
#           are captured by a family that is feuding with the Haggens.
#       "Which Doctor / " desc> = "Festus and Doc go fishing, but are captured
#           by a family that is feuding with the Haggens. [...]"
#          --> "Gunsmoke / Which Doctor"
#
# 11) demoted_titles
#     The content contains a programme 'brand' and a new title to be extracted
#     from subtitle field and promoted to programme title, replacing the brand
#     title.
#     In other words, if title matches, and sub-title starts with text then
#     remove the matching text from sub-title and move it into the title.
#     Any text after 'separator' (any of .,:;-) in the sub-title is preserved.
#     e.g.
#       11|Blackadder~Blackadder II
#       "Blackadder / Blackadder II: Potato" --> "Blackadder II / Potato"
#
# 12) replacement_film_genres
#     The content contains a film title and a category (genre) or categories,
#     separated by a tilde (~).
#     If title matches the rule's text and the prog has category "Film" or
#     "Films", then use the replacement category(-ies) supplied.
#     Use case: some film-related programmes are incorrectly flagged as films
#     and should to be re-assigned to a more suitable category.
#     (Note ALL categories are replaced, not just "Film")
#     e.g.
#       12|The Hobbit Special~Entertainment~Interview
#       "The Hobbit Special / " category "Film" + "Drama"  -->
#       "The Hobbit Special / " category "Entertainment" + "Interview"
#
# 13) subtitle_remove_text
#     The content contains a programme title and arbitrary text to
#     be removed from the start/end of the programme's subtitle. If the text to
#     be removed precedes or follows a "separator" (any of .,:;-), the
#     separator is removed also.
#     e.g.
#       13|Time Team~A Time Team Special
#       "Time Team / Doncaster : A Time Team Special" -->
#       "Time Team / Doncaster"
#
# 14) process_replacement_genres
#     The content contains a category (genre) value followed by replacement
#     category(-ies) separated by a tilde (~).
#     Use case: useful if your PVR doesn't understand some of the category
#     values in the incoming data; you can translate them to another value.
#     e.g.
#       14|Adventure/War~Action Adventure~War
#       "The Guns of Navarone" category "Adventure/War"  -->
#       "The Guns of Navarone" category "Action Adventure" + "War"
#
# 15) process_add_genres_to_channel
#     The content contains a channel id followed by replacement
#     category(-ies) separated by a tilde (~).
#     Use case: this can add a category if data from your supplier is always
#     missing; e.g. add "News" to a news channel, or "Music" to a music
#     vid channel.
#     e.g.
#       15|travelchannel.co.uk~Travel
#       "World's Greatest Motorcycle Rides" category "Motoring"  -->
#       "World's Greatest Motorcycle Rides" category "Motoring" + "Travel"
#       15|cnbc.com~News~Business
#       "Investing in India" category ""  -->
#       "Investing in India" category "News" + "Business"
#     You should be very careful with this one as it will add the category you
#     specify to EVERY programme broadcast on that channel. This may not be what
#     you always want (e.g. Teleshopping isn't really "music" even if it is on MTV!)
#
# 16) process_remove_numbering_from_programmes
#     The content contains a title value, followed by an optional channel
#     (separated by a tilde (~)).
#     Use case: can remove programme numbering from a specific title if it
#     is regularly wrong or inconsistent over time.
#     e.g.
#       16|Bedtime Story
#       "CBeebies Bedtime Story" episode-num ".700."  -->
#       "CBeebies Bedtime Story" episode-num ""
#       16|CBeebies Bedtime Story~cbeebies.bbc.co.uk
#       "CBeebies Bedtime Story" episode-num ".700."  -->
#       "CBeebies Bedtime Story" episode-num ""
#     Remember to specify the optional channel limiter if you have good
#     programme numbering for a given programme title on some channels but
#     not others.
#
#
###############################################################################
#
# Some sample rules follow; obviously you should delete these and replace with
#  your own!
#
1|Action Heroes Season
1|Python Night
1|Western Season
2|Blackadder II
2|Comic Relief
2|Old Grey Whistle Test
3|Storyville
4|Storyville
4|Timewatch
5|A Time Team Special~Time Team
5|Cheaper By the Dozen~Cheaper by the Dozen
5|Later - with Jools Holland~Later... with Jools Holland
6|Antiques Roadshow~Entertainment~Arts~Shopping
6|Deal or No Deal~Game show
6|Men Behaving Badly~Sitcom
7|Time Team~Time Team Special: Doncaster~Doncaster
8|Top Gear USA Special~Detroit~Top Gear~USA Special
9|Heroes of Comedy~The Goons~The series celebrating great British comics pays tribute to the Goons.
10|Which Doctor~~Gunsmoke~Which Doctor~Festus and Doc go fishing, but are captured by a family that is feuding with the Haggens.
11|Blackadder~Blackadder II
11|Formula One~Live Formula One
11|Man on Earth~Man on Earth with Tony Robinson
12|Hell on Wheels~Drama
12|The Hobbit Special~Entertainment~Interview
13|Time Team~A Time Team Special
13|World's Busiest~World's Busiest
14|Adventure/War~Action Adventure~War
14|NFL~American Football
14|Soccer~Football
15|smashhits.net~Music
15|travelchannel.co.uk~Travel
16|Antiques Roadshow~bbc1.bbc.co.uk
16|Classic Antiques Roadshow
#
# (the sample rules shown here are in sorted order but that is not necessary
#  in your live file)
###############################################################################
