============================================================================
Documentation for VideoteXt V0.5           Copyright (c) 1994-95 Martin Buck
============================================================================


With this program and the included driver it's possible to receive, display
and store videotext-pages received from a videotext-interface. There's a
commandline-version that can be used mainly for batch-operation and an
interactive version using the X-Window-System and the XView-toolkit. You
also can use VideoteXt to display pages from INtv's videotext-service in the
WWW.



Installation
------------

If the videotext-device-driver (at least version 1.4) isn't installed on
your system, you have to do this first (otherwise, the required include-file
won't be found). If you use a "release of the week", you should always
install the accompanying driver, because the API may change without changing
the driver's version number.

To install the driver, cd to the directory 'driver' and follow the
instructions in 'README'. If you just want to test VideoteXt or if you just
want to use it for viewing INtv-pages, you can compile it without installing
the driver. For this, you have to uncomment the line 'DRIVER_KLUGE =
-Idriver' in the Makefile.

Except for the installation-directories and the include-/library-directories
for OpenWindows you shouldn't have to change anything in the Makefile. To
compile VideoteXt, just type 'make'. You need an Ansi-C-compiler (I tested
gcc 2.5.8 and Slowlaris-2-cc), GNU-make, GNU-awk and bdftopcf for this.
Also, you should have the XView-libraries and header-files (at least version
3.2) installed (e.g. from ftp://sunsite.unc.edu/pub/Linux/libs/X/xview*).
The XView-libraries for XFree86 >3.0 from Slackware 2.1 and 2.2 are buggy
and shouldn't be used.

To install VideoteXt, type 'make install'; to test it before installation
you have to add the font-directory to X's font-path (with 'mkfontdir fonts'
and 'xset +fp `pwd`/fonts'), so the X-version is able to find its fonts.
After instllation, you should check that the directory where VideoteXt
installed its fonts is in X's font-path ('xset q'). You also have to type
'xset fp rehash' once, because otherwise the X-server will find the fonts
only after restarting it.



Using VideoteXt (XView-version)
-------------------------------

VideoteXt can be used interactively with the XView-toolkit. Its main
features are TOP-text-support, which makes it possible to receive all
videotext-pages in advance and to display them immediately when you type the
page-number; you also can find unknown pages fast with the page-descriptions
provided by TOP-text. There's also a hotlist for every station, that allows
you to display your frequently used pages very fast. Videotext-pages can be
saved and loaded; you also can export them in GIF-, PPM-, ASCII- and
PostScript-format.


Some notes on the user-interface:

VideoteXt follows the usual XView-conventions, i.e. values entered in
dialog-windows become active after you press the 'Apply'-button. Also, you
have to closes these windows explicitly be pressing the 'Close'- or the
corresponding window-manager-button (in fileselect-boxes these buttons are
called 'Open'/'Save' and 'Cancel', but they are handled like
'Apply'/'Close').

The popup-windows may be positioned automatically (menu
Options->Window-layout), but I had to use some dirty tricks to find out the
size of the window-manager's decoration, so this might not work with every
window-manager (up to now only gwm (generic window manager -- I don't think
that anybody really uses it :-) failed). In this case, you can tell
VideoteXt the size of the wm's decoration in the config-file (see below).

There are hotkeys for some buttons, which are mentioned in parentheses
below. Many of them can also be used without Meta, but some of them collide
with hexadecimal digits used for the page-numbers -- for these you have to
use Meta. 'Reset' and 'Exit' can also be used only with Meta for security
reasons.


User-interface-elements:

The number of the currently displayed page is shown in the upper right
corner. If it is a multi-page, the subpage-number and the number of subpages
currently in the cache will be shown additionally. If the current station
uses TOP-text, the number of existing subpages will also be displayed.

With the '+'- and '-'-buttons (+/-, cursor up/cursor down) you can
increase/decrease the page- and subpage-number.

To search for a page, you have to enter the number into the 'Page'-field
(you can also use hexadecimal numbers in the range 100-8FF). If you press
the 'Search'-button (Return), the serach starts in the foreground; with
'Search bg' (Meta-Return) the page will be sought in the background and
stored in VideoteXt's internal cache. If you request this page the next
time, it will appear immediately. You can also start the search by clicking
on a 3-digit-number somewhere on the page (button 1 searches in foreground,
3 in background). Searching for a certain subpage is done by entering its
number (1-7F) in the 'Subpg.'-field before pressing 'Search'. To switch back
to continuous mode (i.e. the currently transmitted page will be displayed
immediately) you have to press 'Cont.' (Meta-C).

The current page can be freezed by clicking the 'Stop'-checkbox (Meta-S).

With 'Reveal' (Meta-E) you can reveal the hidden parts of a page.

The current status of the data-acquisition-units is displayed on the left
side of the footer; on the right side the automatically recognized
station-name is shown. If 'Unknown charset' appears here, the encoding of
the currently used charset is unknown (this happens e.g. with TRT Int.). If
you have information about unsupported encodings, please tell me.


The following functions are available in the 'File'-menu:

'Load' loads a page stored in VideoteXt's internal format from disk. Because
of changes in this format, pages stored with versions prior to 0.4 can't be
loaded.

'Save' saves the currently displayed page in the internal VideoteXt-format.
A filename consisting of the station-name, the page- and subpage-number will
be suggested automatically. To write the output to a pipe instead of a file,
use '|' as the first character in the filename.

With 'Export' you can export the current page in different formats. If you
use the graphics-formats GIF (GIF87) or PPM (binary), the current font-size
will be used. When exporting in ASCII-format (with ISO-latin-1-font),
graphics- and some special characters will be lost. For PostScript-output,
you can choose between color-, black&white- or black&white inverted
PostScript. The exported files follow the EPSF conventions, so you can print
them either directly or include them in other documents. By pressing the
'Use default printer'-button, you can insert the prining-command matching
the currently selected format into the input-field (settable in
'Options->Misc options'). You may also use a pipe here like in the
'Save'-window.

With 'Reset' (Meta-R) you can erase the internal cache and VideoteXt's
history; also the current page will be reset to 100, the search for the
hotlist-pages starts and VideoteXt tries to recognize the current station.
This is alway necessary after switching stations. If all station-names are
entered correctly (see below) and the corresponding option in 'Options->Misc
options' is activated, station-changes are recognized automatically and
'Reset' is not required.

'Statistics' shows some information about the current station (if it
broadcasts TOP-text) and the number and memory usage of the pages in the
cache.

'About' tells you everything you need to know about VideoteXt.

'Exit' (Meta-X) is (besides the close-button of your window-manager) the
"official" way to leave VideoteXt, because changes in the hotlist and the
station-options are saved automatically in ~/.vtx-hotlist. If you leave
VideoteXt by pressing ctrl-c or when an error occurs, your changes will be
lost.


With the 'Gadgets'-menu you can activate the different popup-windows:

'Page history' stores the numbers of the pages you visited. The pages from
the hotlist will be put into the history automatically. You can search for a
page in the history by double-clicking on the number or by clicking on the
'Go to'-button. With the 'Previous'- (Meta-P) and 'Next'-button (Meta-N),
you can jump to the previous/next page in history. The symbols next to the
page-numbers show the status of the corresponding page. The eyes mean that
VideoteXt is searching for the page at the moment; a sheet of paper shows
that the page was received but not yet read; eyes combined with a sheet of
paper show that at least one page is already in cache but VideoteXt is still
searching for it (e.g. for multi-pages). A checkmark combined with a sheet
of paper stands for a page that was already read and a clock means that a
timeout occured for this page and that it is probably not in the
videotext-cycle. With the button 'Index pg' you can jump to the (adjustable)
index-page.

The 'TOP-Text'-window shows (provided that the station broadcasts it) the
title of the current, next and previous page, of the next group-page and the
next block-page. By pressing the 'Next page'- (Page up), 'Prev. page'- (Page
down), 'Next group'- (Meta-G) or 'Next block'-buttons (Meta-B) you can jump
to the corresponding pages. With the 'Overview'- and 'Hierearchy'-buttons
you can get a overview over all pages or a hierarchical display (divided
into block- and group-pages) of the pages for which a description is
available.

The 'Hotlist'-popup shows the hotlist for the current station. This only
works if you already defined the names of all stations. Like in the
history-popup you can jump to pages by double-clicking them or by pressing
the 'Go to'-button. With 'Move up' or 'Move down' you can change the
position of a page in the hotlist which also determines the order in which
the pages are sought for. Pages that are not always broadcast should be put
at the end of the hotlist, because otherwise VideoteXt would have to wait
until the timeout occurs to be able to continue to search for other pages.
With 'Add current' you can add the current page from the main-window to the
hotlist and with 'Remove' you can remove the selected page.

In the 'Select station'-window you can select the current station in case it
can't be recognized automatically. To do this, just double-click on the
station-name or select the station and press 'Apply'. In this window you can
also define the names of the stations you receive. This is necessary so that
VideoteXt can automatically recognize them and use the suitable hotlist. To
change a name just select it and press 'Change Name'. To define a new
station, select 'Unknown' and then press 'Change Name'. In the following
window you can either enter the name manually or read it from the current
header-line by pressing 'Read header'. You should delete everything but the
station's name from this line, because VideoteXt must be able to find the
whole string in the current header line to be able to recognize the station.


In the 'Options'-menu you can change the following settings:

With 'Font' you can change the font size used in the main window. You can
also get another font by simply resizing the window, because VideoteXt
automatically uses the largest font that fits into the window.

'Screen updates' determines the delays between the updates of the
header-line. The higher the speed of the updates, the higher the system-load
VideoteXt produces.

In the 'Window layout'-menu you can change the policy VideoteXt uses when
positioning its popup-windows. 'Centered' should work flawlessly with any
window-manager; the other options which try to put the popups at the border
of the main window may need some adjustments to your window-manager. In this
window you can also control which popups should be opened automatically when
VideoteXt starts and if the TOP-text-window should be opened whenever
TOP-text becomes available.

With 'TV options' you can change the way VideoteXt displays the pages on an
attached TV-screen or disable it completely. Depending on the interface you
own this may or may not work. By clicking on 'Dispay pages on TV' you can
make VideoteXt display its pages on TV. If there's no TV attached to your
videotext-card you should disable this option, because to display the pages,
they have to be sent twice over the I²C-bus which increases system load and
slows down VideoteXt. Normally interlace will only be used when a
videotext-page is inserted into a TV-picture because the page looks better
without interlace. Unfortunately, some TVs/interfaces always need interlace
to produce a steady picture, so you can turn it on for all modes with
'Always use interlace'. With 'Display mode' you can choose whether the pages
will be displayed on the whole screen ('Normal'), inserted into to TV
picture with transparent background ('Transparent') or only subtitles will
be inserted into the picture ('Insert').

In the 'Misc. options'-window you can select whether VideoteXt autmatically
resets itself when it detects a station-change. For this to work you have to
enter all station-names correctly (see 'Select station'). Also, you can
change the commands for printing the different output-formats.

All the above options, which are common for all stations, can be saved with
'Save global options' to ~/.vtxrc.

The 'Station options'-window allows you to adjust some options individually
for every station. Only the options for the currently selected/recognized
station (as shown in the lower right corner) will be affected by changes in
this window. These changes will be saved automatically when you quit
VideoteXt. With 'Page-Timeout' you can change the time (in seconds)
VideoteXt will wait for a requested page until the search is cancelled.
'Top-Text interleave' set the interleave-factor used to search for pages
from the TOP-text-table. The meaning of this value is described below in the
documentation for the '-i'-option of vtxget. For VideoteXt this value should
be slightly higher than for vtxget, because VideoteXt has to display the
pages simultaneously which slows down the search a bit. For stations that
don't broadcast TOP-text you can disable the search for the bascictop-page
with 'Don't search for TOP-Text'. This makes an additional data acquisition
unit available for searching for pages from the hotlist. 'Auto-search pages'
allows you to change the categories of pages that will be searched
automatically in the background if a station broadcasts TOP-text. With
'None' you can disable this search completely, with 'Blocks' and 'Groups'
only block- or block- and group-pages will be searched; 'Normal' searches
for all single pages and 'Subpages' searches for all pages including
subpages. Because searching for multi-pages blocks a data acquisition unit
until all subpages have been received, only normal pages will be sought by
default. With the 'Page-lookahead'-field you can set the number of pages
following the current one that will be searched automatically in background.
If a station broadcasts TOP-text you should set this value relatively low,
because otherwise the serach for TOP-text pages will be delayed too much. In
the 'Index-Page'-field you can enter the number of the index-page that will
be searched after a reset or after pressing the 'Index pg.'-button.


Commandline-options:

You can use all standard XView-options (you can get a list with the
'-help'-option). The '-d'-option allows you to change the device VideoteXt
uses (the default is '/dev/vtx'). Option '-f' will start VideoteXt in
display-only-mode (see below). To get a list of all options, use '-\?'.


Configuration-files:

VideoteXt uses 2 kinds of config-files: 'vtxrc' and 'vtx-hotlist'. It
searches for them in /usr/local/etc and in your home-directory (as '.vtxrc'
and '.vtx-hotlist'). In the system-wide hotlist you should define all
available station-names so that new users can use the automatically. IT
WOULD BE NICE IF YOU COULD MAIL ME YOUR '.vtx-hotlist' IF YOU ADDED SOME
ENTRIES, SO THAT OTHER USERS DON'T HAVE TO DEFINE THEM AGAIN AND AGAIN (many
thanks to Martin Höppner for the station-names broadcast via Astra).

