diff options
Diffstat (limited to 'html/en/epgsearch.4.html')
| -rw-r--r-- | html/en/epgsearch.4.html | 912 |
1 files changed, 912 insertions, 0 deletions
diff --git a/html/en/epgsearch.4.html b/html/en/epgsearch.4.html new file mode 100644 index 0000000..d7ca287 --- /dev/null +++ b/html/en/epgsearch.4.html @@ -0,0 +1,912 @@ +<?xml version="1.0" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>Epgsearch Version 0.9.24.beta9</title> +<meta http-equiv="content-type" content="text/html; charset=utf-8" /> +<link rev="made" href="mailto:root@localhost" /> +</head> + +<body style="background-color: white"> + +<p><a name="__index__"></a></p> +<!-- INDEX BEGIN --> + +<ul> + + <li><a href="#name">NAME</a></li> + <li><a href="#overview">OVERVIEW</a></li> + <li><a href="#content">CONTENT</a></li> + <li><a href="#1__using_variables_in_the_directory_entry_of_a_search_timer">1. Using variables in the directory entry of a search timer</a></li> + <li><a href="#2__the_format_of_epgsearch_conf">2. The format of epgsearch.conf</a></li> + <li><a href="#3__description_of_the_search_process">3. Description of the search process</a></li> + <li><a href="#4__how_do_search_timers_work">4. How do Search Timers work?</a></li> + <li><a href="#5__how_to_trigger_a_search_timer_update">5. How to trigger a search timer update?</a></li> + <li><a href="#6__the_sources_of_the__select_directory__menu">6. The sources of the 'Select directory' menu</a></li> + <li><a href="#7__language_dependent_commands_for_epg">7. Language dependent commands for EPG</a></li> + <li><a href="#8__usage_from_other_plugins_or_scripts">8. Usage from other plugins or scripts</a></li> + <ul> + + <li><a href="#8_1__filebased__intended_for_use_in_scripts_">8.1. File-based (intended for use in scripts)</a></li> + <li><a href="#8_2__via_plugininterface__intended_for_use_in_plugins_">8.2. via Plugin-Interface (intended for use in plugins)</a></li> + </ul> + + <li><a href="#9__svdrp_interface">9. SVDRP interface</a></li> + <ul> + + <li><a href="#search_management_">search management:</a></li> + <li><a href="#channel_group_management_">channel group management:</a></li> + <li><a href="#blacklist_management_">blacklist management:</a></li> + <li><a href="#search_template_management_">search template management:</a></li> + <li><a href="#extended_epg_categories_">extended EPG categories:</a></li> + <li><a href="#misc_">misc:</a></li> + <li><a href="#timer_conflicts_">timer conflicts:</a></li> + </ul> + + <li><a href="#10__customizing_the_epg_menus">10. Customizing the EPG menus</a></li> + <li><a href="#11__working_with_the_timer_conflict_menu">11. Working with the timer conflict menu</a></li> + <li><a href="#12__user_defined_variables">12. User defined variables</a></li> + <ul> + + <li><a href="#assignment">Assignment</a></li> + <li><a href="#control_structures">Control structures</a></li> + <li><a href="#calling_a_system_command">Calling a system command</a></li> + <li><a href="#possible_variables">Possible variables</a></li> + <li><a href="#examples">EXAMPLES</a></li> + </ul> + + <li><a href="#13__email_notification">13. Email notification</a></li> + <ul> + + <li><a href="#customizing_the_notifications_mails">Customizing the notifications mails</a></li> + </ul> + + <li><a href="#see_also">SEE ALSO</a></li> + <li><a href="#author__man_pages_">AUTHOR (man pages)</a></li> + <li><a href="#report_bugs">REPORT BUGS</a></li> + <li><a href="#copyright_and_license">COPYRIGHT and LICENSE</a></li> +</ul> +<!-- INDEX END --> + +<hr /> +<p> +</p> +<h1><a name="name">NAME</a></h1> +<p><em>epgsearch</em> - Searchtimer and replacement of the VDR program menu</p> +<p> +</p> +<hr /> +<h1><a name="overview">OVERVIEW</a></h1> +<p>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.</p> +<p> +</p> +<hr /> +<h1><a name="content">CONTENT</a></h1> +<pre> + 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</pre> +<p> +</p> +<hr /> +<h1><a name="1__using_variables_in_the_directory_entry_of_a_search_timer">1. Using variables in the directory entry of a search timer</a></h1> +<p>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:</p> +<pre> + 1|Category|Kategorie|Information,Kinder,Musik,Serie,Show,Spielfilm,Sport|3</pre> +<p>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:</p> +<pre> + My Movies~%Category% + Childrens Movies~%category% + %CATEGORY%~%genre%</pre> +<p>There are also three other variables: %Title%, %Subtitle% and %Channel%. +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</p> +<pre> + %Category%~%Genre%~%Title%~%Subtitle%</pre> +<p>is the same as</p> +<pre> + %Category%~%Genre% + (with 'serial recording' set to 'yes').</pre> +<p>The %Channel% variable gets replaced with the name of the channel.</p> +<p>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:</p> +<pre> + %Category%~%Genre%~%Title%~%Episode%~%Subtitle%</pre> +<p>There is also another variable %search.query% that will be replaced with the +query of the search timer.</p> +<p>See also <code>epgsearchuservars.conf(5)</code>.</p> +<p> +</p> +<hr /> +<h1><a name="2__the_format_of_epgsearch_conf">2. The format of epgsearch.conf</a></h1> +<p>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 <strong>':'</strong>:</p> +<pre> + 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</pre> +<p>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 ;-))</p> +<p>See also <code>epgsearch.conf(5)</code>.</p> +<p> +</p> +<hr /> +<h1><a name="3__description_of_the_search_process">3. Description of the search process</a></h1> +<p>First, for each broadcasting a search text divided by '~' is created, +depending on the settings of 'Use title', 'Use subtitle' and 'Use +description':</p> +<pre> + title~subtitle~description</pre> +<p>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:</p> +<dl> +<dt><strong><a name="item__2d__27phrase_27_matches">- 'Phrase' matches</a></strong> + +<dd> +<p>if the search term is found anywhere in the search text.</p> +</dd> +</li> +<dt><strong><a name="item__2d__27at_least_one_word_27_2c__27all_words_27">- 'at least one word', 'all words'</a></strong> + +<dd> +<p>first the search term will be split in single words. Delimiters are a +blank and the characters ',' ';' '|' '~'.</p> +</dd> +<dd> +<p>Then we check if at least one or all words appear in the search text.</p> +</dd> +</li> +<dt><strong><a name="item__2d__27match_exactly_27">- 'match exactly'</a></strong> + +<dd> +<p>matches if search term and search text are identical.</p> +</dd> +</li> +<dt><strong><a name="item__2d__27regular_expression_27">- 'regular expression'</a></strong> + +<dd> +<p>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 <em>INSTALL</em>).</p> +</dd> +</li> +</dl> +<p>If the search was successful until now, the other criterions (start +time, duration, week day) are checked.</p> +<p> +</p> +<hr /> +<h1><a name="4__how_do_search_timers_work">4. How do Search Timers work?</a></h1> +<p>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.</p> +<p>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.</p> +<p>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.</p> +<p> +</p> +<hr /> +<h1><a name="5__how_to_trigger_a_search_timer_update">5. How to trigger a search timer update?</a></h1> +<p>the update of search timers runs in its own thread. There are several +ways to trigger it:</p> +<dl> +<dt><strong><a name="item__2d_automatically">- automatically</a></strong> + +<dd> +<p>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).</p> +</dd> +</li> +<dt><strong><a name="item__2d_manually_extern">- manually extern</a></strong> + +<dd> +<p>the thread observes the file '.epgsearchupdate' in the +plugins config directory. When you</p> +</dd> +<dd> +<pre> + touch /path_to_file/.epgsearchupdate</pre> +</dd> +<dd> +<p>this will also trigger an update. So this is a simple solution to +make an update e.g. by a script.</p> +</dd> +</li> +<dt><strong><a name="item__2d_manually_intern">- manually intern</a></strong> + +<dd> +<p>calling actions or pressing '3' in the menu of searches asks also +for an update.</p> +</dd> +</li> +<dt><strong><a name="item__2d_from_other_plugins">- from other plugins</a></strong> + +</dl> +<p>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</p> +<p> +</p> +<hr /> +<h1><a name="6__the_sources_of_the__select_directory__menu">6. The sources of the 'Select directory' menu</a></h1> +<p>This menu displays directories, that can be used for search timers or +ordinary timers. The items displayed are read from the following +sources:</p> +<pre> + * current recording directories + * current timer directories + * directories used in search timers + * directories specified in F<epgsearchdirs.conf>, + see C<epgsearchdirs.con(5)></pre> +<p>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.</p> +<p>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'.</p> +<p> +</p> +<hr /> +<h1><a name="7__language_dependent_commands_for_epg">7. Language dependent commands for EPG</a></h1> +<p>If you like to have a language dependent list of commands simply +translate your present <em>epgsearchcmds.conf</em> to your preferred OSD +language and store it with the filename epgsearchcmds-XXX.conf, where +XXX is the language code from i18n.c:</p> +<pre> + { "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", + }</pre> +<p>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 <em>epgsearchcmds.conf</em>.</p> +<p>See also <code>epgsearchcmds.conf(5)</code>.</p> +<p> +</p> +<hr /> +<h1><a name="8__usage_from_other_plugins_or_scripts">8. Usage from other plugins or scripts</a></h1> +<p>Searching the EPG and other functionality can be used by other plugins +or scripts. There are two approaches:</p> +<p> +</p> +<h2><a name="8_1__filebased__intended_for_use_in_scripts_">8.1. File-based (intended for use in scripts)</a></h2> +<p>Therefore simply create the file '.epgsearchrc' in the plugins config +directory with the following lines in it:</p> +<pre> + 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</pre> +<p>Then call Epgsearch via svdrpsend.pl (you must have assigned a key +to it), e.g.</p> +<pre> + svdrpsend.pl HITK green</pre> +<p>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.</p> +<p>A sample script <em>recrep.sh</em>, that searches for the repeats of a recording +exists in the scripts subdirectory of Epgsearch.</p> +<p> +</p> +<h2><a name="8_2__via_plugininterface__intended_for_use_in_plugins_">8.2. via Plugin-Interface (intended for use in plugins)</a></h2> +<p>A plugin can directly call two functions of epgsearch with only some +lines of source code:</p> +<pre> + - searching the EPG for some criteria and display the result list + - extended timer edit menu</pre> +<p>I have added a quick and dirty dummy plugin +(source/vdr-epgsearchclient-0.0.1.tgz), that demonstrates the usage.</p> +<p> +</p> +<hr /> +<h1><a name="9__svdrp_interface">9. SVDRP interface</a></h1> +<p>epgsearch implements a SVDRP interface, that can be accessed for +example like this</p> +<pre> + svdrpsend.pl PLUG epgsearch LSTS</pre> +<p>the following commands are available:</p> +<p> +</p> +<h2><a name="search_management_">search management:</a></h2> +<pre> + * '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:</pre> +<pre> + 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.</pre> +<p> +</p> +<h2><a name="channel_group_management_">channel group management:</a></h2> +<pre> + * '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</pre> +<p> +</p> +<h2><a name="blacklist_management_">blacklist management:</a></h2> +<pre> + * '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</pre> +<p> +</p> +<h2><a name="search_template_management_">search template management:</a></h2> +<pre> + * '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.</pre> +<p> +</p> +<h2><a name="extended_epg_categories_">extended EPG categories:</a></h2> +<pre> + * '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)</pre> +<p> +</p> +<h2><a name="misc_">misc:</a></h2> +<pre> + * '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</pre> +<p> +</p> +<h2><a name="timer_conflicts_">timer conflicts:</a></h2> +<pre> + * '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:</pre> +<pre> + 1190232780:152|30|50#152#45:45|10|50#152#45</pre> +<pre> + '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:</pre> +<pre> + '152|30|50#152#45' is the description of the first conflicting timer. Here:</pre> +<pre> + '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</pre> +<pre> + '45|10|50#152#45' describes the next conflict</pre> +<p> +</p> +<hr /> +<h1><a name="10__customizing_the_epg_menus">10. Customizing the EPG menus</a></h1> +<p>The file <em>epgsearchmenu.conf</em> 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:</p> +<pre> + 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</pre> +<p>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.</p> +<p>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.</p> +<p>'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</p> +<pre> + MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35</pre> +<p>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.</p> +<p>The following variables exist:</p> +<pre> + %time% - start time in format HH:MM + %timeend% - end time in format HH:MM + %date% - start date in format TT.MM.YY + %datesh% - start date in format TT.MM. + %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 + %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%'</pre> +<pre> + %<epg-category>% - a value from the extended EPG categories, specified in + epgsearchcats.conf, like %genre% or %category%</pre> +<p>for the 'Whats on...' and 'Search results' menu there are also:</p> +<pre> + %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') + %progrT2S% - progress bar in text2skin style (not for menu 'Search results')</pre> +<p>some indepent variables:</p> +<pre> + %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 + %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)</pre> +<p>The variables are not case sensitive. You can also use variables for extended +EPG categories defined in <em>epgsearchcats.conf</em> or use your own user defined +variables defined in <em>epgsearchuservars.conf</em></p> +<p>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 ':'.</p> +<p>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.</p> +<p>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.</p> +<p>There's a sample <em>epgsearchmenu.conf</em> in the subdirectory ``conf''. For a quick try +copy it to your plugins config directory (e.g. /etc/vdr/plugins).</p> +<p>To enable icons from WarEagleIcon-Patch simply put the line</p> +<pre> + WarEagleIcons=1</pre> +<p>to <em>epgsearchmenu.conf</em>.</p> +<p>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.</p> +<p>See also <code>epgsearchmenu.con(5)</code>.</p> +<p> +</p> +<hr /> +<h1><a name="11__working_with_the_timer_conflict_menu">11. Working with the timer conflict menu</a></h1> +<p>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'.</p> +<p>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.</p> +<p>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.</p> +<p>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</p> +<pre> + - 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</pre> +<p>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.</p> +<p>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.</p> +<p> +</p> +<hr /> +<h1><a name="12__user_defined_variables">12. User defined variables</a></h1> +<p>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 <em>epgsearchuservars.conf</em>.</p> +<p>Variables looks like %Variablename%.</p> +<p>``Variablename'' can be consist of any alphanumerical character. Space +and special characters are not allowed.</p> +<p>The variable names are case-insensitive.</p> +<p>Examples for possible names:</p> +<pre> + %Series% %DocuVar1% %ThemesSubtitleDate1%</pre> +<p> +</p> +<h2><a name="assignment">Assignment</a></h2> +<pre> + %Series%=New series~Thriller</pre> +<p>The variable %Series% will be assigned with the string ``New series~Thriller''.</p> +<p>Assignments are always strings. Spaces stay spaces.</p> +<pre> + %Path%=%Series%</pre> +<p>The variable %Path% gets the content of the variable %Series%.</p> +<p>You can do nearly everything:</p> +<pre> + %Path%=%Serie%~Lost</pre> +<p>The variable %Path% contains now the string ``New series~Thriller~Lost''.</p> +<p> +</p> +<h2><a name="control_structures">Control structures</a></h2> +<p>You can use simple ``if then else'' constructions.</p> +<p>These constructions cannot contain strings, only variables. +Spaces are ignored.</p> +<pre> + %Foo%=Other</pre> +<pre> + %Variable%=%Path% ? %Path% : %Foo%</pre> +<p>If %Path% is not empty, assign the content of %Path% to %Variable%, +otherwise the content of %Foo%.</p> +<p>``%Path% ?'' means ``not empty?''. You can use other checks.</p> +<pre> + %Variable%=%Path%!=5 ? %Path% : %Foo%</pre> +<p>``%Path%!=5 ?'' means ``is %Path% equal 5?''</p> +<p>You can also compare variables.</p> +<pre> + %Five%=5</pre> +<pre> + %Variable%=%Path%!=%Five% ? %Path% : %Foo%</pre> +<p>Other possible checks:</p> +<pre> + == equal + != not equal</pre> +<p> +</p> +<h2><a name="calling_a_system_command">Calling a system command</a></h2> +<p>You can call external commands. The returned string will be assigned +to a variable</p> +<pre> + %uservar%=system(scriptname[, parameters])</pre> +<p>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.</p> +<p>Sample:</p> +<pre> + %myVar%=system(/usr/local/bin/myscript.sh, -t %title% -s %subtitle% -u %myOtherVar%) + +The script must return a string B<without> line break!</pre> +<p>If the script returns nothing, an empty string will be assigned to the +Variable %Result%.</p> +<p> +</p> +<h2><a name="possible_variables">Possible variables</a></h2> +<p>for a list of already builtin variables refer to the section ``Customizing the EPG menus'' +Furthermore you can use every variable defined in <em>epgsearchcats.conf</em>.</p> +<p>See <code>epgsearchcats.conf(5)</code>.</p> +<p> +</p> +<h2><a name="examples">EXAMPLES</a></h2> +<pre> + # Weekday, Date, Time + %DateStr%=%time_w% %date% %time%</pre> +<pre> + # Themes or Subtitle or Date + %ThemesSubtitleDate1%=%Subtitle% ? %Subtitle% : %DateStr% + %ThemesSubtitleDate%=%Themes% ? %Themes% : %ThemesSubtitleDate1%</pre> +<pre> + # 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%</pre> +<p> +</p> +<hr /> +<h1><a name="13__email_notification">13. Email notification</a></h1> +<p>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</p> +<pre> + - epgsearchupdmail.templ (for search timer update notifications) + - epgsearchconflmail.templ (for timer conflict notifications)</pre> +<p>You can find sample files in the 'conf' directory. Copy them to epgsearchs +config directory (e.g. /etc/vdr/plugins/epgsearch).</p> +<p> +</p> +<h2><a name="customizing_the_notifications_mails">Customizing the notifications mails</a></h2> +<p>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:</p> +<pre> + - "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% and %update.deltimers% for the + list of changed or deleted timers. + - "timer" the description of one timer. This section is used to display one + timer within a timer list, e.g. in %update.newtimers%</pre> +<p>each section is enclosed in a pseudo XML tag.</p> +<p>The following variables can be used in the section <mailbody>:</p> +<pre> + - %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 + - %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</pre> +<p>The following variables can be used in the section <timer>:</p> +<pre> + - %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 + - 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')</pre> +<p>For a conflict notification mail the following sections exist:</p> +<pre> + - "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</pre> +<p>The following variables can be used in the section <mailbody>:</p> +<pre> + - %conflict.count% - complete number of timer conflicts + - %conflict.conflicts% - list of times with conflicting timers</pre> +<p>The following variables can be used in the section <conflictsat>:</p> +<pre> + - %conflict.date% - date of the conflict + - %conflict.time% - time of the conflict + - %conflict.confltimers% - list of conflicting timers for this time</pre> +<p>The section <conflicttimer> can use the same variables as the section <timer> +in an update mail (see above).</p> +<p> +</p> +<hr /> +<h1><a name="see_also">SEE ALSO</a></h1> +<p><code>epgsearch(1)</code>, <code>epgsearch.conf(5)</code>, <code>epgsearchuservars.con(5)</code>, <code>epgsearchdirs.conf(5)</code>, <code>epgsearchmenu.conf(5)</code>, <code>epgsearchcmds.conf(5)</code></p> +<p> +</p> +<hr /> +<h1><a name="author__man_pages_">AUTHOR (man pages)</a></h1> +<p>Mike Constabel <epgsearch (at) constabel (dot) net></p> +<p> +</p> +<hr /> +<h1><a name="report_bugs">REPORT BUGS</a></h1> +<p>Bug reports (german):</p> +<p><a href="http://www.vdr-developer.org/mantisbt/">http://www.vdr-developer.org/mantisbt/</a></p> +<p>Mailing list:</p> +<p><a href="http://www.vdr-developer.org/mailman/listinfo/epgsearch">http://www.vdr-developer.org/mailman/listinfo/epgsearch</a></p> +<p> +</p> +<hr /> +<h1><a name="copyright_and_license">COPYRIGHT and LICENSE</a></h1> +<p>Copyright (C) 2004-2007 Christian Wieninger</p> +<p>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.</p> +<p>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.</p> +<p>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 <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">http://www.gnu.org/licenses/old-licenses/gpl-2.0.html</a></p> +<p>The author can be reached at <a href="mailto:cwieninger@gmx.de">cwieninger@gmx.de</a></p> +<p>The project's page is at <a href="http://winni.vdr-developer.org/epgsearch">http://winni.vdr-developer.org/epgsearch</a></p> +<p>The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.</p> + +</body> + +</html> |