path: root/doc-src/en/epgsearch.4.txt

=head1 NAME

F<epgsearch> - Searchtimer and replacement of the VDR program menu

=head1 OVERVIEW

Since the README get bigger and bigger this man page shall be used
to explain some things in detail. So it's not really a manual, but an
extended README.

=head1 CONTENT

 1.  Using variables in the directory entry of a search timer
 2.  The format of epgsearch.conf
 3.  Description of the search process
 4.  How do Search Timers work?
 5.  How to trigger a search timer update?
 6.  The sources of the 'Select directory' menu
 7.  Language dependent commands for EPG
 8.  Usage from other plugins or scripts
 9.  SVDRP interface
 10. Customizing the EPG menus
 11. Working with the timer conflict menu
 12. User defined variables
 13. Email notifications
 14. The conf.d subdirectory

=head1 1. Using variables in the directory entry of a search timer

If you are using extended EPG information, you can use variables as
part of a directory entry of a search timer. These variables always have
the form '%variable%'. The name of a variable corresponds with the
internal name of an extended EPG info, as specified in the file
epgsearchcats.conf (samples can be found in subdirectory 'conf'). 
Example: 

 1|Category|Kategorie|Information,Kinder,Musik,Serie,Show,Spielfilm,Sport|3

The category with ID 1 has the internal name 'Category'. So you could
use it with '%Category%'. The names are not case sensitive. Sample
directory entries could look like this:

 My Movies~%Category%
 Childrens Movies~%category%
 %CATEGORY%~%genre%

There are also three other variables: %Title%, %Subtitle% and %chlng%.
If you don't use %Title%, the title is always automatically
appended to the directory entry, when a timer will be created. If you
set 'serial recording' to 'yes' in your search timer then also the
subtitle will be automatically appended. So the directory entry

 %Category%~%Genre%~%Title%~%Subtitle%

is the same as 

 %Category%~%Genre%
 (with 'serial recording' set to 'yes').

The %chnlng% variable gets replaced with the name of the channel.

Attention: Automatically appending title and subtitle will not be
done, if you use the variables %Title% or %Subtitle% in the directory
entry. This allows to form directory entries like this one:

 %Category%~%Genre%~%Title%~%Episode%~%Subtitle%

There are also the following search variables:

 %search.query% that will be replaced with the query of the search timer
 %search.series% that is '1', if the search has it's 'Series recording' flag set, else '0'.

See also C<epgsearchuservars.conf(5)>.

=head1 2. The format of epgsearch.conf

