# ---------------------------------------------------------------------------
#
#  Nextview decoder online manual
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License Version 2 as
#  published by the Free Software Foundation. You find a copy of this
#  license in the file COPYRIGHT in the root directory of this release.
#
#  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.
#
#
#  Description:
#
#    User's documentation in Perl "POD" format. The content is
#    converted into various other formats by use of different scripts:
#    UNIX manpage by pod2man; HTML web page by pod2html (needs manual
#    adjustments) and the online help by a self-made script. The releases
#    should contain the converted files, so that the user is not forced
#    to install Perl.
#
#  Author: Tom Zoerner
#
# $Id: nxtvepg.pod,v 1.78 2002/10/13 14:12:32 tom Exp tom $
# ---------------------------------------------------------------------------

=head1 NAME

nxtvepg - Decoder, Browser and Analyzer for the Nextview Electronic Programme Guide

=head1 SYNOPSIS

B<nxtvepg> S<[ options ]> S<[ database ]>

=head1 DESCRIPTION

B<nxtvepg>
is an X11 and Win32API application to decode, analyze and browse TV programme
schedules transmitted on analog TV channels as defined in ETS 300 707:
"Protocol for a TV Guide using electronic data transmission" by the
European Telecommunications Standards Institute.

The Nextview standard was developed for use in TV sets, but the data can be
received and used in a PC, too - provided you have a Teletext capable TV tuner
card and are lucky enough to have a Nextview content provider in your country.

B<nxtvepg>
enables you to obtain free TV programme listings for all of the major
networks in Germany, Austria, France and Switzerland. Currently
Nextview EPG is transmitted by the following TV networks (note that each
of these EPGs cover not only the provider's programme but also that of
many other networks):

=over 4

=item *

In Germany and Austria: Kabel1, 3Sat, RTL-II.

=item *

In Switzerland: SF1, TSR1, TSI1, EuroNews.

=item *

In France: Canal+, M6.

=item *

In Turkey: TRT-1

=back

For up-to-date information check the nxtvepg homepage in the Internet
(see the About popup in the Help menu). If you don't receive any of the
channels listed above, you can only use the demo mode as described
with the B<-demo> command line option.

=head1 OPTIONS

Summary of command line options:

=over 4

=item B<-display> I<display>

UNIX only: The display on which the windows will be created.
Default: taken from environment variable DISPLAY.

=item B<-geometry> I<geometry>

Specifies the position of the main window, e.g.  B<-geometry -0+0>
to put the main window in the upper right corner of the visible screen.
The size of the window cannot be changed.

=item B<-iconic>

Start with the main window iconified (i.e. minimized).

For M$ Windows users this option may be esp. helpful when nxtvepg is
started from inside the I<Auto start> group and I<Hide on minimize> is
enabled: nxtvepg then will start almost invisibly in the background,
only with an icon in the system tray of the task bar.

=item B<-rcfile> I<path>

Specify an alternate configuration file.
Default: on UNIX $HOME/.nxtvepgrc,
on Windows nxtvepg.ini in the current directory.

=item B<-dbdir> I<directory>

Specify an alternate directory for the databases.
Default: On UNIX /usr/tmp/nxtvdb, on Windows the current directory.
Note that the database management is not equipped for concurrent writing,
so if you have more than one TV tuner card in your system or network,
relocate the directory into the users' homes.

If you're using an acquisition daemon, the browser must be configured
to use the same directory as the daemon.  If the daemon is running on
a different host, you need to mount the remote directory, e.g. via NFS.

=item B<-card> I<index>

Specify which TV card hardware to use, if you have more than card.
Default: index 0.
On Linux the given index is appended to the device names,
i.e. F</dev/vbi> and F</dev/video>.
On Windows index "n" means the n-th card found while scanning the PCI
bus for cards with a Bt878, Bt878A, Bt848 or Bt849 chip.  If you have more
than one TV card with the same chip, the order between those is undefined,
but still constant (i.e. the order is determined by the driver, not nxtvepg)

=item B<-provider> I<CNI>

Select a provider by its hexadecimal CNI (Country and Network Identifier),
e.g. I<-provider dc7> for B<3sat>. You can find out the provider's CNI
during a provider scan or from the database file names.
Default: the last provider selected during the previous session.

=item B<-noacq>

Start with acquisition disabled.
The acquisition can still be started later from the Control menu.

=item B<-daemon>

Start without the graphical user interface. The process will detach
from the terminal (i.e. create an invisible window on M$ Windows) and
perform background acquisition. If no other
options are given the same provider and acquisition mode as configured with
the GUI will be used. If the -provider option is given acquisition will work
for this provider only (note the difference to non-daemon mode, where that
option selects the browser database). The -daemon option cannot be combined
with the -noacq or -demo options.

The daemon always creates a named socket in the I</tmp> directory (UNIX only)
plus optionally a TCP/IP socket to allow connects by browser processes. While
connected, the browser receives updates for opened Nextview databases and
reports about the acquisition progress; if left unconnected, the browser
listing might be incomplete or outdated.

It's important to note that the browser B<must use> the same I<-dbdir>
directory, because the daemon forwards only deltas to the database files
stored in that directory. For more details see
L<"CONFIGURATION: Client/Server">.

UNIX
Warning: for security reasons it's depreciated to run the daemon with root
privileges, because nxtvepg has not been reviewed yet for possible exploits.
If you want to start the daemon already during system startup, you should
use su(1). Also note that you'll probably need to specify -rcfile because
the $HOME environment variable  might not be (correctly) defined.  Example:

   su nobody -c "/usr/local/bin/nxtvepg -daemon \
                 -rcfile /usr/local/etc/nxtvepgrc"

The only way to stop the daemon is to send it a signal, i.e. kill it with
SIGTERM. For more details see L<"CONTROL"> and L<"FILES">.


=item B<-nodetach>

UNIX only:
In daemon mode this option prevents the process actually making itself a
daemon, i.e. it doesn't fork and stays connected to the terminal. Also
all log messages starting with level
.I warning
are sent to standard error out (e.g. configuration errors that lead to
an immediate exit).  This mode is intended for debugging purposes only.

=item B<-acqpassive>

In daemon mode this option overrides the acquisition mode setting in the
configuration file and forces the acquisition into passive mode (see
L<"ACQUISITION MODES">).  The configuration file is not changed, so that
you can use different acquisition strategies for daemon and GUI.

=item B<-dump> I<mode>

With this argument, nxtvepg will only export the database in a fixed text
format (see also L<"CONFIGURATION: Export as text">), then exit.
This argument must be combined with I<-provider> to specify which database
is to be exported. Use the code B<0x00FF> to export the merged database
(in the last used configuration as saved in the rc/ini file).

Three mode keywords are understood:
I<pi> to dump programmes (i.e. the complete schedules),
I<ai> to dump the provider's network table,
I<pdc> to dump the PDC theme table.

The output is written to I<stdout> unless you redirect it into a file
or pipe it into another program.  Note to Windows users: since nxtvepg
is not a console application, no I<stdout> is available, i.e. it's output
will be discarded by the operating system unless you redirect it.
For example you could enter the following command in the shell
(or "MS-DOS prompt"):

  nxtvepg -dump ai -prov dc7 > networks.txt

to write the network table of provider I<3sat> (CNI I<0xdc7>) into a file
called I<networks.txt>.


=item B<-demo> I<path>

Load database given by I<path>
and enter demo mode. In this mode all entries of the database are shifted
into the presence, i.e. just far enough so that none expire. Hence the
entries' dates and times are not for real and acquisition or database
reselection is not possible.

=item B<-help>

List all available command line options.

=back

After the options you can add a database filename. This is equivalent
to specifying B<-dbdir> and B<-provider>. The provider CNI is taken
from the file name. If the file name does not have the format as
defined in L<"FILES">, it's assumed to be a demo database and loaded
just as with the B<-demo> option. The database filename argument
silently overrides any previously given options.

This is particularily useful for users of graphical file managers
(like the Windows Explorer) who can just drag and drop a database file
onto the executable. When used on Windows systems the working
directory is set to the one that contains the executable, because
the Explorer seems to set it to the user's desktop root, so that none
of the DLLs and drivers are found.

Note to Windows users: all these options - unless otherwise noted -
are available in the Win32 version too. You can supply the options
either from a "MS-DOS" command prompt or batch file, or by appending
them to the executable in a shortcut definition.



=head1 GETTING STARTED

Before you can start reading in TV programme schedules (called
I<acquisition>
from here on), you have to do just a few configurations. Which
ones depends on your setup and will be described in this chapter.
As long as your browser window contains no data, there's also a
recommondation how to get to data in the browser window,
highlighted by a yellow background.

This manual describes all features of nxtvepg in detail. You
do not have to read all of it at once to operate the software.
However it's recommended to skim at least through L<"BASIC BROWSING">,
L<"DATA ACQUISITION"> and L<"FILTERING">.


=head2 TV card Setup on M$ Windows

Windows users first have to configure the driver for their TV card
in the 'TV card input' dialog from the Configure menu (for more
in-depth information see also L<"CONFIGURATION: TV card input">).
UNIX users can skip this section.

The easiest way is to copy the values of your favorite TV application.
nxtvepg can read the INI files or registry of the following freeware
programs: DScaler, K!TV, MultiDec, MoreTV, FreeTV. After selecting a
TV app in the drop-down menu, you need to specify the directory where
the software is installed in the entry field below (i.e. the directory
which contains the I<.INI> file, except for MoreTV and FreeTV which use
the central Windows registry to store their parameters); click the folder
icon on the right to get a browser window for directory selection.

Finally press the I<Load config> button.  If loading succeeds, the three
parameters in the middle box of the dialog window have been set,
i.e. input source, tuner type and PLL initialization.  Note that the
TV application type and directory configured here are also used by the
EPG scan and the network name dialog to obtain a channel table.

If nxtvepg cannot load your TV app's configuration, you should open your
TV app's card configuration dialog and look up the tuner and PLL settings
used there, and then set them manually in nxtvepg.  Otherwise the only
way to figure out which tuner your card is using is to open your PC case
and search for a label on the metal tuner box on the TV card, or try all
the tuners in nxtvepg's list. 

Some hints for figuring out your settings: if you live in Germany,
Austria or Switzerland you probably have a PAL tuner, in France it's
one of the SECAM types. (If you select the wrong tuner, you can have
either no reception at all or no reception just on a few channels.)
The correct value for I<PLL initialization> with PAL and SECAM cards
is either I<No init> or I<28 MHz>. (If you select the wrong value
you have no reception at all.)

If you're not sure about your configuration, start with the topmost and
then try them one after each other and start an EPG scan inbetween (see
below) to
check if the tuner works.  If you have one of the TV applications listed
above make sure to keep the I<Use TV app freq.> button enabled; this way
only well known channels are visited, and you can monitor in the output
window if there is reception on these channels (however only networks
which transmit VPS/PDC can be identified with their network name).

