# VideoteXt

    ============================================================================
    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
      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
      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
      Sets the timeout in seconds, after which the search for a page will be
      cancelled (valid range: 1-600, default: 60).
    -i
      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
      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:
    Snail-mail: Martin Buck, Paukengasse 2, D-89077 Ulm, Germany