Besides the station-names and the hotlists, the options for every single
station are also stored in 'vtx-hotlist'. In 'vtxrc' only the options all
stations have in common are stored. Normally, you shouldn't have to edit
these files manually, because you can set all options from within VideoteXt.
There is, however, one exception: if the automatic placement of the
popup-windows fails with your window-manager, you have to change the line
'wm_decoration=auto' in '~/.vtxrc' as follows: 'wm_decoration=l,r,t,b'.
l,r,t,b should be replaced by the sizes (in pixles) of the window-manager's
decoration on the left, right, top and bottom side of the popups. If the
windows still don't get positioned correctly, you can move them with
'wm_offset=x,y' in x- and y-direction. Normally, either 0,0 or the sizes of
the left and top decorations should be OK. BTW, I'd like to know if other
window-managers besides gwm cause trouble with the automatic placement.


Using the 'display-only-mode' (e.g. as a viewer for INtv):

When using the option '-f', you also have to pass a filename to VideoteXt. A
videotext-page stored in this file will be read and displayed in
display-only-mode, i.e. you can't receive pages from a videotext-interface
but only load, save or export them. If VideoteXt receives the signal 'USR1',
it will re-read and re-display the given file.

To use VideoteXt for INtv (http://www.ntu.ac.sg/intv/intv_www.html) you have
to tell your WWW-browser to start VideoteXt to display the pages. With
Mosaic and Netscape you have to insert the right entries into
~/.mailcap and ~/.mime-types (if you use Netscape, you probably have to
enter these filenames in Options->Preferences->Helper Applications; if you
use Mosaic there are corresponding resources). The easiest way to do this is
to copy the entries from examples/mailcap and examples/mime.types. Because
it's rather inefficient to start a new VideoteXt for every new page, you can
use the shell-script 'view_vtx', which you should install somewhere in your
path in this case.



Using vtxget (commandline-version)
----------------------------------

vtxget searches for videotext-pages given on the commandline and writes them
to stdout or into a specified directory.

For stations that broadcast TOP-text, you can use 'all', 'allnorm' or
'allsub' instead of page-numbers. This will cause vtxget to search for all
normal and multi-pages, all normal pages or all multi-pages. Depending on
the current station, all normal pages will be found in about 5 minutes;
searching for multi-pages takes substantially more time, because their order
can't be determined.

If you use a single number (between 100 and 8FF) for the page-number, the
corresponding normal page or the next subpage will be searched. Certain
subpages can be requested by appending the subpage-number (between 1 and 7F)
to the page-number and separating them by a dot. All existing subpages may
be requested by searching for subpage-number 0. You can pass as many pages
on the commandline as you like. These pages will be searched sequentially
with all available data acquisition units. If you search for subpage 'l',
the given page will be searched until either a timeout occurs or you cancel
vtxget. This is useful for recording subtitles.

The following commandline-options are available:

-f {iso|ansi|text|vtx|ps|ips|cps}
  Sets the outpt-format of the pages. 'iso' outputs the pages monochrome
  with the ISO-latin-1 charset (default), 'ansi' uses the same charset but
  additionally ANSI-escape-sequences for the colors; 'text' replaces all
  videotext-control-chars by plain text enclosed in braces, which can be
  parsed easily be other programs (all available control-chars can be found
  at the beginning of 'batch.c'). 'vtx' is the format used internally by
  VideoteXt and can be read by the XView-version. With 'ps', 'ips' and 'cps'
  the pages will be written in PostScript-format (either black&white,
  black&white inverted or colored). If the output goes to stdout, lines with
  the following format will be used as seperators between the pages: '{PAGE
  x/y}'. If you only search for a single page, you can filter this line out
  by piping the output through 'egrep -v "^{PAGE.*}$"'.