If you have problems see F<README> for more details and a
list of error messages from the Windows driver.


=head2 Video input configuration

Before nxtvepg can start acquiring EPG data, it must be told if the
video feed is provided by your TV card's internal TV tuner (if you're
connected to your city's TV cable network or a terrestrial antenna)
or an external source (usually satellite receivers connected via
Composite or S-Video cable).  This can be configured in the
I<TV card input> dialog in the Configure menu
(for more in-depth information see also L<"CONFIGURATION: TV card input">).

By default nxtvepg assumes input via TV tuner.  This is the preferred
mode of operation, since nxtvepg can change channels between multiple
Nextview providers, while with an external source you have to switch
channels manually (see also L<"DATA ACQUISITION">).  If you're living in
France you should tell nxtvepg to use the French channel table (which
implies using the Secam TV norm instead of PAL B/G/I); this information
is required for the next step: the EPG scan.

If you cannot use the TV tuner but have instead connected a satellite
receiver through the Composite or S-Video input, select the respective
setting in the I<video input> drop-down menu.  Then close the dialog with
Ok and open the aquisition mode configuration dialog from the same menu.
There you should change to the I<external> mode: in this mode nxtvepg
will switch to the configured video input channel during startup of
acquisition, but afterwards expect you to tune in a Nextview provider's
channel at the external video source. To load all provider's inventories
in the way the EPG scan does, you have to tune in all provider channels
(for a list see the intro of this manual or the Internet homepage) and
wait until the status line changes from "starting up" to "working on".

Note that you can also connect your satellite receiver via antenna cable.
However this  variant is highly depreciated, because the signal is often
degraded so much that nxtvepg is not able to decode the EPG data stream
any more.  But if you still want to go that route, you'd keep the tuner
as input source and start an EPG scan to find the channel your receiver
is transmitting its signal on.  Make sure to disable the I<Use .xawtv>
option in the provider scan dialog, unless your satellite receiver's
channel (i.e. the frequency onto which the satellite signal is modulated)
is defined as an input channel in xawtv.  Before you start the EPG scan
you need to tune in a Nextview provider's channel.  The scan will only
find that one provider. If you want to load all providers you have to
continue manually as described above.  For an acquisition mode it's
recommended to stay with I<Follow browser database>. Although nxtvepg
will not be able to actually "follow" your provider selection with the
acquisition since it can't switch the TV channel at your external input,
this mode will tell nxtvepg to set the TV tuner onto your receiver's
channel (see also L<"ACQUISITION MODES"> for more details.)


=head2 EPG scan: Search for Nextview providers

This section only applies if you chose to use your TV card's internal
tuner.  In this case the next step to get started is to run a provider
scan from the Configure menu.  During the scan all TV channels are
checked for Nextview transmissions and a list of Nextview providers
is built from the result.

You can speed up the scan by using a TV application's channel table;
in this case the scan is limited to TV frequencies defined in the
TV app's channel table. This mode is enabled with the
I<Use TV app freq. table> checkbutton. It's checked by default if
you have loaded your TV card parameters from a TV application's INI
file.  If you want to load the channel table from a different application
use the I<TV app. interaction> dialog described in the next chapter.

At the end of the scan there's a short summary which tells you how many
providers have been found.  If there were any, you can close the dialog
window and open the provider selection dialog from the Configure menu
and select you favorite one.  Then wait a little while the provider's
TV channel is tuned and data being loaded.

If the provider scan does not find any or not all Nextview provider channels
(possibly due to weak reception - this is a very simple scan that does
not attempt any fine-tuning) enable the I<Slow> button and try again.
If this does not help, you can still add the missing providers manually.
set the acquisition mode to I<external> or I<passive> (UNIX only). Then
use an external application to tune the channel (Windows users have to
stop acquisition first; then start the TV application; then tune the
channel; then quit the other application; finally start acquisition again).

In external mode nxtvepg will not touch the tuner and wait infinitly for
Nextview reception on the current channel.  On Windows (and Linux with
bttv drivers version 0.7.50 and earlier) this method has the disadvantage
that no channel number or frequency will be known for this provider so you
have to tune the provider's channel manually whenever you start acquisition.


Acquisition of a complete database takes about 20 minutes. However
programmes that are nearer in the future are available much faster,
since they are transmitted more often. The currently running and
directly following programmes of all networks are usually available
after about 2-3 minutes max.


=head2 Configuring a TV application

nxtvepg can cooperate in three ways with TV applications:

=over 4

=item *

Windows only: loading TV card parameters to simplify the
initial configuration (already described above).

=item *

Loading the TV application's channel table: use of the TV tuner frequencies
can significantly speed up the EPG scan (already mentioned above);
the channel names are used by the  I<Network name> dialog in the
Configure menu (see L<"CONFIGURATION: Network names">) to synchronize
network names between nxtvepg and the TV application.

=item *

Interaction between nxtvepg and the TV application, to provide you
with convenience features like an on-screen display of the current
programme title after channel changes, changing the channel from
inside nxtvepg with the I<TuneTV> button, and background Nextview
data acquisition while you're watching TV.

=back 4

The first two are passive features, i.e. only nxtvepg needs to be
adapted to the respective TV applications.  The third one however
requires cooperation of both sides.  For this reason the number
of TV applications for which the passive features are supported
will always be much larger.  On Windows the interaction features
are still under development and currently only supported by a
developer's version of K!TV.

On UNIX only I<xawtv> is supported currently.  With xawtv all
the features listed above are supported.

On Windows several freeware TV applications are supported for the
passive features; you must select which one you're using.
If you've loaded TV card settings from
a TV app in the I<TV card input> dialog, then the TV app type and path
is already configured.  Else, or if you want to use a different app as
source for the channel table, open the I<TV app. interaction> dialog
(see also L<"CONFIGURATION: TV application interaction">).

Regarding the third, the active feature:
You can check if nxtvepg is able to interact with a specific TV application
by starting both, and then opening the TV application interaction
dialog in  the Configure menu. In the middle of the dialog window the
connection status is indicated.  In most cases however unsupported TV
application will already fail to start with a message like "TV card
already in use" or "Couldn't load Bt8x8 driver". Only with cooperating
TV apps nxtvepg is able to automatically free the card when the TV app
is started (TV viewing is always given priority over EPG data acquisition.)

After setting up the TV app type and path, you should open the
I<Network name> configuration dialog to synchronize
network names between nxtvepg and the TV app.  Even if interaction is not
possible, it may still be a good idea to have the same network names in
both applications.  See L<"CONFIGURATION: Network names"> for details.



=head1 BASIC BROWSING

The browser mainly consists of two windows: the upper one contains
a list of programme titles, sorted by start time. All currently running
programmes (or rather: all programmes that should be running according
to their start time) are marked by a light blue background color.
One line in the list is selected by a cursor; the lower window contains
the attributes and description for this selected title. The amount of
information available here depends entirely on the content provider.

The basic browsing of programme information works very straight-forward.
You can either use the mouse or the keyboard cursor keys:

With the mouse, you can click on any title to select it and display its
description in the lower window. With a double-click you open a popup
window with a summary of all attributes known for that title.  See
L<"FILTERING"> on how to use those for filtering. Use the scrollbar
to scroll the listing forward to programmes farer in the future.

With the keyboard, use the Cursor up/down keys to select any title.
For fast scrolling use the page up/down keys. With the Home key you
always get back to the first title. With TAB and SHIFT-TAB you can
move the keyboard input focus to other widgets, e.g. to the network
and shortcut lists; to apply a selected theme or shortcut as filter
press the Space or Return key. The first 10 shortcuts can also be
enabled directly from the main window with the digit keys 1-9 and 0.
Control-C in the main window opens the context menu; Control-F opens
the text search dialog; the Escape key is equivalent to the Reset
button.  The menus can be accessed by pressing the ALT key together
with the underlined character in the respective menu button.

When you resize the main window vertically the difference in height
will be added to the info text window at the bottom.  You can adjust
the proportions between program listbox and the info text with the
"panning" button inbetween, i.e. by dragging the button you can
resize the program listbox.

nxtvepg can interact with TV applications (e.g. I<xawtv> on UNIX;
requires initial setup, see L<"GETTING STARTED">) to provide a connection
in both directions: Firstly you'll find a
I<Tune-TV> button in the main window below the clock. When you press
it, the network of the currently selected programme will be tuned in the
TV application.  With the right mouse button you can also pop up a small
menu which offers basic TV controls. Secondly, when you change the channel
in the TV application, the cursor in the nxtvepg main window will
automatically jump onto the programme currently running on that network.
For more details see L<"CONFIGURATION: TV application interaction">

At the bottom of the window there is a status line which informs you
about the state of the browser database and background acquisition.
It's basically a very dense summary of the B<Statistics> popups from
the B<Control> menu and is especially useful to warn you about the
database age or stalled acquisition.

I<Note:>
For most providers it holds true that programme content descriptions
(i.e. the texts in the lower nxtvepg window) are available only for
currently running programmes and those whose start time is very close.
This time span for full coverage can be as short as 2 hours, or 3 titles
per network. As a consequence you should enable data acquisition as
often as possible; consider running the acquisition daemon permanently
in the background. For details on the acquisition process see the following
chapter.



=head1 DATA ACQUISITION

As long as acquisition is enabled, programme titles are constantly being
acquired or updated in the background. You will notice that all incoming
programme information is instantly inserted to the programme listing.
Every effort is taken to not alter the cursor position or title selection,
except if the cursor is on the very first item - then the cursor
stays on top.

By default, the acquisition always works for the provider whose database
you have loaded into the browser. Therefore, upon program start or whenever
you switch providers, the TV tuner is set onto the frequency of the
provider's TV channel.  Please note that this mode is only possible after
a provider scan, because that's the only way to find out the frequencies.
Check out L<"ACQUISITION MODES"> for more sophisticated acquisition
strategies.

If you do not choose the TV tuner as input (e.g. if you choose an external
source via the Composite or S-Video input sockets), or if the TV tuner is
kept busy by another application (UNIX only, e.g. if you watch TV) data is
still being acquired, but it's no longer possible to automatically change
the TV channel. Hence you are resposible for selecting the channel of the
provider who's database you want to load or refresh. If a transmission
belonging to a different provider than the one selected in the browser
is detected, a second database is automatically opened in the background
to store the incoming data.

The transmitted database is constantly in change: Elapsed titles are
removed, new titles appended, and the titles closest to the current time
updated with an increased amount of description. (The reason that the
complete description is not transmitted for all titles is simply that
the size of the database has to be reduced - it shall be transmitted
in 20 minutes maximum.)  So you should start the acquisition as often
as possible, about every 2-3 hours, at least a couple of minutes before
you browse.

