=encoding utf8

=head1 NAME

F<epgsearchcats.conf> – extended EPG information

=head1 DESCRIPTION

Some EPG providers deliver supplemental EPG information, like the kind of
event, the video and audio format, cast, etc. in the content summary.
Using tools like F<tvmovie2vdr> or F<epg4vdr>, EPG content like this
can be imported into the VDR.

Such information allows, for instance, creating a search for finding
all tips of the day broadcasted in 16:9 format quite easily.
For this purpose, EPGSearch scans the summary of an event for lines
starting with the names of categories, followed by C<:> and a space,
that have one or more values set in the search timer. The search is
case-sensitive for both the category name and its values.

To use this kind of information in search timers, appropriate settings
must have been made in the file F<epgsearchcats.conf> in the EPGSearch
configuration directory.
Sample files for F<epgsearchcats.conf> can be found in the directory
F<conf> of EPGSearch. Quite often, copying the one that fits best
as F<epgsearchcats.conf> to the EPGSearch configuration directory and
making some minor adjustments might be sufficient. Then just restart
the VDR and open a search timer's edit menu for making use of the
EPG categories.

Since setting up a new F<epgsearchcats.conf> is quite a lot of work,
EPGSearch comes with the small tool F<createcats> that does the
biggest part of the job. It should have been installed to the directory
of the VDR.
See B<createcats>(1) for information about how to use it.

=head1 SYNTAX

Lines within this file have the following format:

=over 4

    ID|category name[,format]|name in menu|values|search mode

=back

A line's fields have the following meaning:

=over 4

=item B<1 – Unique identifier (ID)>

Integer with a positive value.

B<Caution:> Changing the identifier later on will require
updating the search timers!

=item B<2 – Category name>

String with the EPG category's name as delivered by the EPG
provider, like C<Genre>.

If an optional C<format> is supplied, the category value will be
interpreted as integer and formatted as specified by the format
string (see C<man printf> for applicable format strings).

=item B<3 – Name in menus>

String with the EPG category's name for display in EPGSearch menus.

=item B<4 – Values>

String with an optional, comma-separated list of values for the
EPG category.

=item B<5 – Search mode>

Optional enumeration with the following values:

=over 4

B<Textual comparison:>

=over 4

=item 0 = the whole term must appear as substring

=item 1 = all single terms (delimited by one of C<,;|~>)
must exist as substrings; this is the default search mode

=item 2 = at least one term (delimited by one of C<,;|~>)
must exist as substring

=item 3 = exact match

=item 4 = regular expression

=back

B<Numerical comparison:>

=over 4

=item 10 = less

=item 11 = less or equal

=item 12 = greater

=item 13 = greater or equal

=item 14 = equal

=item 15 = not equal

=back

=back

=back

=head1 EXAMPLE

=over 4

  1|Category|Kind|Information,Children,Music,Series,Show,Movie,Sports|2
  2|Genre|Genre|Adventure,Action,Business,Science,Cartoon|2
  3|Format|Video format|16:9,4:3|2
  4|Audio|Audio format|Dolby Surround,Dolby,Stereo|2
  5|Year|Release year||2
  6|Cast|Cast||2
  7|Director|Director||2
  8|Presenter|Presenter||2
  9|Rating|Rating|Excellent,Great,Average,Acceptable,Poor|2
  10|Age|Age|6,12,16,18|2
  11|Country|Country||2
  12|Themes|Themes||4
  13|Season,%02i|Season||14
  14|Season,%02i|Season from||13
  15|Episode,%02i|Episode||14

=back

Identifiers 13 and 14 refer to the same EPG category, but provide distinct
menu names for different search modes. As the evaluation sequence is not
guaranteed, their formats should be identical to avoid unexpected results
when referencing the category's variable.

=head1 AUTHORS (man pages)

Originally provided by Mike Constabel <epgsearch (at) constabel (dot) net>.

Revised and adapted to recent plugin features by the current maintainers.

=head1 PROJECT SITE

The plugin is maintained as GitHub project:

L<https://github.com/vdr-projects/vdr-plugin-epgsearch/>

=head1 REPORTING BUGS

Issues can be reported, and features be suggested, through the project's
bug tracker:

L<https://github.com/vdr-projects/vdr-plugin-epgsearch/issues/>

=head1 COPYRIGHT and LICENSE

Copyright (C) 2004-2010 Christian Wieninger

Copyright © 2011-2025 TomJoad (VDR-Portal), et al.

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 L<https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

The original author can be reached via L<cwieninger@gmx.de>.

Current maintainers can be reached via the project's GitHub site (see above).

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

=head1 SEE ALSO

B<epgsearch>(1), B<createcats>(1), B<epgsearchcats.conf>(5)