Due to some new features there was a change in the format. The format
is now signed with a comment in the first line. The field delimiter
is B<':'>:

  1 - unique search timer id
  2 - the search term
  3 - use time? 0/1
  4 - start time in HHMM 
  5 - stop time in HHMM 
  6 - use channel? 0 = no,  1 = Interval, 2 = Channel group, 3 = FTA only
  7 - if 'use channel' = 1 then channel id[|channel id] in vdr format,
      one entry or min/max entry separated with |, if 'use channel' = 2
      then the channel group name     
  8 - match case? 0/1 
  9 - search mode:
       0 - the whole term must appear as substring
       1 - all single terms (delimiters are blank,',', ';', '|' or '~') 
 	  must exist as substrings.
       2 - at least one term (delimiters are blank, ',', ';', '|' or '~') 
           must exist as substring.
       3 - matches exactly
       4 - regular expression
       5 - fuzzy searching (specify tolerance in parameter 42, not available
           for EPG categories)
 10 - use title? 0/1
 11 - use subtitle? 0/1
 12 - use description? 0/1
 13 - use duration? 0/1
 14 - min duration in minutes
 15 - max duration in minutes
 16 - use as search timer? 0/1/2 (with 2 one can specify time margins in 
      parameter 48/49 where the search timer is active)
 17 - use day of week? 0/1
 18 - day of week (0 = Sunday, 1 = Monday...;      
      -1 Sunday, -2 Monday, -4 Tuesday, ...; -7 Sun, Mon, Tue)
 19 - use series recording? 0/1
 20 - directory for recording
 21 - priority of recording
 22 - lifetime of recording
 23 - time margin for start in minutes
 24 - time margin for stop in minutes
 25 - use VPS? 0/1
 26 - action:
       0 = create a timer
       1 = announce only via OSD (no timer)
       2 = switch only (no timer)
 27 - use extended EPG info? 0/1
 28 - extended EPG info values. This entry has the following format
      (delimiter is '|' for each category, '#' separates id and value):
      1 - the id of the extended EPG info category as specified in
          epgsearchcats.conf
      2 - the value of the extended EPG info category
          (a ':' will be translated to "!^colon^!", e.g. in "16:9")
 29 - avoid repeats? 0/1
 30 - allowed repeats
 31 - compare title when testing for a repeat? 0/1     
 32 - compare subtitle when testing for a repeat? 0/1     
 33 - compare description when testing for a repeat? 0/1     
 34 - compare extended EPG info when testing for a repeat?
      This entry is a bit field of the category IDs.
 35 - accepts repeats only within x days
 36 - delete a recording automatically after x days
 37 - but keep this number of recordings anyway
 38 - minutes before switch (if action = 2)
 39 - pause if x recordings already exist
 40 - blacklist usage mode (0 none, 1 selection, 2 all)
 41 - selected blacklist IDs separated with '|'
 42 - fuzzy tolerance value for fuzzy searching
 43 - use this search in favorites menu (0 no, 1 yes)
 44 - number of the search menu template to use (only available if multiple
      search result templates are defined in epgsearchmenu.conf)
 45 - auto deletion mode (0 don't delete search timer, 1 delete after given
      count of recordings, 2 delete after given days after first recording)
 46 - count of recordings after which to delete the search timer
 47 - count of days after the first recording after which to delete the search
      timer
 48 - first day where the search timer is active (see parameter 16)
 49 - last day where the search timer is active (see parameter 16)
 50 - ignore missing EPG categories? 0/1
 51 - unmute sound if off when used as switch timer