You can monitor the progress of acquisition with the timescale and
database statistics windows from the Control menu. See L<"STATISTICS">
for details.



=head1 ACQUISITION MODES

The acquisition mode configuration dialog enables you to control for which providers
data is collected, and in which order. It's mainly intended for users who use
more than one provider's database, i.e. in a merged database, or want to
optimize startup time. If you're happy with a single provider or don't
want to browse immediately after program start, you should keep the
default, which is loading data always for the provider selected in the
browser.

=over 4

=item B<Passive>

UNIX only:
In this mode the software never accesses the video device and never changes
the input channel or tuner frequency.  It's useful if you want to set up the
source with command line tools like I<v4lctl>. If you're using applications
which keep the video device busy (e.g. a TV application) you don't need this
mode, because when nxtvepg detects an unsolicited channel change, it
automatically switches to the passive mode for as long as the video device
remains busy.

Please note: when nxtvepg does not control the input channel, it can not
automatically take care of updating your databases. Even if the browser
database should be completely empty, no data will appear until you tune in
the provider's channel manually with an external application. Because of
this, passive mode is depreciated.

=item B<External>

This is the recommended mode for Composite or S-Video input sources. Only
the input source will be set; the tuner is not touched. Hence the provider
channel has to be selected either externally (e.g. in a satellite receiver
connected to the Composite or S-Video input sockets) or by a different
application (e.g. TV application, UNIX only), just like in passive mode.

On Windows systems this mode can be used if your tuner is not known to
nxtvepg, i.e. if the EPG scan does not find any channels with all of the
available tuner types. In this case tune in the provider channel with a
TV application; then quit this application and start nxtvepg. When you
view the acquisition statistics from the Control menu, the VPS/PDC code
of the tuned channel should appear in the lower half of the window.

=item B<Follow-UI>

This is the default mode: the acquisition always works for the provider you
have selected for the browser (i.e. user interface). If you change the
provider in the browser window, acquisition follows by tuning the new channel.
Of course this requires to have performed an EPG scan at least once, so that
the tuner frequencies of all providers are known. When you use a merged
database in the browser, acquisition works on each of the merged providers,
one after another, just like in the mode described next.

=item B<Manually selected>

This mode enables you to manually select for which providers the acquisition
should work. If you select more than one provider, they are loaded one after
another, in your specified order. Warning: if you choose a provider for the
browser that's not on the list, no data will be loaded into the browser,
even if it's completely empty.

Since transmission errors have to be considered, it's not attempted
to load every single block of a provider before acquisitions switches to the
next. Instead a statistical criterium was defined, that regards the variance
in coverage of all networks contained in the database, and the slope of that
variance.

=item B<Cyclic: Now - Near - All>

Like the previous mode, this one enables you to specify a list of providers
to load data for. However they are not just loaded completely one after another.
Instead, a 3-staged round-robin is implemented. In the first stage, only
I<Now>
data is loaded, i.e. the currently running and next 2-3 programmes. When
this has been completed for all providers, the next stage begins, which loads
I<Near>
data, i.e. all programmes running in the next 12-24 hours. When that was
completed, the final stage loads the outstanding blocks for all providers.
See below for an explanation what this mode is good for.

=item B<Cyclic: Now - All>

This is the same as the previous mode, except that the
I<Near> stage is skipped.

=item B<Cyclic: Near - All>

This is the same as the mode before the previous one, except that the
I<Now> stage is skipped.

=back

Which mode is best for you depends on how you use the browser. As said
above, if you're mainly using a single provider, stick with the Follow-UI
mode. If you use a merged database, data is automatically loaded for all
contained providers. However if you switch manually between multiple
providers, you should choose one of the manual acquisition modes.

The Cyclic modes enables you to optimize startup time. While in standard
manual mode, the first database is loaded completely before the next one
is started, in Cyclic modes you can specify to load only Now data of all
providers first. Hence already after a couple minutes you'll have updated
Now information for all providers. If you require more look-ahead than
the next 2-3 programmes, e.g. the complete evening, use a Cyclic mode
that starts with the Near stage.

If you use manual acquisition together with a merged browser database,
make sure to put the same provider at top in both lists, i.e. acquisition
should always start for the "master database" of the merge.

Please note that the time until all databases are complete is longer
in the cyclic modes than in standard manual mode. In general, the time
used for the Now and Next stages just adds to the time to complete the
database.

Also note that the cyclic modes depend on the transmission cycles of
the providers. Firstly this means that the time ranges covered by the
cycle stages may differ between providers. Secondly, the cycle times
may vary. In the worst case the Near cycle runs as long as the cycle
for the complete database (e.g. the German provider RTL2). In this case
you don't win anything by selecting a mode that contains a Near stage.



=head1 STATISTICS

There are currently three ways to obtain information about the state of the
databases and the acquisition process: the first and most obvious is the
status line at the bottom of the main window (only if enabled, see
L<"CONFIGURATION">). The second one are the timescale popup windows,
which visualize for each TV network the time ranges which are covered
with TV programme data. The third one are the database statistics popup
windows which offer technical details about the database, e.g. which
percentage of entries is already loaded etc., both in textual form and
as charts.

The latter two windows are available separately for the browser and
acquisition databases. (By default both are the same databases, but you
can configure background acquisition on multiple databases,
see L<"ACQUISITION MODES">).
All types of statistics are regularily updated while acquisition is running.
While connected to an acquisition daemon, all statistics output refers to
the acquisition running in the daemon.


=head2 Status line