-o <Directory>
  This sets the directory where received pages will be stored. If you omit
  this option, vtxget will write the pages to stdout (unless you use the
  format 'vtx). If the directory doesn't exist, it will be created
  automatically.
-p <Prefix>
  Sets the prefix that will be prepened before each filename when writing
  the pages to a directory (this is useful, if you want to save pages from
  different stations in a single directory).
-r
  Shows the hidden parts of a page when using one of the formats 'iso',
  'ansi', 'ps', 'ips' or 'cps'.
-h
  Prepends a header showing the videotext-control-bits to the output for all
  formats except 'vtx'.
-t <Timeout>
  Sets the timeout in seconds, after which the search for a page will be
  cancelled (valid range: 1-600, default: 60).
-i <Interleave>
  Adjusts the interleave-factor used to search for pages from the
  TOP-text-table (valid range: -100-100, default: 20). This factor
  determines, how many pages will be skipped when searching for successive
  pages. This is necessary, because the transmission over the I²C-bus is
  slower than the videotext-broadcasts of most stations. If no pages would
  be skipped, vtxget would have to wait for a whole cycle to receive the
  next page. If only a few pages per cycle are received, you should increase
  the interleave-factor; if there are delays of several seconds between the
  pages, you should decrease it. The default of 20 should be suitable for
  most stations and a machine with a moderate load. If a station broadcasts
  its pages in the reverse order, you should use a negative
  interleave-factor (e.g. for arte or Premiere).
-v
  Causes vtxget to interpret its commandline-arguments as filenames instead
  of page-numbers. These files will be read and output in the selected
  format. This allows you to use vtxget as a filter, for example to print
  already received pages.
-d <Device>
  Sets the device vtxget uses to receive the pages (default: /dev/vtx). If
  you only have one videotext-interface, you normally shouldn't need this
  option.
-\?
  Outputs a short help for the commandline-arguments and -options.



Copyright
---------

This program is free software and can be used and distributed under the
terms of the GNU General Public License (file COPYING). I can't guarantee
that it will work or doesn't do bad things[tm] to your machine.


BTW, is there anybody willing to write a little program for creating
video-titles (using a SAA5246 and my driver)? Also, a terminal-based,
interavtive videotext-decoder would be nice. Volunteers?


Have fun with this program,
Martin Buck

Please send bug-reports, new fonts, suggestions, donations to:

Internet: <martin.buck@student.uni-ulm.de>
Snail-mail: Martin Buck, Paukengasse 2, D-89077 Ulm, Germany