A ':' in the search term or the directory entry will be translated in
a '|'. If a '|' exists in the search term, e.g. when using regular
expressions, it will be translated to "!^pipe^!" (I know it's ugly ;-))

See also C<epgsearch.conf(5)>.

=head1 3. Description of the search process

First, for each broadcasting a search text divided by '~' is created,
depending on the settings of 'Use title', 'Use subtitle' and 'Use
description': 

 title~subtitle~description

If "Match case" is not set, the search text and the search term are
transformed to lower case.
Now depending on the search mode, the search term will be looked up in
the search text:

=over 4

=item - 'Phrase' matches

if the search term is found anywhere in the search text.

=item - 'at least one word', 'all words'

first the search term will be split in single words. Delimiters are a
blank and the characters ',' ';' '|' '~'. 

Then we check if at least one or all words appear in the search text.

=item - 'match exactly'

matches if search term and search text are identical.

=item - 'regular expression'

the search is done with a regular expression. You don't need a leading
and trailing '/' in your search term.
Two standards of regular expression are supported: extended
POSIX and Perl compatible regular expressions (PCRE) (see F<INSTALL>).

=back

If the search was successful until now, the other criterions (start
time, duration, week day) are checked.


=head1 4. How do Search Timers work?

With each update, the plugin searches for new matches of your search
timers. If a new match is found then a new timer is created. For
serial recordings, the subtitle is appended to the recording
directory. Many providers deliver the subtitle just 1-2 days before
the event. The plugin uses then a date/time string for the subtitle,
but replaces this one later if the subtitle is present.

Start and end times of a broadcasting often vary a little bit. To avoid
getting many different timers for the same event, the plugin
checks before adding a new timer, if there is one, that has start and
end times which only differ by a maximum of 10 minutes (or the events 
duration if this is less then 10 minutes). If so, the present timer is 
modified, else a new timer is created. If the timer was set to inactive 
there will be no update. Also manually corrected priority or lifetime 
will not be changed when updating.

If you have set 'Announce only (no timer)' to yes, no timer is
created. Instead you get an OSD message about the event. This message
is displayed at each scan, but only if there is no timer for the event.

=head1 5. How to trigger a search timer update?

the update of search timers runs in its own thread. There are several
ways to trigger it:

=over 4

=item - automatically

after VDR starts there is always an update (after a
few seconds). After this, the setup option 'Update interval' tells
epgsearch when the next update should be done repeatedly (in minutes).

=item - manually extern

the thread observes the file '.epgsearchupdate' in the
plugins config directory. When you

 touch /path_to_file/.epgsearchupdate

this will also trigger an update. So this is a simple solution to
make an update e.g. by a script.

=item - manually intern

calling actions or pressing '3' in the menu of searches asks also
for an update.

=item - from other plugins

=back

there's a service
'Epgsearch-updatesearchtimers-v1.0' that can be used with the service
interface of VDR from other plugins with the option to inform via
OSD when the update has finished

=head1 6. The sources of the 'Select directory' menu

This menu displays directories, that can be used for search timers or
ordinary timers. The items displayed are read from the following
sources: 

   * current recording directories
   * current timer directories
   * directories used in search timers
   * directories specified in F<epgsearchdirs.conf>,
     see C<epgsearchdirs.con(5)>

The menu merges theses directories and displays only distinct
directories. With key 'yellow' one can change the depth of the
directories shown. If there are items, that contain category variables
like '%genre%', these entries are always shown before any other
directories. They are also not level dependent, but are always shown
with their full directory.

If this menu is called from the timer edit menu and an item is
selected that contains the variables "%title%" or "%subtitle" then the
'file' item of the timer gets cleared, since title or subtitle already
exist in the 'directory' item.
This list can also be accessed via the SVDRP command 'LSRD'.

=head1 7. Language dependent commands for EPG

If you like to have a language dependent list of commands simply
translate your present F<epgsearchcmds.conf> to your preferred OSD
language and store it with the filename epgsearchcmds-XXX.conf, where
XXX is the language code from i18n.c:

  { "eng,dos",
    "deu,ger",
    "slv",
    "ita",
    "dut,nla,nld",
    "por",
    "fra,fre",
    "nor",
    "fin,smi",
    "pol",
    "esl,spa",
    "ell,gre",
    "sve,swe",
    "rom,rum",
    "hun",
    "cat,cln",
    "rus",
    "hrv",
    "est",
    "dan",
  }

If there are more codes for one language (e.g. "deu,ger") choose
one of them. If there is no language dependent file, epgsearch loads
the file F<epgsearchcmds.conf>.

See also C<epgsearchcmds.conf(5)>.

=head1 8. Usage from other plugins or scripts

Searching the EPG and other functionality can be used by other plugins
or scripts. There are two approaches:

=head2 8.1. File-based (intended for use in scripts)

Therefore simply create the file '.epgsearchrc' in the plugins config
directory with the following lines in it:

 Search=your search term
 Searchmode=x  // 0=phrase, 1=and, 2=or, 3=regular expression
 ChannelNr=x   // add this line, to search on a specific channel
 UseTitle=x    // 1(default) or 0
 UseSubtitle=x // 1(default) or 0
 UseDescr=x    // 1(default) or 0

Then call Epgsearch via svdrpsend.pl (you must have assigned a key
to it), e.g.

 svdrpsend.pl HITK green

At startup Epgsearch will look for this file and give you the
search results for your search, if it exists. After that the file is
removed.

A sample script F<recrep.sh>, that searches for the repeats of a recording
exists in the scripts subdirectory of Epgsearch.

=head2 8.2. via Plugin-Interface (intended for use in plugins)

A plugin can directly call two functions of epgsearch with only some
lines of source code:

 - searching the EPG for some criteria and display the result list
 - extended timer edit menu

I have added a quick and dirty dummy plugin
(source/vdr-epgsearchclient-0.0.1.tgz), that demonstrates the usage.

=head1 9. SVDRP interface

epgsearch implements a SVDRP interface, that can be accessed for
example like this

 svdrpsend.pl PLUG epgsearch LSTS

the following commands are available:

=head2 search management:

 * 'LSTS [ID]' to list all searches, or the one with the passed ID
   (format is the same as epgsearch.conf)
 * 'NEWS <settings>' to add a new search
   REMARK: the value of element ID is ignored. epgsearch will always
   assign the next free ID
 * 'DELS <ID>' to delete the search with ID
 * 'EDIS <settings>' to modify an existing search
 * 'UPDS [OSD]' to update the search timers. Passing the optional keyword
   'OSD' pops up an OSD message after the update has finished.
 * 'MODS ID ON|OFF' turns on/off the option 'Use as search timer'.
 * 'UPDD' to reload the file epgsearchdone.data, e.g. after an
   external tool has modified it.
 * 'SETS <ON|OFF>' to temporarily activate or cancel the search timer background
   thread. 
 * 'FIND <settings>' for searching the EPG
   input is the same as with 'NEWS'. output is a list of found events formatted
   as 'NEWT' lines. So they can be immediately used to create a new timer for
   an event.
 * 'QRYS < ID(s) >' to get the results for a search with the given
   ID. Multiple IDs can also be passed and have to be separated with '|'. 
   The results are formatted like this:

   search ID    : // the ID of the corresponding search timer
   event ID     : // VDR event ID
   title        : // event title, any ':' will be converted to '|'
   episode name : // event short text, any ':' will be converted to '|'
   event start  : // event start in seconds since 1970-01-01
   event stop   : // event stop in seconds since 1970-01-01
   channel      : // channel ID in VDR's internal representation (e.g. 'S19.2E-1-1101-28106')
   timer start  : // timer start in seconds since 1970-01-01 (only valid if timer flag is > 0)
   timer stop   : // timer stop in seconds since 1970-01-01 (only valid if timer flag is > 0)
   timer file	: // timer file (only valid if timer flag is > 0)
   timer flag   : // 0 = no timer needed, 1 = has timer, 2 timer planned for next update)
 * 'QRYS <settings>' to get the results for a search with the given search
   settings. 
 * 'QRYF [hours]' to get the results for the favorites menu, see QRYS for
   result format. The optional parameter specifies the number of hours to
   evaluate and defaults to 24h. 
 * 'MENU [PRG|NOW|SUM]' calls one of the main menus of epgsearch or the summary
   of the current event.

=head2 channel group management:

 * 'LSTC [channel group name]'
   list all channel groups or if given the one with name 'group name'
 * 'NEWC <channel group settings>'
   create a new channel group, format as in epgsearchchangrps.conf
 * 'EDIC <channel group settings>'
   modify an existing channel group, format as in epgsearchchangrps.conf
 * 'DELC <channel group name>'
   delete an existing channel group
 * 'RENC <old channel group name|new channel group name>'
   rename an existing channel group

=head2 blacklist management:

 * 'LSTB [ID]' to list all blacklists, or the one with the passed ID
   (format is the same as epgsearchblacklists.conf)
 * 'NEWB <settings>' to add a new blacklist
   REMARK: the value of element ID is ignored. epgsearch will always
   assign the next free ID
 * 'DELB <ID>' to delete the blacklist with ID
 * 'EDIB <settings>' to modify an existing blacklist

=head2 search template management:

 * 'LSTT [ID]' to list all search templates, or the one with the passed ID
   (format is the same as epgsearch.conf)
 * 'NEWT <settings>' to add a new search template
   REMARK: the value of element ID is ignored. epgsearch will always
   assign the next free ID
 * 'DELT <ID>' to delete the search template with ID
 * 'EDIT <settings>' to modify an existing search template
 * 'DEFT [ID]' returns the ID of the default search template. When passing an
   ID it activates the corresponding template as default.

=head2 extended EPG categories:

 * 'LSTE [ID] to get the extended EPG categories defined in epgsearchcats.conf
   or the one with the given ID. (format is the same as epgsearchcats.conf)

=head2 misc:

 * 'SETP [option]' returns the current value of the given setup option or a
   list of all options with their current values.
   The following options can be accessed:
    - ShowFavoritesMenu
    - UseSearchTimers

=head2 timer conflicts:

 * 'LSCC [REL]' returns the current timer conflicts. With the option 'REL' only
   relevant conflicts are listed. The result list looks like this for example 
   when we have 2 timer conflicts at one time:

   1190232780:152|30|50#152#45:45|10|50#152#45

   '1190232780' is the time of the conflict in seconds since 1970-01-01. It's 
   followed by list of timers that have a conflict at this time:

   '152|30|50#152#45' is the description of the first conflicting timer. Here:

   '152' is VDR's timer id of this timer as returned from VDR's LSTT command
   '30' is the percentage of recording that would be done (0...100)
   '50#152#45' is the list of concurrent timers at this conflict

   '45|10|50#152#45' describes the next conflict


=head1 10. Customizing the EPG menus

The file F<epgsearchmenu.conf> in your plugins config directory is used to store
the entries for customizing the EPG menus. You specify the look of each menu
(What's on now, What's on next, What's on at ..., Schedule, Search results,
Favorites) with a separate line. Here's a sample: 

 MenuWhatsOnNow=%chnr%:3|%progrt2s%:5| %time% %t_status%:8|%category%:6| %title% ~ %subtitle%:35
 MenuWhatsOnNext=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
 MenuWhatsOnElse=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
 MenuSchedule=%time% %t_status%:8|%genre%:14| %title% ~ %subtitle%:35
 MenuSearchResults=%chnr%:3|%datesh% %time% %t_status%:14|%genre%:8| %title%%colon% %subtitle%:35
 MenuFavorites=%chnr%:3|%time%:6|%timespan%:7|%t_status%:14|%genre%:8| %title%%colon%%subtitle%:35

E.g. the entry 'MenuWhatsOnNow' tells epgsearch how you would like to build a
line for the menu 'What's on now'. This would create a menu line starting with
the channel number, followed by a progress bar in text2skin style, a space of
one char, the start time, the timer status, the EPG category (like "movie")
and finally the title and subtitle.

The values for MenuWhatsOnNext, MenuWhatsOnElse, MenuSchedule,
MenuSearchResults, MenuFavorites specify the menu 'What's on next', 'What's on
at ...', 'Schedule', 'Search results' and 'Favorites' respectively. If you do
not specify one entry, epgsearch uses it's default menu look. 

'MenuSearchResults' has something special: If you want to have different
layouts for your search results depending on the search, you can use more then
one menu template. Simply define e.g. an additional

 MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35

This will produce an additional menu item "Result menu layout" in the edit
menu of a search where you can choose between the default menu template and your
own templates. In the example above you will get "Tip of the Day" as selection
entry, since epgsearch simply cuts the leading "MenuSearchResults". When you
display the search results the chosen template will be used instead of the
default one.

The following variables exist:

 %time%           - start time in format HH:MM
 %timeend%        - end time in format HH:MM
 %date%           - start date in format DD.MM.YY
 %datesh%         - start date in format DD.MM.
 %date_iso%       - start date in format YYYY-MM-DD.
 %year%           - year with century
 %month%          - month (1-12)
 %day%            - day (1-31)
 %time_w%         - weekday name
 %time_d%         - start day in format TT
 %time_lng%       - start time in seconds since 1970-01-01 00:00
 %timespan%       - timespan from now to the beginning of an event, e.g. 'in 15m'
                    or the time an event is already running, e.g. '10m'. 
 %length%         - length in seconds
 %title%          - title
 %subtitle%       - subtitle
 %summary%        - summary
 %htmlsummary%    - summary, where all CR are replaced with '<br />'
 %eventid%        - numeric event ID
 %liveeventid%    - encoded event ID as used in the frontend 'live'
 %t_status%       - timer status ('T', 't', 'R')
 %v_status%       - VPS status
 %r_status%       - running status
 %status%         - complete status, the same as
                    '%t_status%%v_status%%r_status%'

 %<epg-category>% - a value from the extended EPG categories, specified in
                    epgsearchcats.conf, like %genre% or %category%

for the 'Whats on...' and 'Search results' menu there are also:

 %chnr%           - channel number
 %chsh%           - the short channel name (>=vdr-1.3.15)
 %chlng%          - the 'normal' channel name
 %chdata%         - VDR's internal channel representation (e.g. 'S19.2E-1-1101-28106')
 %progr%          - graphical progress bar (not for menu 'Search results'), 
                    requires VDRSymbols font for vdr>=1.5.3
 %progrT2S%       - progress bar in text2skin style (not for menu 'Search results')

some indepent variables:

 %colon%          - the sign ':'
 %datenow%        - current date in format DD.MM.YY
 %dateshnow%      - current date in format DD.MM.
 %date_iso_now%   - current date in format YYYY-MM-DD
 %timenow%        - current time in format HH:MM
 %videodir%       - VDR video directory (e.g. /video)
 %plugconfdir%    - VDR plugin config directory (e.g. /etc/vdr/plugins)
 %epgsearchdir%   - epgsearchs config directory (e.g. /etc/vdr/plugins/epgsearch)

The variables are not case sensitive. You can also use variables for extended
EPG categories defined in F<epgsearchcats.conf> or use your own user defined
variables defined in F<epgsearchuservars.conf>

An entry consists of up to 6 tables separated with '|'. The last entry of
each table should declare the table width in chars, separated with ':'.

If you use a separator like '~', '-' or '#' to separate items like title or
subtitle, e.g. %title% ~ %subtitle%, and the subtitle is empty, then epgsearch
will try to fix this automatically to avoid a trailing separator.

You should vary the tab width values to fit your needs, since the look often
depends on the selected skin. epgsearchmenu.conf is not reloaded with every
plugin call, since this is only useful when testing the conf file. To activate
the permanent reload for testing your conf, pass the new start parameter '-r'
or '--reloadmenuconf' in your runvdr.

There's a sample F<epgsearchmenu.conf> in the subdirectory "conf". For a quick try
copy it to your plugins config directory (e.g. /etc/vdr/plugins).

To enable icons from WarEagleIcon-Patch simply put the line

 WarEagleIcons=1

to F<epgsearchmenu.conf>. This also works for vdr>=1.5.3, which uses true type fonts, 
if you have installed and selected the font VDRSymbols.ttf (available at 
http://andreas.vdr-developer.org/fonts/download.html)

NOTE: As long as there is a file epgsearchmenu.conf with an entry for a special
menu, all setup settings regarding the look of this menu are ignored.

See also C<epgsearchmenu.con(5)>.

=head1 11. Working with the timer conflict menu

If a conflict is detected within the periodic conflict background check you get
an OSD message which informs you about it. Pressing 'Ok' you will get a menu
that displays all relevant conflicts. You can manually call this menu in
epgsearch in the menu 'Search/Actions'.

Besides the relevant conflicts (relevance is controlled via the setup options
of epgsearch) there may also be conflicts which are not classified as
important. If so, you can press 'Show all' to get the complete list. The menu
title always displays the number of relevant conflicts and the total number.

The list displays first the time when a conflict appears and then all timers
that will fail here. A timer entry consists of the channel number and its name
followed by the timer priority and the percentage value that shows how much of
the timer will be recorded. Finally the timer's file entry is displayed. 

When you select a timer entry and press 'Ok' or 'Details' you get a new menu
which displays all concurrent timers. This menu allows you to resolve the
conflict by

 - searching a repeat for an event
 - disabling a timer
 - deleting a timer
 - changing the timers start- or stop-time or its priority
 - executing any other commands on this timer

An entry of this menu consists of the sign '>' to indicate an active timer,
the channel number, the start and stop time, the priority, the number of the
device that will do the recording (or 'C' for conflict) and the timer's file
entry. Pressing 'Ok' on a timer entry will show you its event description if
present. 

If one returns from this menu to the conflict overview menu there will be an
automatic update to see if a conflict was really resolved. Some changes to a
timer (like modifying start/stop or deleting a timer) in the conflict details
menu also cause an immediate return to the overview menu and produce an
update. 

=head1 12. User defined variables

You can create your own variables to be used in any place that supports
variables, like the default recording directory for manually created timers,
the recording directory of a search timer or in your customized EPG menus.
Put them in the file F<epgsearchuservars.conf>.

Variables looks like %Variablename%.

"Variablename" can be consist of any alphanumerical character. Space
and special characters are not allowed.

The variable names are case-insensitive.

Examples for possible names:

 %Series% %DocuVar1% %ThemesSubtitleDate1%

=head2 Assignment

 %Series%=New series~Thriller

The variable %Series% will be assigned with the string "New series~Thriller".

Assignments are always strings. Spaces stay spaces.

 %Path%=%Series%

The variable %Path% gets the content of the variable %Series%.

You can do nearly everything:

 %Path%=%Serie%~Lost

The variable %Path% contains now the string "New series~Thriller~Lost".

=head2 Control structures

You can use simple "if then else" constructions.

These constructions cannot contain strings, only variables.
Spaces are ignored.

 %Foo%=Other

 %Variable%=%Path% ? %Path% : %Foo%

If %Path% is not empty, assign the content of %Path% to %Variable%,
otherwise the content of %Foo%.

"%Path% ?" means "not empty?". You can use other checks.

 %Variable%=%Path%!=5 ? %Path% : %Foo%

"%Path%!=5 ?" means "is %Path% equal 5?"

You can also compare variables.

 %Five%=5

 %Variable%=%Path%!=%Five% ? %Path% : %Foo%

Other possible checks:

 ==   equal
 !=   not equal

=head2 Calling a system command

You can call external commands. The returned string will be assigned
to a variable

 %uservar%=system(scriptname[, parameters]) 

Calls the script "scriptname" with the parameters defined in the optional list
of 'parameters'. This can be an arbitrary expression containing other user
variables, but not again a system call or a conditional expression.

Sample: 

 %myVar%=system(/usr/local/bin/myscript.sh, -t %title% -s %subtitle% -u %myOtherVar%) 
 
The script must return a string B<without> line break!

If the script returns nothing, an empty string will be assigned to the
Variable %Result%.

=head2 Calling a TCP service

You can call a TCP service with the following syntax:

 %uservar%=connect(<addr>, <port>, [<data>]) 

This will connect to <addr> through the given port and pass the optional given
data. <addr> can be an IP address or the domain name of the TCP service. The result 
returned by the service must be terminated with a line feed. 

=head2 Possible variables

for a list of already builtin variables refer to the section "Customizing the EPG menus"
Furthermore you can use every variable defined in F<epgsearchcats.conf>.

See C<epgsearchcats.conf(5)>.

=head2 EXAMPLES

 # Weekday, Date, Time   
 %DateStr%=%time_w% %date% %time%

 # Themes or Subtitle or Date
 %ThemesSubtitleDate1%=%Subtitle% ? %Subtitle% : %DateStr%
 %ThemesSubtitleDate%=%Themes% ? %Themes% : %ThemesSubtitleDate1%

 # Calls this script to get a recording path
 %DocuScript%=system(doku.pl, -t %Title% -s %Subtitle% -e %Episode% -th %Themes% -c %Category% -g %Genre%)
 %Docu%=%DocuScript%

=head1 13. Email notification

If you want to get email notifications about timers added/modified/removed by
the search timer thread or about timer conflicts, first copy the script
'sendEmail.pl' to the place where your executables are (e.g. /usr/local/bin)
and then configure your email account in the setup. Press 'Test' to check if
it works. There should be something like 'Email successfully sent' at the end
of the output.
The content of the mails is defined by the files

  - epgsearchupdmail.templ (for search timer update notifications)
  - epgsearchconflmail.templ (for timer conflict notifications)

You can find sample files in the 'conf' directory. Copy them to epgsearchs
config directory (e.g. /etc/vdr/plugins/epgsearch).

=head2 Customizing the notifications mails

The content of the mails can be customized in many ways. You can use plain
text or HTML (see the sample conf/epgsearchupdmail-html.templ). For an update
mail you have to define the following sections:

  - "subject" to be used as mail subject
  - "mailbody" the body of the mail:
    put %update.newtimers% in the place where the list of new timers should
    appear. The same for %update.modtimers%, %update.deltimers% and 
    %update.newevents& for the list of changed or deleted timers and event
    announcements.
  - "timer" the description of one timer and "event" with the description of
    one event. This section is used to display one timer within a timer list, 
    e.g. in %update.newtimers%. The same for "event".

All sections are optional, e.g. if you don't use event announcements you
can drop "%update.newevents%" in the mailbody and the "event" section. But
of course you should have at least a mailbody ;-)
Each section is enclosed in a pseudo XML tag.

The following variables can be used in the section <mailbody>:

  - %update.newtimers%      - will be replaced with the list of new timers
                              created with this update. The timers are
                              displayed as defined in the section '<timer>'
  - %update.countnewtimers% - the number of new timers
  - %update.modtimers%      - same as %update.newtimers% but for modified
                              timers. 
  - %update.countmodtimers% - the number of modified timers
  - %update.deltimers%      - same as %update.newtimers% but for deleted
                              timers. (Note: a deleted timer has eventually
                              no event assigned to it. So all event variables
                              within the timer section will be substituted to
                              an empty string.)
  - %update.countdeltimers% - the number of deleted timers
  - %update.newevents%      - will be replaced with the list of events to 
                              announce. These events are the search result of
                              search timers with the action "announce by mail".
                              The events are displayed as defined in the section
                              '<event>'
  - %update.countnewevents% - the number of new events
  - %colon%                 - the sign ':'
  - %datenow%               - current date in format TT.MM.YY
  - %dateshnow%             - current date in format TT.MM.
  - %timenow%               - current time in format HH:MM

The following variables can be used in the section <timer>:

  - %timer.date%            - date of the timer
  - %timer.start%           - start time of the timer
  - %timer.stop%            - stop time of the timer
  - %timer.file%            - recording directory of the timer
  - %timer.chnr%            - channel number 
  - %timer.chsh%            - short channel name
  - %timer.chlng%           - channel name
  - %timer.search%          - name of the search timer, that created the timer
  - %timer.searchid%        - id of the search timer, that created the timer
  - %timer.modreason%       - the reason for a timer modification in plain text
  - %timer.liveid%    	    - encoded timer ID as used in the frontend 'live'
  - any event variable (as in '10. Customizing the EPG menus')
  - any extended EPG variable as defined in epgsearchcats.conf
  - any user variable (as in '12. User defined variables')

The following variables can be used in the section <event>:

  - any event variable (as in '10. Customizing the EPG menus')
  - %search%                - the name of the search timer that triggered
                              this event
  - %searchid%              - the ID of the corresponding search timer
  - any extended EPG variable as defined in epgsearchcats.conf
  - any user variable (as in '12. User defined variables')

For a conflict notification mail the following sections exist:

  - "subject" to be used as mail subject
  - "mailbody" the body of the mail. Put %conflict.conflicts% in the place
    where the list of conflict times should appear (Note: there can be more
    than one timer conflict at the same time!). A conflict time uses the
    section 'conflictsat' to display its content.
  - "conflictsat" the description of one time where one or more conflicts
    exists. Put %conflict.confltimers% in the place where the list of conflict
    timers should appear.
  - "confltimer" the description of one conflicting timer

The following variables can be used in the section <mailbody>:

  - %conflict.count%        - complete number of timer conflicts
  - %conflict.conflicts%    - list of times with conflicting timers

The following variables can be used in the section <conflictsat>:

  - %conflict.date%         - date of the conflict
  - %conflict.time%         - time of the conflict
  - %conflict.confltimers%  - list of conflicting timers for this time

The section <conflicttimer> can use the same variables as the section <timer>
in an update mail (see above).

=head1 14. The conf.d subdirectory

epgsearch supports a configuration mechanism well-known in linux. The settings of the configuration files

  - epgsearchuservars.conf
  - epgsearchdirs.conf
  - epgsearchmenu.conf
  - epgsearchcats.conf

can also be given in a file with arbitrary name in the subdirectory conf.d in 
<plugin-configuration-directory>/epgsearch. This allows one to quickly test different setups only
by exchanging files instead of editing them. The format of these files is

  [<section name>]
  <settings>
  ...

  [<section name>]
  <settings>
  ...

where <section_name> is one of the following:

  - epgsearchuservars
  - epgsearchdirs
  - epgsearchmenu
  - epgsearchcats

The <settings> format follows the one in the corresponding configuration file.
Comments beginning with # are allowed, also blank lines.
At startup epgsearch first reads its 'regular' configuration files and then the conf.d subdirectory. 
It's allowed to overwrite variables already defined in other files (although this is signaled with a warning in 
epgsearch's log file.).


=head1 SEE ALSO

C<epgsearch(1)>, C<epgsearch.conf(5)>, C<epgsearchuservars.con(5)>, C<epgsearchdirs.conf(5)>, C<epgsearchmenu.conf(5)>, C<epgsearchcmds.conf(5)>

=head1 AUTHOR (man pages)

Mike Constabel <epgsearch (at) constabel (dot) net>

=head1 REPORT BUGS

Bug reports (german): 

L<http://www.vdr-developer.org/mantisbt/>

Mailing list:

L<http://www.vdr-developer.org/mailman/listinfo/epgsearch>


=head1 COPYRIGHT and LICENSE

Copyright (C) 2004-2010 Christian Wieninger

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Or, point your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html

The author can be reached at cwieninger@gmx.de

The project's page is at http://winni.vdr-developer.org/epgsearch

The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.