The status line separately summarizes the state of the browser database
(unless it's a merged database) and the acquisition process. Since there's
not much room only the most relevant information is included there, i.e.
the kind of information presented depends on the current state.


For the browser database you'll normally just see the name of the
content provider network and a percentage that describes how many of the
blocks (i.e. TV programmes) in the provider database already have been
received.

If more than 10% of the blocks in the database lie in the past, you'll
additionally see a note about this percentage of expired blocks. Note
that a 100% loaded database may appear completely empty when all blocks
are expired.  As soon as you start acquisition the fill percentage will
drop to 0 because a new inventory will have been loaded which no longer
contains the expired blocks.

When acquisition for the browser database stopped more than 60 minutes ago,
a note is added to the status line. In this case it may be advisable to
start acquisition for this database to load descriptions for programmes
that are now included in the "Near" time range (see L<"DATA ACQUISITION">).


If acquisition is currently not active you'll see a note about that,
often together with a reason, e.g. "no reception" when you've manually
tuned a station that doesn't transmit Nextview.

Else you'll see the name of the content provider network and a percentage
that describes the progress of acquisition. Note that this percentage may
be different from the overall fill percentage given with the browser
database, as it also reflects blocks that have to be reloaded due to
version changes.

Additionally there may be a note about the current mode of acquisition,
like the current phase for cyclic acquisition modes or "forced passive" when
nxtvepg is not able to change the channel, maybe due to a TV application
running in parallel. See L<"ACQUISITION MODES"> for details.


=head2 Timescale popup windows

You can monitor the progress of acquisition with the timescale windows
which can be opened from the Control menu. There's one window for
the browser database, and one for the acquisition database. The
acquisition window is updated whenenever new EPG blocks are received.

The timescale windows have one scale for each network covered by the
selected provider. Each scale begins with the start time of the first
TV programme in the database. Depending on how long ago the database
was updated, the TV programmes may be partly or entirely in the past.
The exact dates are printed in the date scale at top of the window,
the current time is additionally marked with a small arrow.

Ranges that are covered by programmes of the respective network in the
database are marked in shades of red or blue, uncovered ranges are left black.
The different colors reflect the I<stream> in which the data was received,
or an error status; the shades age and version. Stream numbers are directly
connected with the cycle phases mentioned in L<"ACQUISITION MODES">; besides
this the difference is not relevant during normal operation.

=over 4

=item I<red:>

PI blocks received in stream 1, i.e. cycle phase 'Near'.

=item I<blue:>

PI blocks received in stream 2, i.e. cycle phase 'All'.

=item I<dark red or blue:>

PI blocks from an earlier database version.

=item I<orange:>

expired PI blocks from stream 1.

=item I<cyan:>

expired PI blocks from stream 2.

=item I<yellow:>

invalid PI blocks (overlapping or zero run-time,
block number not in the range given in inventory, etc.)

=item I<gray:>

missing PI blocks. Note that the range can only be roughly estimated,
as the time range a block covers is not known until the actual block
is available.

=item I<black:>

time range which is not covered by the provider.

=back

Programmes for which description texts are currently available are
additionally marked by an increased height of the scale in the covered
time range.  For short-info the area is extended towards the top, for
long-info towards the bottom (the distinction between short and long
info is only related to the Nextview transmission specification and
does not neccessarily relate to the length of the description texts;
also note that for the merged database there's no distinction between
short and long info because all texts are concatenated into one.)

In front of the scales there are 5 separate boxes, which refer to the
first 5 programmes (PI blocks) in the inventory (AI block).  They have
two purposes: firstly, during acquisition you can see when the 'Now'
cycle phase is complete; secondly you can check if the data from the
Now cycle is expired (marked orange).  If all 5 are orange, it's time
to update the database.


=head2 Database statistics popup windows

There are two popup windows available from the Control menu which contain
statistical information about the browser database and the acquisition
database and progress. The window is horizontally divided in two parts:
the upper part lists static information; the lower part lists dynamic info
and is available only while acquisition is active.

The acquisition statistics are updated every time a new AI block
(inventory which lists all covered networks and block counts per
network; usually transmitted every 10 seconds) is received.


=over 4

=item I<Last AI update:>

The (local) time when the last inventory block was received. Since
this block has to be transmitted on a regular basis it tells you when
acquisition was active for this database.

=item I<Database version:>

The version number is incremented by the provider every day or after
content changes.  A version change forces a complete reload of the
database.

=item I<Blocks in AI:>

How many blocks are transmitted in total. This number is taken from the
provider's AI block, i.e. the inventory.  Additionally listed separately
for stream 1 and 2 (swo).

=item I<Block count db:>

How many blocks are in the local database. At maximum this can be the
number of blocks given in the AI block.

=item I<Current version:>

How many blocks are in the local database and have the latest version.

=item I<Filled:>

Percentage of blocks in the database in respect to the total given in
the AI block, i.e. "Block count db" divided by "Blocks in AI". The
second percentage in the line only reflects blocks of the current version
and hence the degree of completeness of acquisition.

=item I<Expired blocks:>

Number of blocks which have a stop time that's in the past, i.e. which
no longer show up in the browser. The percentage given here is in respect
to the actual number of blocks in the local database (all versions),
not the AI.

=item I<Defective blocks:>

Number of blocks with invalid or overlapping start time. These blocks
do not show up in the browser (as it would be impossible to handle if
there is more than one "now" entry for a network).  The percentage given
here is in respect to the actual number of blocks in the local database
(all versions), not the AI.

=back

The pie chart on the left on the window visualizes these numbers. The
circle represents 100% of the blocks listed in AI.  It's divided in
stream 1 (red) and stream 2 (blue). The shaded segments represent the
blocks that are still missing in the local database. The yellow segments
the percentage of expired and/or defective blocks.

When you interpret those values, please remember that blocks may be
appended to the transmission cycle when programmes have expired (in a
slight violation of the Nextview standard this is done even without
changing the database version). So you might see from time to time that
the fill percentages take a step back down during acquisition. Also note
that expired PI are not accessible from the user interface, however they
are included in the database dump from the I<Control> menu.


=over 4

=item I<Acq. runtime:>

How long the acquisition has been continuously running for this database.
This timer is reset upon provider or database version changes or when an
external channel change is detected.

=item I<Channel VPS/PDC:>

The VPS/PDC code that has last been received on the currently tuned channel.
Usually this will be the same as the provider CNI given in the database
statistics, but you might see different values here when you manually tune
in a different channel with an external application.

If a valid VPS/PDC code (Programme Identification Label, PIL) was received
together with the CNI it is appended after the CNI in decoded format
(i.e. DD.MM HH:MM with day, month, hour and minute).  Note: the VPS/PDC
codes are used to uniquely identify the current programme on a given
network.  You can display the codes for all programmes in the database
if you enable them (see L<"CONFIGURATION: Select columns">).

=item I<TTX data rate:>

The rate at which teletext data lines are received on the current channel
in baud, i.e. bits per second.  Each teletext line counts as 45 bytes.

=item I<EPG data rate:>

Same as TTX data rate, however only teletext lines that belong to the
page which transmits Nextview are counted.

=item I<EPG page rate:>

The per second average of received teletext pages with carry Nextview data.
Many provider transmit one page per second during the day and up to
1.5 or 2 pages per second during the night.

=item I<AI recv. count:>

The number of AI blocks received since acquisition start.  As long as this
counter remains at zero, no data is added to the database (because the
AI block is mandatory to identify the provider.)

=item I<AI min/avg/max:>

The minimum, average and maximum distance between reception of AI blocks.
The average should usually be 10 seconds.  The maximum should not be much
higher or else an EPG scan might have a hard time finding this provider;
also the acquisition start-up time would be higher because at first an
AI block must be awaited.

=item I<PI rx repetition:>

The average of the number of times each block in the AI was received
since start of the acquisition.  Divided in Now, stream 1 and stream 2.
This value is used by acquisition control in the termination criterium
for acquisition phases, if the acquisition mode is cyclic.

=item I<Acq mode:>

The current acquisition mode as configured by the user, or forced passive
if nxtvepg failed to switch the channel.

=item I<Network variance:>

The variance of block coverage across all networks.
This value is used by acquisition control in the termination criterium
for acquisition phases, if the acquisition mode is cyclic.
It's calculated by separately counting the number of blocks in the
database for each network; then for each network calculating the
percentage of available blocks in regard to expected blocks; then
calculating the average and finally variance of these percentages.

=back

The diagram at the left displays a history of fill percentages for
stream 1 and 2; the meaning of the colors is the same as in the
timescale windows.



=head1 MERGED DATABASES

If you compare databases of different Nextview providers, you will
often find that each has one or more nice features, or covers networks,
that the others lack. Instead of changing back and forth between
several providers all the time, database merging allows to select and
combine features or networks from several original databases into one
newly created database.

When you select the B<Merge providers> entry from the B<Configure>
menu, you will get a dialog with two listboxes: the left one contains
a list of all currently available databases. The right one is the list
of databases you want to merge. You can add, delete or reorder the
entries is this list. When you're done with your selection, press B<Ok>
to start the merge and switch the browser to the new database.

By ordering providers in your selection, you assign priorities which are
important for conflict resolution. A conflict occurs when programme start
and stop times differ between providers. The likelyhood of such conflicts
depends on the quality of your providers; theoretically they should never
happen except if there are late program changes. In reality, conflicts are
not that unlikely, particularily for programmes early in the morning.
You should put the most reliable provider in the first position, because
conflicting programmes from providers further down will be rejected,
i.e. not added to the merged database.

The B<Configure> button in the dialog gives you fine-control over the
priority of providers during the merge of all distinct programme
attributes. You can even completely remove a provider for an attribute,
e.g. if they transmit false data (e.g. the Sound attribute is handled
wrong by the German provider 3Sat: they have swapped Stereo and Surround).
An exception is the title, where you must not delete any providers.

Attributes that cannot be merged, e.g. editorial rating, are fetched from
the first database in the list that contains the attribute for a given
programme.  An exception are sorting criteria and series, where only the
first provider in the list is queried (i.e. even if the first provider
does not have a sorting criterion for a given programme, the further
databases are not searched) because these types of attributes cannot
be mixed between providers (see also L<"FILTERING">).

Note: If you use a manual or cyclic acquisition mode, you should take care
to include all providers of your merged database in the same order. Else,
program changes will not appear in your database until the provider with
highest priority is loaded. If you stay with the default B<Follow-UI>,
acquisition control will automatically cycle across all merged providers
in the correct order.



=head1 NAVIGATE

The Navigate menu contains a tree of filtering options, that's transmitted
by the selected provider together with the programme data. Filtering enables
to restrict the listing of programme information to those titles matching
the selected menu entry.

The extent and content of this menu depends entirely on the provider.
Unfortunately most providers supply only a very limited menu, so you'll
probably want to define your own filters, as described in the next two
chapters.

Any filter selection can always be undone by the
I<Reset> menu entry or the reset button in the main window.

On Windows this menu is en entry inside of the I<Filter> menu for technical
reasons (the concept of danamically created menu hierarchies seems to be
foreign to Windows, so a popup menu has to be used for the Navigate menu).



=head1 FILTERING

Similar to I<Navigate>,
this menu allows to control which of the programmes in the database
are presented in the listing.  However here, you are not limited to a
preselection of filter options.  There's a filter for every kind of
attributes that can be attached to a program, e.g. it's network,
start time, theme descriptors, ... and many more.

Filters can be undone either singularily by selecting the same filter
menu entry again, or globally by clicking on the I<Reset>
button or menu entries.

You can combine as many filters as you want to build a complex filter.
If you combine two filters of different types, only programmes that
match both attributes will be listed (logical AND). If you choose more
than one filter of the same type, all programmes that match either
attribute will be listed (logical OR).

I<Examples:>
If you want to see all programmes listed for either network ARD or
ZDF, simply select both networks. If you want to see all movies
scheduled on Arte, select network=Arte and theme=movies.

Summary of filter options:


=over 4

=item B<Features>

Restrict the listing to programmes that match all given attributes
(logical AND), i.e. sound format, picture format, analog/digital,
encrypted yes/no, live/new/repeat and subtitles yes/no. If you want
to allow more than one value of the same attribute (e.g. picture format
wide OR Pal+) you have to put them into different feature classes.


=item B<Parental Rating>

Restrict the listing to programmes that are suitable for children
of the given age or elder.


=item B<Editorial Rating>

Restrict the listing to programmes that are rated (by the content
provider) to have at least the given quality. The range of rating
values is 1 to 7. Note that some providers do not use all values,
e.g. only 1 to 5, or e.g. just 3, 5 and 7.


=item B<Themes>

Restrict the listing to programmes that have any of the given theme
categories attached to them (logical OR). The Nextview standard
contains a list of 76 predefined themes, which are structured into
11 main categories and subcategories. A programme can have up to
7 theme descriptors attached. If you want to restrict the listing to
programmes that have more than one of the given themes (logical AND)
you need to specify them in different theme classes.


=item B<Series>

Restrict the listing to programmes that belong to any of the given
series. A series code always implies a network specification (even if the
same programme is transmitted on different networks). This filter type is
only available for providers that assign series codes; for the other ones
you can use text search among programme titles.


=item B<Program index>

Restrict the listing to programmes who's index is in the given range.
The currently running programme of each network is given index zero,
the following programme of each network index one etc. The three most
important combinations are available as radio buttons:
I<now> (range 0-0),
I<next> (range 1-1) and
I<now or next> (range 0-1).

For merged databases only indices 0 and 1 are supported.


=item B<Networks>

Restrict the listing to programmes of one or more given networks.
The filter is disabled when all checkbuttons are deactivated.

You can also permanently add an equivalent network filter menu to
the main window by enabling I<Show networks> at the end of the
L<"CONFIGURATION"> menu. Note that selection, order and names of
networks are all configurable.


=item B<Text search>

Restrict the listing to programmes who's title or description (or either
if both options are enabled) contain the given text.  If you enable
I<match complete text> an exact match will be required, i.e. a search for
"heute" will not match on "heute journal" (this option is intended for
title-only searches, as started from the context menu). If you enable
I<match case> character case is relevant in comparisons, i.e. a search
for "heute" will not match on title "Heute Abend".

A history of the last 10 searches, including options, are stored and
available in the drop-down menu below the search text entry field (opened
with the arrow button at the left or one of the up/down cursor keys)
and the I<Title> column header menu in the browser.


=item B<Start Time>

Restrict the listing to programmes who's start time lies in the given
interval. There are two special modes for the interval specification:
If you enable I<Start at current time>
the interval start is fixed to the actual time when the filter is
applied and the value given as stop time is interpreted as duration, i.e.
it's added to the interval start. If you enable I<Stop at end of day>
the interval end is fixed to 23:59 of the same day.

Note that the main intention of this filter is to support time
restrictions in the provider's navigation menus (see L<"NAVIGATE">).
For manual navigation there are more practical alternatives, e.g.
the scrollbar and drop-down menus in the main browser window.


=item B<Duration>

Restrict the listing to programmes whose duration (i.e. difference
between start and stop time) lies in the given range.  When the
maxium is set to zero, the filter is switched off.


=item B<Sorting Criteria>

Restrict the listing to programmes that have any of the given sorting
criteria attached to them; every programme can have 0..7 sorting
criteria attached to it.  They work very much like theme descriptors
however their meaning is not predefined by the Nextview standard.
The content provider can use arbitrary numbers to represent an attribute.
Attributes usually are themes that are not in the predefined catalog,
e.g. current events like the Olympic Games, but could also be not
content related at all.  The meaning of these numbers is usually
defined by the provider's navigation menus (see L<"NAVIGATE">).

Equivalently to themes, you can assign sorting criteria in different
I<classes> to implement a logical AND, i.e. only programmes that have
at least one of the sorting criteria specified in every used class
will match. Example: to get all programmes that have 0x01 attached
plus either 0x10 or 0x11, specify sorting criterion 0x01 in class #1
and 0x10 and 0x11 in class #2.  Note that the dialog displays
all values in hexadecimal format, i.e. with digits 0-9 followed
by a-f.

