This file contains informations about installing and using DataVision.

Introduction
------------

DataVision is a window surfaced table plotting program based on tcl/tk.
The current version supports plotting of tables in 2-d diagrams in several
representations.
Some features of DataVision are:
   -loading tables from files
   -importing tables from 'wosql' (*)
   -loading/saving configurations
   -plotting tables as curves
   -zooming plots
   -exporting plots as postscript files (eps) or sending plots to printer

(*) wosql (Windowing Oracle SQL) is an interactive SQL environment for Oracle
    databases. DataVision has been tested with wosql version 2.2 .


Requirements
------------
   To run DataVision, you will need at least tcl7.3/tk3.6/tclx. This package
   is normally called 'wishx'.

   I have not tested the program with any other tcl/tk-version.


Installation
------------
   If you are lucky, the installation GUI will work on your system.
   Just type 'dvinstall' (X-windows must have been started) and a window
   appears, in which you can type in the desired location of

        1) the startscript (normally somewhere in /usr/bin or /usr/local/bin )

        2) the base directory of misc files

        3) the base directory of program code

        4) the base directory of help pages

        5) the base directory of testdata

   You can start the installation by clicking on the button 'install'.
   After successfull installation you can remove all files, that have been 
   extracted from the tarfile.
   You can start DataVision by typing 'dv'. 

 Comments:
   The installation program will not overwrite any file ! 
   

Bug reports
-----------
   If you run into trouble while installing or using DataVision, please send 
   a bug report to:

   boese@ipf.bau-verm.uni-karlsruhe.de

   This report should contain at least

      - the system you are using
      - your tcl/tk/tclx version
      - a description of the problem

   Of course, any other kind of comments will be welcome.


How to use
----------
   Unfortunately, the help pages have not been written yet.
   However, there exists a german users-guide as a tar archive of a
   postscript file ( which had been added to this package in
   './anleitung/anleitung.tgz)'.

   Here is a brief description of DataVisions options:


   File:
     File operations can be activated with this menu.

     load data...:
        Load table from an ASCII file;
        the format of that file should look like a databank output:
        DataVisions expects titles of columns in the first line, a separator
        in the second line and data elements in all other lines.
        Titles and data elements must be seperated by 'white space', so 
        normally blanks and/or tabs can be used as separators.
        The number of titles and data elements in each line must be the same,
        but is not limited.
        The second line may contain anything - it will be overred.

        Example of valid table:

              time    value1    value2
              ------------------------
              12       1.3       1.7
              13       0.12      14
              17       0.13      18
              18       0.19      22

     concat data...:
        concats table from an ASCII file;
        a new table will be attached to the right of an already existing one.

     load configuration:
        loads a configuration file;
        a configuration may contain settings (e.g. colors of curves, titles,
        etc.) and loaded data. This option is usefull to retrieve an older
        session.
        
     save configuration...:
        saves a configuration file; 
        the current settings and loaded data will be saved.

     save startconfig:
        saves a configuration file as an initialisation file;
        DataVision will load that file after each start and after each reset.
        If no start configuration file exists, the program will use a
        hard coded one.

     delete startconfig:
        deletes the current start configuration file.

     reset:
        resets the program;
        all windows except the main window will disappear and the current
        start configuration will be retrieved.

     quit:
        leaves the program


   Import:
     You can directly import data from the 'wosql result' window.
     Please remember: If your 'wishx' is compiled in 'secure' mode (default),
     then 'Xauthority' must have been installed, or the 'xhost list' must be
     empty to use this option.

     get data from wosql:
        directly imports tables from the 'wosql result' window; for this 
        feature, 'wosql' must have been started.

     concat data from wosql:
        directly concat data from the 'wosql result' window; a new table will
        be attached to the right side of an already existing one.
        For this feature, 'wosql' must have been started.


   Option:
     Some general options can be set with this menu.
     (see 'file: save startconfig') to make these settings permanent)

     set window colors:
       set the windows colors of the program

     show table:
       this checkbutton switches the table window on or off;
       normally the loaded table is shown there.


   Domain:
     This menu sets the kind of depiction. The resulting mode has effects on
     some further menus.

     index:
        every selected column (see 'Data: select curves) will be shown as one
        curve.

     real:
        every selected pair of columns (see 'Data: select curves) will be shown
        as one curve. The first column of the pair contains the X-coordinates,
        the second one the Y-coordinates. Values of one row of a selected pair
        will be interpreted as an coordinate.

     date (yymmdd):
        this mode works nearly as the real mode with the exception that the
        X-coordinate will be interpreted as a date in the format 'yymmdd'.

     time (hhmm):
        this mode works nearly as the real mode with the exception that the
        X-coordinate will be interpreted as a time in the format 'hhmm'.


   Data:
     This menu can be used to select 'what' data will be visualized.

     select curves...:
        1) mode == 'domain index':
           a window with a listbox will come up, where all titles of drawable
           columns are shown. The columns of selected titles will be shown as
           curves.
        2) mode != 'doman index':
           A window with two listboxes will come up. The first listbox contains
           the titles of columns. Now you can select domain (X-koordinates)
           and codomain (Y-coordinates) of the curves, which have to be
           visualized. The pairs of selected titles will be shown in the second
           listbox.
           A little bit more formal: A pair of selected titles defines a
           relation, where the titles represents domain and codomain, 
           respectively. 

     9999.99 means undefined:
        1) mode == 'domain index':
           Values equal to 9999.99 will be taken as an 'undefined value'.
           This value will not be shown as part of the appropriate curve.
           if 'Diagram:diagram layout:misc:show undef' is set (default), then
           this undefined value will be marked with an oval at the upper end
           of the diagram.
        2) mode != 'doman index':
           If the second component of a coordinate is equal to 9999.99, then
           this coordinate will be treated as an undefined one. This value
           will not be shown as a part of the approprite curve. If
           'Diagram:diagram layout:misc:show undef' is set (default), then
           this undefined coordinate will be marked with an oval at the upper
           end of the diagram.

      set undefined value:
           Set the value, which should be interpreted as an undefined one.

    Diagram:
      This menu can be used to select 'how' data will be visualized.

      diagram layout...:
         Set options for the layout of the diagram, e.g. :
           -set titles
           -toggle autoscaling on/off
           -set the area of X/Y axis
            (only possible, if autoscaling is switched off)
           -choose, if a column has to be shown as X-scaling
            (works only in index mode)
           -set size of diagram
           -set kind of representation (as Points,Polygon,Bspline)
           -set color of curves
           -toggle Grid on/off
           -mark undefined values

      show diagram...: 
         plots the diagram in a window;
         it is possible to zoom a plot by dragging the left mouse button
         inside the plot - a new zoom window appears showing the marked 
         area. It is also possible to zoom inside that zoom again, but no
         new window will come up.
         Internally, a zoom diagram gets an own data set, so you can change
         the representation for that zoom.

         Some buttons are added to the diagram for faster handling:
           layout...: shortcut for Diagram: diagram layout...
           curves...: shortcut for Data: select curves...
           output...: this button invokes a menu, in which you can export the
                      plot as a postscript file (eps) or send it to a printer.
                      A resscaling can be done here. The orientation of the
                      plot can be changed and the output mode can be set to
                      'Color' or 'Greyscale'.
           cancel:    this button closes the diagram window


   Help:
     This menu can be used to get help with the use of DataVision.

     about:
        A window will be shown, which displays information about DataVision

     help:
        This menu invokes 'tclhelp', which had been patched for use with
        DataVision.
        Unfortunately, the help pages have not been written yet.


Last but not least i hope, this README will do for now. 