The I<Load all used> button in the sorting criteria filter dialog
fills the selection listbox with a list of all codes that are actually
used in the current database.  This allows a quick overview which filter
criteria will produce any matches.

=back


Note that the interpretation of two filter types depends on the
provider: sorting criterion and series. That's because those are
just arbitrary numbers which only have a meaning in the context of
the provider's navigation menu.

I<Hint:>
the filter menu can also be used to examine the filter options
that are invoked by the entries in the Navigate menu.



=head1 FILTER SHORTCUTS

There's a number of predefined filter options in the main window below
the clock. These shortcuts enable you to invoke filters by a single click
of the mouse. You can freely add or remove entries from this list.

When you want to add a shortcut, either choose an entry from the
Navigate menu or define your own filters via the Filter menu, possibly
based on one or more already defined shortcuts. When you have found an
interesting selection, call I<Add filter shortcut> from the Filter
menu. You'll find a new shortcut appended to the list of existing
shortcuts. First you'll probably want to enter a description in the
entry field at the top of the dialog; default is just "shortcut #xx".
When you're done just press I<Save>, or I<Abort> if you've changed
your mind and don't want to add this shortcut after all.

You can also change descriptions or ordering of existing shortcuts
in this dialog.  If you want to modify the shortcut list without adding
a new one, you can also access the dialog from the I<Configure> menu.

If you want to change the filter settings of an existing shortcut,
then invoke the shortcut, modify the settings as you need and then
use the I<Update filter shortcut> dialog in the Filter menu to save
the new settings of any existing shortcut. You can use the
I<Update & Edit> Button to jump to the filter configuration dialog,
e.g. if you want to fine-tune the description or ordering.

When you deselect a shortcut, either by selecting another shortcut
or clicking on it a second time with I<CTRL> held down, all it's
filters will automatically be undone. Hence when you have two themes
shortcuts, e.g. "Movies" and "Sports", and select first Movies, then
Sports, you'll see only sports programmes afterwards.  However if you
had selected theme movies manually, e.g. by the context menu explained
in the next chapter, the movies filter might remain set, so that you'd
get all programmes of theme movies OR sports.  Since that is usually
not what one expects, a filter mask has been introduced to the shortcut
setting.

The filter mask is defined in the shortcuts dialog with a checkbutton
for each filter type. By default, the mask is enabled for every filter
type you've included in the shortcut filter setting.  When you invoke
the shortcut from the main window later, all filters of the given types
will be cleared (masked out) before the shortcut filters are added.
To return to the above example: if the "Sports" shortcut is defined
with a themes mask, the manually set movies filter would be cleared
before the theme filter is set to sports.

The masking can also be enabled when no filter of that type has been
chosen. This can be used to define I<undo> shortcuts. E.g. choose the
mask 'Themes' if you want a shortcut that allows to clear all
theme-related filters at once. Or enabled all masks for a I<Reset>
button (the only difference to the pre-defined Reset button would
be that the cursor does not jump to the first Now programme.)

You can invoke several shortcuts in parallel by pressing the I<CTRL>
or I<SHIFT> keys when selecting in the listbox - just as you know it
from other applications. However the behavior of the combined shortcuts
is slightly subtle and might not always match your expectations.
That's because the shortcuts are not cleanly separated when processed.
Instead all filters of all selected shortcuts are thrown together and
then processed as if they belonged all to one shortcut in the way
described in L<"FILTERING">. This might change in the future
if someone convices me there's a real need to.



=head1 CONTEXT MENU

Another quick way to select and deselect filters is by using the
context menu, which is popped up with the right mouse button in
the browser window.

This menu consists of three parts: the first entries allow to undo the
previously selected filters - either one by one or globally (reset).

The second part offers a number of possible new filter options, which
depend on the currently selected title and the already selected filters.
The offered filter types include: themes and network of the selected
programme title, it's series code, repeat or original transmission
suppression (only in cunjunction with series or title text filters)
and last but not least the title text.

The title text and series filters allow to check very quickly for
repeats of a programme. These filter options are included only if
there is a match, i.e. if there's another programme with the same
title or series code repectively.

The optional third part is empty by default, but can be used to invoke
user-defined external commands on the selected programme. More precisely,
you can execute any command with properties of the selected programme
(like title or start time) on its command line. The user commands
can be added via the Configure menu (see L<"CONFIGURATION: Context menu">).


=head1 CONTROL

Summary of commands available from the Control menu:


=over 4

=item B<Enable acquisition>

Toggles acquisition on or off.  When you start the browser, acquisition
is automatically enabled (although failure to do so is silently ignored).
Switching off acquisition allows other applications (e.g. a teletext
decoder) to use the TV card while you browse the database, if you have
only one TV card.

UNIX: When acquisition is switched off, the I</dev/vbi> device is freed.
Acquisition can also been switched on and off automatically (i.e. from a
shell script) by sending signal HUP (e.g. with the kill(1) command) to
any of the nxtvepg processes or threads.  If you're using a daemon for
acquisition (see the next command) you have to send the signal to one of
the daemon processes/threads.  To simplify this, the pid of the process
which needs to be signalled is stored in F</tmp/.vbi.pid> while the device
is in use.

Windows: When acquisition is switched off, the driver is unloaded so
that other programs can access the TV card.  Note that most Windows
driver implementations do not allow for more than one TV card in the PC.


=item B<Connect to acq. daemon>

Connect to or disconnect from an acquisition daemon, running in the
background on the same host, or somewhere else in the network.  The
address of the daemon and other parameters are configured in the
I<Client/Server> menu (see L<"CONFIGURATION: Client/Server">).
By default the daemon
is started on the local host.  The main advantage of using the daemon
is that you can keep running acquisition permanently in the background,
even if you terminate the browser, or on UNIX even the X11 server (i.e.
the windowing system). On M$ Windows the daemon is terminated when you
log off.

If you attempt to connect, but no daemon is running, you'll be offered
the option to automatically start the daemon and retry the connect,
provided you have configured server hostname I<localhost>.
The daemon will be started with the same database directory and rcfile
as the browser.

Note that disconnecting from the daemon or terminating the browser does
not stop the acquisition and hence does not free the device.  If that's
what you want, choose the I<Enable acquisition> command instead, which
terminates the daemon.  Of course this option only is available if your
daemon is running on the same host and with the same user id as the
browser process.


=item B<Dump stream>

UNIX only: All incoming Nextview blocks are dumped to I<stdout>
in an ASCII format. This is mainly intended for developers, but
it may also help to debug reception problems, because in the dump
you'll find any block that could be decoded without hamming errors,
even before an inventory block (AI) has been received. This may help
if you have very bad reception, because it may take a long time
until a error-free copy of the usually large AI block is received.

When connected to a acquisition daemon, blocks are only dumped if
they are new to the database or their content changed (because only
those are forwarded by the daemon to the client.)


=item B<Dump raw database>

Open a dialog that allows to dump all blocks in the database to
I<stdout> (UNIX only) or into the named file in a raw text format,
which is actually the same as with the I<Dump stream> command.
This feature is mainly intended for developers. To understand all
the infos in the text dump, you'll have to look at the source in
F<epgui/epgtxtdump.c> in the nxtvepg source package.

The array of checkbuttons allows to control which kind of blocks
will be written. The programme information blocks (PI) do contain
the actual programme descriptions; I<Defective PI> contains those
PI which were not accepted into the database because of inconsistencies
like a zero or overlapping running time. For an explanation of the
other block types please see the ETSI specification 707.


=item B<Export as text>

Open a dialog that allows to export the complete database into a text
file.  Each line in the file will represent one item in the database.
The item's different fields are separated by TAB characters; the line
is terminated by a single new-line character (no line feed character,
even on Windows).  In some cases missing values are represented by
C<\N> which is the MySQL I<NULL> identifier (currently only used for
the VPS/PDC field).

The generated text file can be loaded directly into a relational
database.  It's not formatted for viewing in a regular text editor.
Networks and themes are represented as numerical indices into the
network and themes table respectively.  Hence these tables are
required in addition to the programme table.  To load them into
a database, you need to export them into different files.

For I<MySQL> you could create the following tables:

   CREATE TABLE PI (
      netwop smallint(2) unsigned NOT NULL,
      Dstart date NOT NULL,
      Hstart time NOT NULL,
      Hstop time NOT NULL,
      vpspdc_pil datetime,
      prat tinyint(2) unsigned,
      erat tinyint(2) unsigned,
      sound enum("mono","2-chan","stereo","surround"),
      is_wide BOOL,
      is_palplus BOOL,
      is_digital BOOL,
      is_encrypted BOOL,
      is_live BOOL,
      is_repeat BOOL,
      is_subtitled BOOL,
      theme_0 tinyint(3) unsigned,
      theme_1 tinyint(3) unsigned,
      theme_2 tinyint(3) unsigned,
      theme_3 tinyint(3) unsigned,
      theme_4 tinyint(3) unsigned,
      theme_5 tinyint(3) unsigned,
      theme_6 tinyint(3) unsigned,
      title varchar(40) NOT NULL,
      descr text,
      PRIMARY KEY (netwop, Dstart, Hstart)
   );

   CREATE TABLE AI (
      netwop_idx smallint(2) unsigned NOT NULL,
      cni smallint(5) unsigned,
      lto_mins smallint(5),
      daycount smallint(5) unsigned,
      alphabet smallint(5) unsigned,
      addinfo smallint(5) unsigned,
      name text,
      UNIQUE netwop_idx (netwop_idx)
   );

   CREATE TABLE pdc_themes (
      theme_idx smallint(3) unsigned NOT NULL,
      cat_idx smallint(3) unsigned,
      name_eng text,
      name_ger text,
      name_fra text,
      UNIQUE theme_idx (theme_idx)
   );


=item B<Export as HTML>

Open a dialog that allows to export the complete database or selected
programmes into a file in HTML format (Hypertext Markup Language) which can
then be loaded into a WWW browser, e.g. I<Netscape>. This is particularily
useful if you want to print out TV descriptions.

At the top of the dialog window you have to enter the output file name.
Click on the little folder button for a file selection dialog.

By default the checkbutton I<Selected programme only> is enabled. In this
mode only info on the programme which is currently selected with the cursor
will be written. In combination with the I<Append to file> mode this
allows to build a document with the programmes that interest you step by
step. If you deselect I<Selected programme only>, info on all programmes
that match your current filter will be written. Note that this can generate
very large files which may take a long time to load into your Web browser.
In this mode you may want to set an additional start time filter
(see L<"FILTERING">) to restrict the number of programmes written.

In the bottommost box you see three radio buttons with which
you select the format in which the information will be written. If you
select I<titles> you'll get a table in the same configuration as in the
titles list in the upper part of the main window. If you select
I<descriptions> you'll get roughly the same as in the lower part of the
main window. Obviously, if you select I<titles and descriptions> you'll
get both, in form of one table with all the titles on top and all
descriptions separately below. If you select I<Add hyperlinks> the
titles in the table will be linked to the descriptions.

The look of the generated document is almost entirely determined by use
of an internal CSS stylesheet. If you don't like the look you can override
it with your own stylesheet. Save it to a file named F<nxtvhtml.css> and
put it in the same directory as the generated HTML file. For more
information on HTML and style sheets see I<http://www.w3.org/>


=item B<View timescales>

Toggles the timescale window for the browser database. The window
reflects for each network included in the selected database, which
time ranges are covered by programme information. If acquisition
is working on the database, you can watch how more and more of the
scales get covered.  See L<"STATISTICS"> for details.


=item B<View statistics>

Toggles the browser database statistics window, which informs you about
number of program entries in the database, fill percentage, expiration
percentage, date of last update etc.  If the acquisition is working on
the same database, it also contains information about state and progress
of acquisition.  See L<"STATISTICS"> for details.


=item B<View acq timescales>

Toggles the timescale window for the acquisition database. This entry
is only available if the acquisition uses a different database than
the browser.


=item B<View acq statistics>

Toggles the acquisition statistics window, which informs you about
state and progress of acquisition. If the acquisition control mechanism
switches to a different database, the acq statistics window will
automatically follow.  See L<"DATA ACQUISITION"> for details.


=item B<Quit>

Close all windows and terminate the application.

=back



=head1 CONFIGURATION

Summary of commands available from the Configure menu:


=head2 Select provider

Open the provider selection dialog.  This dialog lists all TV channels
from which Nextview data can be received.  When you select a channel
name on the list, you'll see the name of the Nextview service that's
transmitted there and a list of all networks covered by it on the right.

If you leave the dialog with Ok, the selected provider's database will
be loaded into the browser.  If the database hasn't been updated for a
long time, the programme list might initially be empty, but if you have
selected "Follow-UI" acquisition mode, the provider's TV channel will be
tuned to update the database content (see L<"ACQUISITION MODES"> for
more details.)

To remove obsolete providers (i.e. such which have ceased to provide
Nextview service or which you can no longer receive), you should start a
provider scan in I<refresh> mode.  You cannot remove active providers
because nxtvepg would add them back automatically in the next scan or
when their TV channel is tuned externally.


=head2 Merge providers

Open a dialog that allows to merge several databases into one.
See L<"MERGED DATABASES"> for details.


=head2 Acquisition mode

Open a dialog that allows to control the background acquisition process.
See L<"ACQUISITION MODES"> for more details.


=head2 Provider scan

Open a dialog that allows to start a scan across all TV channels for
Nextview transmissions.  You should perform this search at least once,
firstly to find out which providers are available in your area, and
secondly to determine the frequencies of all provider's TV channels. They
are required for most acquisition modes, and due to driver limitations
often not available without a scan (e.g. on Windows or Linux with bttv
driver <= 0.7.50). See also L<"GETTING STARTED"> and the subsequent
chapter on TV card configuration.

Check the I<Slow> button if you have bad reception on some channels.
In slow mode the scanner will not require a stable video signal and wait
twice as long as normal for everything, i.e. up to 4 seconds for a
VPS/PDC channel identification and up to 90 seconds for EPG for known
providers or if potential data packets were found.  Note that you can
change this setting while the scan is running.

The I<Use TV app.> button is automatically checked if an I<xawtv>
configuration file is found in your home directory (on UNIX) or
a TV application was set up in the I<TV app. interaction> dialog
(or initially in the I<TV card input> dialog).  Instead of
searching all possible channels in all bands, nxtvepg then just checks
the TV channels defined there, which saves a lot of time.

Use the I<Refresh only> mode if you deleted your database files (or if you
upgrade from an incompatible software version) or if you want to find and
remove obsolete providers. In this mode only the channels on which Nextview
data was received before are checked (the frequencies are kept both in the
databases and your rc/ini file). This allows you to regain your complete
provider list very quickly. If no data transmission is found on a
provider's channel, a I<Remove this provider> will be added to the
output window, which you can use after the scan has finished to remove
the database and any information recorded about the provider.

The scan will visit every physical TV frequency (or subsets thereof if
you use one of the options described above) and check for a TV signal.
If one is detected within 150 ms or if at least one teletext packet
was received, the scan waits up to two seconds for a valid VPS/PDC
channel identification.  At the same time it receives packets from all
potential EPG teletext page addresses.  If a VPS/PDC code is read that
belongs to one of the known EPG providers or valid data packets have
been received (which does not necessarily mean it's EPG, because other
services could use the same encoding) the scan waits up to 45 seconds
for EPG inventory messages (BI and AI blocks). You can watch these
proceedings in the message output window.

Even though the scan tries very hard, it can not warrent that every
EPG provider is found every time. For example some providers do have
pauses of more than 45 seconds in their EPG transmission; or they
might have technical problems.  So the safest way is to check the
nxtvepg WWW homepage (see I<About> in the Help menu) for a list of known
EPG providers. If you receive the channels where they transmit, repeat
the scan until they are found, e.g. at different times of the day.
If you find new providers not listed on the web site, please let me know.


=head2 TV card input

Open a dialog where the driver for the TV card can be configured.
This dialog looks very different on Windows and UNIX platforms,
because on UNIX the driver is part of the operating system, whereas
on Windows it's part of the application and has to be configured
separately for every application.

On Windows systems you must at least specify which type of tuner
is on your card, and how the PLL needs to be initialized. You can
copy these settings from a number of supported TV applications,
which can be selected at the top of this dialog (please note that
the TV application selected here is not neccessarily used for TV app.
interaction; see L<"CONFIGURATION: TV application interaction">).
Please refer to L<"GETTING STARTED"> for a detailed description on
how to configure these parameters.

Windows only: if you experience data loss due to heavy system load,
you can raise the acquisition thread priority.  Default is I<normal>,
i.e. the same as for all user applications.

The remaining three configuration options apply to both UNIX and
Windows: firstly choose which video input source to use, i.e. where
you have connected an input signal cable to the TV card:
I<Tuner> or I<Television> refer to input via antenna cable (also
known as RF cable, i.e. terrestrial reception or cable TV);
I<Composite> refers to a cinch video cable as used by satellite
receivers or cheap video records; I<S-Video> is an variant of Composite
with improved image quality (often wrongly called S-VHS cable since
it's mostly used by S-VHS video recorders) and easily recognized
by the Sub-D connectors (called "Hosidenstecker" in German).

See L<"DATA ACQUISITION"> about the consequences of not using the
TV tuner as input.  On Windows: in rare cases the descriptions of
input sources in the TV card popup may be wrong (due to creative
wiring of the Bt8x8 chip on your TV card) so that you may find
your TV tuner for example on "Composite 1".  This is an open point
in the driver interface implementation; feel free to complain to me.

If you live in France, select the French frequency table (which implies
the I<Secam L> TV norm) to be used for the EPG scan; the default is a
frequency table for Germany, Austria and Switzerland and the PAL B/G/I
TV norm. Other countries are not supported, since there currently
are no Nextview providers.  If you live in an area where you receive
both PAL and Secam stations, you should perform the EPG scan twice
with different channel tables.

If you have more than one TV tuner card, you can also choose which
one to use, just like with the B<-card> command line option. On
Linux you get a popup menu with TV card names as supplied by the
driver. On Windows you only can choose cards by an index; the
relation between index number and cards is undefined, i.e. which card
has index 0 depends on the driver implementation and may differ between
applications using different drivers.

Windows only: at the very bottom of the dialog window there's a
checkbutton which allows to enable logging during driver startup and
shutdown. The output is appended to a file named I<dsdrv.log> in the
nxtvepg working directory.  Enable this option if you're not able to
start the driver and cannot find out why.  But first see the explanation
of driver error messages in the README file.  Note that the logging
option is not remembered across program starts, i.e. to make use of it
you have to enable the acquisition via the Control menu and not by
restarting nxtvepg.


=head2 Client/Server

Opens a dialog that allows to configure the connection between acquisition
daemon (called "server" here) and GUI.  The connection allows to forward
all newly acquired EPG data from the daemon to the GUI and to monitor the
daemon's acquisition progress.

The dialog contains settings of which some refer to the server-side only,
some to the client-side only and some to both server and client.  To avoid
confusion, there are three radio buttons at the top of the dialog which
allow to grey out items that do not refer to the client or server
respectively.

=over 8

=item I<Enable remote control>

Note: this feature is not yet implemented.
By enabling remote-control you can stop acquisition, change acquisition
mode, TV card parameters or any parameters configured by this dialog
in a running daemon via the network connection.

=item I<Enable TCP/IP>

By enabling connections via the TCP/IP network protocol, you allow
connections from remote hosts.  Since there's currently no access
control in nxtvepg, these hosts can be anywhere in your network,
or anywhere in the world if you're connected to the Internet. If
you don't have a firewall which prevents incoming connections of
untrusted hosts, this mode is highly depreciated, because nxtvepg
is not in any way secured against malicious client connections.

Note: on Windows currently only TCP/IP is supported, i.e. you have
to enable this option if you want to start the daemon.

=item I<Server hostname>

Client-side only: this setting identifies the host on which the daemon
is running. You can enter either a hostname in "dot.com" format or
an IP address in "127.0.0.1" format.  If you set it to I<localhost> the
connection is automatically established via UNIX domain sockets (i.e.
pipes), which is more efficient than TCP/IP.  You can still use TCP/IP
locally if you set it to the name of your local host, as returned
by hostname(1).

=item I<Server TCP port>

If TCP/IP is enabled, this setting tells server and client which port
to use. You can enter an arbitrary number between 1024 and 65535 here,
but you have to make sure no other server is using the same port.
Make sure you configure the same port number for client and server.
The default is 7658.

=item I<Bind IP address>

If TCP/IP is enabled and your server host has more than one IP address,
you can select here on which one to listen for incoming connections.
Make sure you use the same IP address as server hostname on client-side,
or a hostname that resolves to that IP address.  This setting is optional;
if you leave the field blank (default) the server will bind to all
IP addresses.

Note: on systems that support it, TCP/IP sockets are created in the
IPv6 domain (I<PF_INET6>) by default.  On some systems (e.g. NetBSD)
you cannot connect via IPv4 to an IPv6 server and vice versa, i.e. you
need to use the same domain on both ends.  If your client only supports
IPv4, you can force your server to create an IPv4 socket by binding to
an IPv4 address.  If you fail to connect to a local IPv6 server via
the IPv4 loopback address 127.0.0.1, use the IPv6 equivalent "::1".

=item I<Max. connections>

This setting limits the number of client connections the server will
allow.  Once the limit is reached the server will stop listening for
new connections.

=item I<Log filename>

If you enable log generation by the following option, you can choose
here where the log will go. Make sure the file is writable to the uid
under which the daemon process is running.  The file opened and closed
for each appended log line (usually there's very low traffic into that
file) so you can operate on it (e.g. truncate it) without restarting
the daemon.

=item I<File min. log level>

Here you can choose if log information should be written to a file.
If you run nxtvepg with TCP/IP disabled, you don't need to use logging;
but if you allow remote connections you should keep log files at
"info" level to be able to check which hosts connect to your server.

The following settings are available: "no logging" disables logging;
"error" enables logging of internal errors that lead to an immediate
exit of the daemon; "warning" additionally enables logging of
unexpected events, i.e. internal errors which do not lead to exit;
"notice" additionally enables logging of server status changes,
i.e. startup and shutdown; "info" additionally enables logging of
connection establishment or shutdown. 

=item I<Syslog min. level>

Here you can enable or disable logging to UNIX syslog and Windows
application event logging (application name is I<nxtvepg daemon>;
this feature is not supported by Windows 95).
See UNIX man pages I<syslogd(8)> and I<syslog.conf(5)> or the Windows
event log help for details about the syslog facility. The log levels
you can choose here are the same as described in the previous paragraph
for logging to files.

=back

Note that while network mode is enabled configuration of acquisition
mode and TV card input has no effect and no EPG scan is possible.
If you use the same rc/ini file for daemon and GUI the changed settings
will however be used by the daemon upon the next start.


=head2 TV application interaction

Opens a dialog that allows to configure the interaction between a
TV application and nxtvepg.  On UNIX this menu entry is available
only when a F<.xawtv> configuration file is found in your home.
On Windows you should at least configure your TV application type
and path here if you're using one of the supported applications; this
is a recommended step during the initial installation, as described
in L<"GETTING STARTED">.

The first four (only three on UNIX) options allow to 
switch interaction features on or off. If you want to improve startup
time on UNIX, turn them all off; in this case nxtvepg does not need to
search for the I<xawtv> toplevel window (which can take up to several
seconds if you have many applications running or a slow connection to
your X server.) By default all interaction features are enabled.

=over 4

=item I<General enable>

Windows only: the option allows to disable or
re-enable the allocation of communication resources, and implicitly
to switch off or on all interaction features. While disabled, nxtvepg
will be invisible for the TV application.  The use of this option is
depreciated, as nxtvepg won't automatically free the driver when the
TV application is started, and nxtvepg will fail to start acquisition
when a TV appliaction is running.  Use this option only if you suspect
compatibility problems between the TV app and nxtvepg, e.g.  if one
application hangs or crashes during startup if the other is already
running (I'm not saying such behavior is to be expected, but it's
better to be prepared for everything)

=item I<Tune TV button>

This option allos to hide or show the equally named button
and it's little popup menu (accessed with right mouse button) below the
clock in the nxtvepg main window.  If you're not interested in
remote-controlling the TV application, switch it off.

=item I<Cursor follows channel changes>

While this option is enabled,
nxtvepg will monitor TV channel changes. Whenever such a change is
detected, the cursor in the programme listbox will be set onto the
title currently running on that network. During EPG acquisition VPS/PDC
is used to exactly determine the current programme (only on networks
which support VPS/PDC); however if the nominal running time is in the
past it's currently not possible to display the programme in the
listbox. This info may however be sent to the TV app (see next option).
If you have just a network filter enabled, it will be switched to the
new network so that you'll get a complete listing of that network's
programmes, starting with the currently running one. This works even
when you have excluded this network in the network selection configuration.
If there are more or other filters than network enabled, then they will
remain unchanged. If the current programme on the new network does not
match this filter setting, then neither cursor nor listbox content will
be changed.

=item I<Display EPG info in TV app>

While this option is enabled,
nxtvepg will monitor TV channel changes. During EPG acquisition
VPS/PDC are also monitored to determine newly starting programmes.
VPS/PDC also allows to detect channel changes on an external input
source, e.g. a satellite receiver connected via the Composite socket.
After a change of channel or current programme title, the info about
the currently running title will be displayed in the TV application.
On Windows it's entirely up to the TV application how this information
is displayed.

On UNIX the display format can be selected by the following radio buttons:

With I<Separate popup> nxtvepg will generate a small popup window and
put it right beneath the xawtv window. The blue area in the small bar
on top represents how much of the (nominal) running time lies in the past.
With I<Video overlay> the info will be handed to xawtv and displayed
as subtitles (please note that this option only works properly with
XFree86 version 4 and the XVideo extension). If you prefer a proportional
font add the following line to F<~/.Xdefaults>:

  xawtv.vtx.label.font: -*-helvetica-bold-r-*--14-*-*-*-*-*-iso8859-*

and execute F<xrdb -load ~/.Xdefaults> afterwards. Note that this will
affect subtitles too. Future versions of xawtv will hopefully allow for
dynamic font selection.
I<Video overlay, 2 lines> is the same except that it writes running time
and title in separate lines and additionally contains the percentage of
expired running time. (Not recommended with xawtv versions older than 3.48
as there was a bug in displaying lines of different width.)
With I<Xawtv window title> the info will be sent to xawtv and displayed
in the window title. Except for this last option, you can configure the
desired display duration with the slider at the bottom of the dialog.
A duration of zero means the display will never be removed.

=back

Windows only: in the middle of the dialog there's one line that
indicates the current TV application connection status.  It contains
the name of the connected application or I<not connected>. You
can connect to different applications than configured below, but if
the network names are not synchronized with nxtvepg, the interaction
will not work optimally (i.e. nxtvepg might not be able to identify
all networks, and hence not be able to provide programme titles).


Windows only: in the lower part of the dialog window you can configure
the type and path of your preferred TV application.  This information
is used to access the TV app's channel table (i.e. TV tuner frequencies
and station names) during an EPG provider scan
(see L<"CONFIGURATION: Provider scan">) and in the network name
configuration dialog (see L<"CONFIGURATION: Network names">).
After you've changed the setting, you can press the I<Test> button to
check if nxtvepg can parse the channel table correctly. It will complain
if it fails to open the file or registry key and if no channels are found.
After the test was successful, you shoud open the network names
configuration dialog and synchronize network names with nxtvepg.

If your TV application is not supported, choose I<none>.  (If it's a
freeware application feel free to mail me a download URL and I will
consider supporting it.  However I will not support proprietary
closed-source software, unless on request by the author.)

Note that not all of the TV applications listed in the popup menu can
currently interact with nxtvepg.  The interaction requires modifications
in the TV applications; it's up to the respective authors if they want
to implement these. (If you are an author of a TV app, feel free to mail
me if you want to add EPG support to your application; a demo application
and reference implementation source code are available on the nxtvepg
home page.)

Note that there's a similar configuration in the I<TV card input>
dialog.  However that one is only used to load the hardware settings
during initial setup (i.e. when you press I<Load Config> in that dialog).
In most cases you'll use the same TV app for both purposes, but you
don't have to.


=head2 Select columns

Open the browser listbox column configuration dialog. It allows to
select which attributes are displayed for the listed programmes. In the
listbox on the left you find a list of all available categories, e.g.
title, running time & date, TV network name, rating, sound and picture
format, i.e. mostly the same attributes that are available for filtering.

The listbox on the right contains the types currently selected for display.
The topmost entry appears on the left side of the listbox.  Press I<Apply>
to refresh the browser listbox with the new column selection and save the
new configuration to the config file.

Note: you can change the width of each column by moving the mouse pointer
to the very right of the menu button above each column (provided column
headers have not been disabled in the Configure menu) and then dragging
the border to a new position while keeping the left mouse button pressed
down.


=head2 Select networks

Open the network selection dialog. It allows to permanently suppress
TV networks in a provider's listing, e.g. if you can not receive the
channel. You can also change the order of the networks, e.g. to put
your favorite networks at the top of the filter menus.

This window has two lists: on the left you'll find all networks that are
covered by the provider in their original order, on the right those that
are selected for the programme listing in your preferred order. By default,
both lists will have exactly the same content. If you want to exclude
networks, select them in the right list and press I<Delete>. You can always
include them again by selecting them in the left list and pressing I<Add>.
You can change the order in the right list by selecting one or more networks
and pressing the I<up> or I<down> arrows.

If you want the same selection and order for all providers, you can simply
copy your order and selection with the I<copy> popup menu;  this menu
contains a list of all known providers.  Note that if you copy from a
provider with less (or different) networks, those networks that are
missing in the other provider's database appear at the end of the network
selection in the right listbox.

At the bottom of the dialog window there's an entry field that allows to
limit the program listing for a network to a given time frame. For example
if you receive Arte only from 19:00 until 07:00 o'clock, select Arte either
in the left or right list, then enter "19:00" and "07:00" in the fields
(make sure to always use 4 digits and the separating colon).  Programmes
that fall completely outside that window will not appear in the browser
window.  If you want to undo the limitation, enter 00:00 until 00:00
or any other equal time values.

Note: you can also operate this dialog (and all other dialogs with similar
listbox selections) with he keyboard: use the TAB key or the mouse to move
the keyboard input focus to the left or right listbox. Use the cursor
up/down keys to select an item; hold down SHIFT to select multiple items.
In the left list, press Return to add a network to the right list. In the
right list, press the Delete key to remove a network, or press CONTROL
and the up/down cursor keys to change the selected items' position in
the list.


=head2 Network names

Open the network names configuration dialog. It's main purpose is to
synchronize the network names between nxtvepg and your TV application.
This is required because the network name is used in communication when
you use the I<Tune TV> remote controls, and as well for channel change
notifications by the TV applications.  For many networks there will be
no need to change anything, but for some there exist different variants,
e.g. in Germany "Super RTL" vs. "S-RTL" or "MDR3" vs. "MDR".

If you're not using UNIX, you first need to select which TV application
you want to synchronize with and where the configuration files are
located.  This is done in the I<TV app. interaction> dialog in the Configure
menu (see L<"CONFIGURATION: TV application interaction">).

Another use of this dialog is to make network naming consistent across
all Nextview providers. The names you specify here will be used in the
programme listbox and all filter menus, independently of the provider.

On the left side of the dialog you find a list of all networks of
all known Nextview providers. The names used here are the ones you
configured before, or if you haven't done so yet, the names that match
the station names of your TV application best. Unmatched names are
marked red.  If no TV application is configured, each network's name
is taken from the first Nextview database which covers this network,
in order of your provider selection history.

On the right side, you're offered four ways to change the name: topmost
is a simple entry field where you can type in an arbitrary name. Below
is a popup menu which contains all network names defined in your TV app.'s
channel table.  Below is a button which contains the one name in your
TV app.'s channel table which resembles the current string in the entry
field most, or I<none>. It's marked red
until it's identical to the entry field. You can copy the name to the
entry field by clicking the button. Below is a listbox with the original
names used in the various provider databases. When you select a name from
the menu or the listbox, it will be copied into the entry field and the
network name list on the left. If you want to save the changed list,
leave the dialog with I<Save>, else use I<Abort>.

Note: if you receive channels that carry multiple networks, e.g.
in Germany "Arte / Kinderkanal", it's recommended to include all
networks' names in the network name on side of the TV application,
separated by a slash.  The slash is recognized as separator by nxtvepg
and all resulting segments can be used as network names.


=head2 Context menu

Open the context menu configuration dialog which allows to add references
to external commands to the context popup menu. (See also L<"CONTEXT MENU">.)
At the top of the dialog window there is a list of all currently defined
command titles. When you open the dialog for the first time, it'll be empty.

Below the list there are two text input fields which allow to modify or
create new commands. The field labeled B<Title> defines the text which will
be included to the popup menu.  The field labeled B<Command> defines the
command line to be executed when the entry is selected in the popup menu, with
possible placeholders enclosed in ${} which are replaced by parameters of the
currently selected programme in the browser listbox. After the substitution
and after appending an ampersand '&' sign to allow asynchronous execution
(UNIX only), the command line is passed to a shell via the system(3) function.

When you press the menu button I<Copy Example> a list pops up which contains
a few example commands which can be copied into the title and command entry
fields.  To save a new or modified title and command, you have to press either
the I<New> or I<Update> button and leave the popup with I<Ok>.  Use I<Delete>
to remove an entry from the listbox; the buttons with up/down arrows to change
the ordering.  Use I<Clear> to clear the entry fields, e.g. before you create
a new entry.

The following is a list of formal variables (i.e. placeholders) which
are substituted in the command line with parameters of the selected title upon
invocation of the external command. The meaning of the variables should be
self-explanatory, except possibly for CNI, which is a hexadecimal network code;
and e/p_rating which are editorial and parental rating respectively.

  ${title}
  ${network}
  ${start}
  ${stop}
  ${relstart}
  ${duration}
  ${CNI}
  ${description}
  ${themes}
  ${VPS}  or  ${PDC}
  ${e_rating}
  ${p_rating}
  ${sound}
  ${format}
  ${digital}
  ${encrypted}
  ${live}
  ${repeat}
  ${subtitle}

The keywords can be followed by a colon and an output format specification.
In case of the start, stop and VPS/PDC times, all options defined in the
B<strftime(3)> manpage are available; default is %H:%M-%d.%m.%Y (hour, minute,
day, month, year). In case of relative start time and duration, you can choose
between minutes (default) and seconds by appending "m" or "s". For themes
you can choose between numerical and textual output by appending "n" or "t".
For all other variables the modifiers are currently ignored.

On UNIX the substrings which replace the formal variables are enclosed in
single quotes to protect them from interpretation by the shell. Single quotes
inside the substituted string are correctly escaped.

Example: The command line

  plan ${start:%d.%m.%Y %H:%M} ${title}

could for example result in

  plan '22.08.2001 13:05' 'Käpt'\''n Blaubärs Seemannsgarn'

to be passed to the Bourne Shell (F</bin/sh>).

On Windows there's a special prefix C<!wintv!> which tells nxtvepg to
send this command line to a connected TV application (see
L<"CONFIGURATION: TV application interaction">).  For example

  !wintv! setstation ${network}

would create a command that switches the TV app's channel to that of
the currently selected programme (i.e. the same what the I<Tune TV>
button does).  When no TV application is connected, such entries are
automatically disabled.


=head2 Filter shortcuts

Open the filter shortcut dialog to rename, reorder or delete shortcuts. 
You have to press the I<Update> button to save any changes for a shortcut
and then close the dialog with I<Save>.
See L<"FILTER SHORTCUTS"> for more details.


=head2 Themes language

Select the language for programme themes (i.e. content category, see
L<"FILTERING">) in the main window and the filter menu.  By default
it's set to default, in which case the language is derived from the
selected provider's database.  Please note that the language of the
menus, help etc. currently can not be changed from English.


=head2 Show shortcuts

Toggle visibility of the shortcut listbox.


=head2 Show networks

Toggle visibility of the network filter listbox.


=head2 Show status line

Toggle visibility of the status line at the bottom of the browser window.


=head2 Show column headers

Toggle visibility of the browser listbox column header menu bar.


=head2 Hide on minimize

Windows only:
When this option is enabled, the main window's entry in the task bar
is removed when it's minimized or when the program is started with
the I<-iconic> command line switch.  Instead an icon is added to the
system tray in the task bar.  A double-click on the tray icon deiconifies
the main window.  A click with the right mouse button opens a little
popup menu.  The entries in this menu have the same meaning as the
equally named ones in the control menu (see L<"CONTROL">).



=head1 FILES

=head2 Files used on UNIX systems

=over 4

=item B<$HOME/.nxtvepgrc>

Configuration file where all personal settings are stored. Per default
this is created in your home directory, but a different path and file
name can be specified with the B<-rcfile> option.


=item B</usr/tmp/nxtvdb/nxtvdb-####>

Directory containing one file for each provider's database.
Can be changed with the B<-dbdir> command line option.
The last 4 digits of the file names are the hexadecimal CNI (Country
and Network Identifier) of the provider.


=item B</dev/vbi0>, B</dev/vbi1>, etc.

Device files from which Nextview data is being read during acquisition.
The index postfix can be specified with the B<-card> command line option.


=item B</dev/video0>, B</dev/video1>, etc.

Device files which are needed to set input source (e.g. TV tuner or one of
the composite or S-Video sockets) and tuner frequency for VBI reception,
unless you choose the passive acquisition mode. The index postfix can be
specified with the B<-card> command line option.

The device is only kept open during a provider search. Else, it's just
opened shortly to set the input source and tuner frequency. If the device
is busy (e.g. while you watch TV), acquisition starts on the currently
selected channel and automatically follows any externally controlled
changes (this will be reported, e.g. in the status line at the bottom
of the browser window, as I<forced passive> acquisition mode).


=item B</tmp/.vbi0.pid>, B</tmp/.vbi1.pid>, etc.

This file contains the process id of the Nextview decoder (or the
acquisition slave process unless threading is used) whenever a vbi device
is kept open. The process can be forced to free the device by sending
it signal SIGHUP, e.g. from a wrapper script around a teletext decoder.
An example which works with sh, bash or tcsh:

   kill -HUP `cat /tmp/.vbi0.pid`

Note that the daemon is not kept alive when acquisition is disabled,
so that sending HUP equals sending TERM.  You can restart acquisition
by starting a new daemon.  The browser attempts to reconnect every
10 seconds when the connection was broken, but you can also trigger
an immediate reconnect be signalling it a HUP.

To restart acquisition in non-daemon mode, signal again with HUP,
either to the acquisition slave process or the browser process.


=item B</tmp/nxtvepg.0>

This non-regular file (socket) is created by the daemon to allow
local client connections via UNIX domain sockets.  The same socket
can be used for more than one client connection.  It's deleted when
the daemon terminates (unless the daemon crashes or receives an
uncatchable signal like KILL).


=item B<$HOME/.xawtv>, etc.

This file belongs to the TV viewer F<xawtv>. It's not required or
created by nxtvepg. But if it exists, it will be used in the
EPG scan (for a fast scan mode where only the channels defined in
this file will be checked) and in the network name configuration
dialog.

=back


=head2 Files used on Windows systems

=over 4

=item B<nxtvepg.ini>

Configuration file where all configuration and personal preference settings
are stored. By default this is created in the working directory, but a
different path and file name can be specified with the B<-rcfile> option.


=item B<nxtv####.epg>

One file for each provider's database is created in the working directory
or the one given with the B<-dbdir> command line option.
The last 4 digits of the file base names are the hexadecimal CNI (Country
and Network Identifier) of the provider.  You must not change the name
of this file, or nxtvepg will refuse to load the database.

=item B<vbi_map.dat>

This hidden file is used to set up shared memory to allow information
exchange between nxtvepg and an attached TV application.  It's
automatically removed when nxtvepg terminates and should never be
accessed (i.e. being written to or removed) by external applications.
The file is not created when TV app. interaction is disabled (see
L<"CONFIGURATION: TV application interaction">).


=back


=head1 SEE ALSO

For in-depth information about Nextview please refer to the specifications
ETS 300 707 (data structures and basic principles), ETS 300 708
(transmission protocol) and ETR 288 (code of practice). These specs
are available from http://www.etsi.org/

You can also have Nextview directly inside your television set - check
out the catalogues of Grundig, Loewe, Metz, Sony, Philips, Thompson or
Telefunken. However be aware that not all models do support the same
set of Nextview features.

=head1 KNOWN BUGS

Under Windows there's a risk of system crash ("blue screen") when the
application is terminated by force, e.g. via the task manager. This
is unavoidable because in this case there's no chance to stop the
driver and hence the TV card continues to capure data into RAM.
In normal operation this should be very unlikely because all software
exceptions (e.g. page faults) and shutdown messages are caught and the
driver then stopped before the exit.

=head1 REPORTING BUGS

Feel free to mail any bug reports to me, but please make sure that
(a) you have the latest version of this software, (b) it's not already
in the TODO file and (c) it's not just an error in your provider's EPG
transmission. And please note that I've got no telepathic capabilities,
so be comprehensive in describing your problem. See the README file
for instructions on which information must be included in a bug report.

=head1 AUTHOR

Thorsten "Tom" Zoerner, Erlangen, Germany.

Email: tomzo (at) users (dot) sourceforge (dot) net

Many thanks to Thierry Ménétrier for his valuable feedback;
to Matthieu for the French translation of PDC theme descriptors;
to E-nek for the DScaler driver port and cooperation
in develepment of the TV application interaction;
to John Adcock for the DScaler driver;
to Jan Schuster for beta testing nxtvepg 0.7.0;
to Mario Kemper for the NetBSD port and early beta testing;
to "Mario's brother" for beta testing the first Windows port;
to Gerd Knorr for xawtv and maintaining the Debian and SuSE nxtvepg packages;
to Ralph Metzler for his teletext decoder;
to Edgar Toernig for the Latin-1 conversion tables in alevt;
and last but not least to the authors of bttv and v4l for their excellent work,
and the authors of the Cygwin GNU and XFree86 port, without which nxtvepg
would never have been ported to M$ Windows.

=head1 COPYRIGHT

Copyright (C) 1999, 2000, 2001, 2002 by Thorsten Zoerner.
All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License Version 2 as
published by the Free Software Foundation, e.g. at
http://www.fsf.org/

This program is distributed in the hope that it will be useful, but
B<WITHOUT ANY WARRANTY>; without even the implied warranty of
merchantability or fitness for a particular purpose. See the
file F<COPYRIGHT> for more details.