   Thank you for installing the GTKWave Beta Release for MS-Windows.

		** PLEASE READ THIS FILE CAREFULLY **
		**     GTKWave IS BETA SOFTWARE    **

   This release is intended for users familiar with both Wave for Unix and
MS-Windows. Most functions of Wave for Unix are available, but some functions
may not work on some versions of Windows. It is strongly recommended that you
install the free Cygwin "Unix-like" environment from www.cygwin.com (see
section 2.2 below).

   GTKWave is designed for 32-bit MS-Windows operating systems (eg. Windows
9x/ME/NT4/2000).  GTKWave will not work with Windows 3.x or Windows NT3.
GTKWave should work with the upcoming Windows XP, but has not been tested.

   Please write to Isaac Henry (ihenry@physionet.org) for further information
or to report bugs; also, please write to Isaac if you attempt to run GTKWave
under Windows XP.

   GTKWave also works under Linux and is readily portable to other versions of
Unix.  See README-UNIX.TXT if you wish to use GTKWave under any version of
Linux or Unix.


1. Important Information for Users

1.1 Running GTKWave

   GTKWave can be started from the Start menu, Programs>Wave>Wave, or from the
MS-DOS prompt (by typing 'gtkwave').  If started from the command line, GTKWave
will accept the switches (command-line arguments) outlined in the Wave User's
Guide (see section 1.6). If run with no switches, GTKWave will start with no
record loaded, which is the default behavior if started from the start menu.

   If you start GTKWave from the MS-DOS prompt, GTKWave's current directory is
the same as MS-DOS's current directory (normally shown in the MS-DOS prompt).
If you start GTKWave from the Start menu or by clicking on its icon, its
current directory is the directory specified by its 'Start in' property
(right-click on the icon to view the property list).  The current directory is
significant since any files created by GTKWave (edited annotations, results of
analyses) will generally be written there.

1.2 Viewing Records

   Please remember that record names are NOT file names!  (See
http://www.physionet.org/faq.shtml#record-names if the difference is not clear
to you.)

   To view a record, the WFDB path must include the location(s) of the files
belonging to the record.  By default, the WFDB path includes the current
directory (see section 1.1), then WAVEROOT (see section 2.1), and finally
PhysioBank (http://www.physionet.org/physiobank/database).  If you wish to use
GTKWave to read local files, either put them into one of these directories, or
add the names of the directories where they are located to the WFDB path.  If
you wish to read records directly from PhysioBank, simply prefix the database
directory name, followed by a forward slash (/), to the record name (e.g.,
'mitdb/100').

   If you need to change the WFDB path, see section 2.1.

			** IMPORTANT **

   Even though Windows ignores character case in local file and directory
names, you must be careful to use the proper case (usually lower case) in all
record and annotator names and in remote directory names (those beginning with
http: or ftp:).

1.3 Editing Annotations

   Editing annotations should be possible on most systems.  A three button
trackball or mouse is strongly recommended; if you are using special mouse
software (like Logitech MouseWare(tm)) you must disable special functions on
the middle button.  If you have a two button mouse, the action of the middle
button can be achieved by pressing <F2>.  Note, however, that <F2> does not
work on some Windows 2000 systems, and in such cases you must use a three
button trackball or mouse.

   Many users who use Wave heavily for annotation editing prefer trackballs,
since the act of clicking the button (used to insert or move an annotation) is
less likely to disturb the position of the cursor when using a trackball than
when using a mouse.

   Your edits are written to a copy of the annotation file that you opened;
they do not replace those annotations.  Your edits are normally written to the
current directory (see section 1.1); if the original annotation file was also
read from that directory, a tilde (~) is appended to its name.  If a file with
that name already exists, it will be overwritten.  If you want to keep more
than one level of backup, you must do so manually.

   An important exception to the rule that annotations are written to the
current directory occurs if you have used a directory name as part of the
record name, as suggested in the previous section.  In this case, be sure that
the current directory contains a subdirectory with the same name before
beginning; your edits will then be written into this subdirectory.  For
example, if you wish to edit the 'st' annotations for record 'slpdb/slp60',
create a directory 'slpdb' in the current directory before starting.  Your
edits will then be written to 'slp60.st' in the 'slpdb' directory you have
created.  (In the next release of the WFDB library, if the subdirectory doesn't
exist, the library will try to create it, so that you won't have to do this
manually.)

1.4 Analysis Menu

   Analysis functions are possible on most systems, but there is no native
(Windows-like) interface to these functions at this point, and most of them
will not work within an MS-DOS shell.  In order to use the existing analysis
menu (defined in wavemenu.def and taken directly from the original Wave for
Unix), install Cygwin (see section 2.2), to get the proper environment for the
scripts to run.  You may also write your own analysis menu using MS batch
commands.
   
   The analysis scripts are based on command-line tools from PhysioToolkit.  A
set of PhysioToolkit binaries is provided with GTKWave. If you already have
PhysioToolkit binaries installed elsewhere, you may remove the duplicates from
the Wave directory, but be sure to set your PATH accordingly.

   External graphing functions (such as heart rate plots) are currently
dependent on plot2d, a shell script (batch file) provided with GTKWave that
invokes gnuplot, which is available for Windows but not included in the GTKWave
package (get it from http://www.gnuplot.org/).  gnuplot has not been tested for
use with GTKWave.  If you would like to set up gnuplot, please contact Isaac
Henry (ihenry@physionet.org), for more information.

   Alternatively, plot2d can be replaced by plt, which is available from
http://www.physionet.org/physiotools/plt/.  If you would like to set up plt for
use with GTKWave, please contact George Moody (george@mit.edu).

   Under Windows 9x/ME, GTKWave uses the Win95Cmd.exe program as a shell. This
program is necessary because Windows 9x does not come with a "real" shell.  If
you wish to use the analysis functions, however, you should install Cygwin (see
section 2.2), and use Cygwin's bash shell (bash.exe) rather than Win95Cmd.exe.

1.5 Printing

  At this time printing is not supported.  Future versions of GTKWave will
support the creation of PostScript files and PostScript printing.

1.6 The Wave User's Guide

   GTKWave is based on George Moody's original Wave, for Unix systems. You can
find George's manual, the Wave User's Guide, at
http://www.physionet.org/physiotools/wug/wug.htm (where you can read it online
or download a ready-to-print PostScript version).  In most cases, the manual
applies to GTKWave, although the illustrations show the original Unix version.

   If you find a difference between GTKWave and what is described in the Wave
User's Guide (other than a cosmetic difference in the user interface elements),
please check in the GTKWave Beta Notes
(http://www.physionet.org/physiotools/beta/wfw/notes.shtml) to see if this
difference has already been reported.  If not, please send George a note
(george@mit.edu), citing the page number in the printed Wave User's Guide, or
the exact URL in the online version.  Indicate what is different in GTKWave,
and which version of Windows you are using.

2. Notes

2.1 Environment Variables

   To use GTKWave as intended, these environment variables must be set
appropriately:

  WAVEROOT	the name of the directory that contains GTKWave's
		initialization files
  WFDB		A list of locations where GTKWave's input files are kept
  WFDBCAL	The name of GTKWave's calibration file

These variables are set to reasonable defaults during installation.

   Usually, the value of WAVEROOT will be the name of the directory in which
GTKWave itself is installed, by default 'C:\Progra~1\Wave'.

   GTKWave searches the list of locations specified by the value of WFDB (the
"database path") in order when you ask it to open a new record or annotation
file.  The first component of the path should usually be '.' (i.e., the current
directory); since output files (such as edited annotation files) are normally
written to the current directory, it is necessary to include '.' explicitly if
GTKWave is to be able to find and read these files subsequently.  Usually,
WAVEROOT should be the second component of WFDB, so that the calibration file
(see below) can be located when needed.  Other components can include the names
of local directories (these should usually include drive specifiers, as in
'c:/data/ecg') as well as directories on remote web or FTP servers (such as
'http://www.physionet.org/physiobank/database').  Use forward slashes (/)
rather than backslashes (\) within WFDB, as within record names.  The value of
WFDB is simply the list of locations, separated by semicolons or spaces; for
this reason, components of WFDB may not include embedded semicolons or spaces
(e.g., use 'C:/Progra~1/Wave' rather than 'C:\Program Files\Wave').

   GTKWave uses the calibration file named by WFDBCAL to determine the relative
display scales for signals of different types.  By default, WFDBCAL specifies a
standard calibration file, named 'wfdbcal', which is installed in WAVEROOT when
you install GTKWave.

   The values of WFDB and WFDBCAL can be set temporarily within GTKWave from
the File:Load dialog; be sure to hit the Enter key after you finish (this is
behavior inherited from Wave for Unix, and will be fixed in the next release).
Changes made in this way are not saved between sessions.

Setting environment variables in Windows:

   Note: In Windows 9x long file names should be shortened in variables.  For
   example, "C:\Program Files\Wave" becomes "C:\Progra~1\Wave" (use the first
   six letters of the directory or file name and append "~1"). In WinNT/2000,
   long file names are OK, but embedded spaces cannot be used within WFDBCAL or
   within components of WFDB, as noted above.  Please also heed the warning
   about character case in section 1.2 above.

   The following examples assume that you have allowed the installer to use
   the default GTKWave directory, "C:\Program Files\Wave".

  ** Windows NT **

   Under NT, environment variables are set in "system properties". Login as
   Administrator (or as a user with administrator privileges), right click on
   "My Computer", select "Properties" and go to the "Environment" tab.  Look
   for PATH in the list of "System variables", append ";C:\Program Files\Wave"
   to the end, and "set" the variable.

   To add WAVEROOT, WFDB, and WFDBCAL, select any variable from the "System
   variables" list, rename the variable to WAVEROOT (or WFDB, etc.), edit
   the value, and "set" (the variable you had originally selected will be
   unchanged).

  ** Windows 2000 **

   As under NT, environment variables are set in "system properties". Login as
   Administrator (or as a user with administrator privileges), right click on
   "My Computer", select "Properties", go to the "Advanced" tab, and click on
   "Environment Variables...". Look for PATH in the list of "system variables",
   append ";C:\Program Files\Wave" to the end, and "set" the variable.

   To add WAVEROOT, WFDB, and WFDBCAL, use the "New..." button under "System
   variables" to create settings for WAVEROOT, etc.

  ** Windows ME **

   From the Start menu, select "Run", enter "msconfig", and click "OK".
   Environment variables are set under the "Environment" tab.  Long filenames
   seem to be OK, but use short filenames to be safe.

   ** Win95/98 (but not Win ME) **

   Under Win95/98, environment variables are set in C:\autoexec.bat.  For
   example, you might add these lines to your autoexec.bat:

   SET WAVEROOT=C:\PROGRA~1\WAVE
   SET WFDB=;C:/PROGRA~1/WAVE;http://www.physionet.org/physiobank/database
   SET WFDBCAL=wfdbcal

   (These values are the defaults, so you don't actually need to put these
   lines in your autoexec.bat unless you wish to use different values.)

2.2 Cygwin

   Cygwin is the popular Unix-like environment for Windows.  GTKWave does not
require Cygwin for basic functions (like signal viewing or annotation editing),
but some more advanced analysis features must use Cygwin tools. Cygwin is free
and available at www.cygwin.com.

   If you wish to use Cygwin with GTKWave, you must edit the "Defaults" file in
your Wave installation directory (normally C:\Program Files\Wave).  Open
Defaults with Windows Notepad, and add the following line:

Shell: C:\Cygwin\bin\bash.exe

(where "C:\Cygwin" is the location of the Cygwin root directory).
Wave should now use bash as your shell.  Be sure to add the Wave
directory to your PATH.


3. Technical Information

3. 1 MS-Windows versions tested with GTKWave:

 Windows 3.x     - Will not work (GTKWave is 32-bit)
 Windows 95      - OK
 Windows 95 OSR2 - OK
 Windows 98      - OK
 Windows 98se    - Untested, should work
 Windows ME      - OK
 Windows NT 3    - Will not work (it may be possible to port)
 Windows NT 4    - OK (Recommended platform)
 Windows 2000    - OK (some issues, see section 1.3)
 Windows XP      - Untested, may work

   If you run Wave for Windows on 98se or XP, please report your findings to
Isaac Henry (ihenry@physionet.org)

3.2 Development Environment

   GTKWave is being developed with the GNU tool chain available in the current
Cygwin installation.  Specifically, mingw gcc is being used to produce binaries
that are not dependent on the Cygwin runtime; this is due to requirements of
the current GTK+.  The goal is to integrate the build tools for Unix and
Windows, but for now GTKWave for Windows uses a custom Makefile.

   If you are interested in building GTKWave yourself, please contact Isaac
Henry (ihenry@physionet.org) for more instructions.

3.2 GTK+

   Wave was originally developed using the XView toolkit for Unix systems
running X.  GTKWave is a port of Wave to the GTK+ toolkit (www.gtk.org), which
is the base toolkit of the Gnome desktop system for Unix.  GTK+ has been ported
to Windows, and it appears that the next major release of GTK+ will have
official Windows support.

   Using GTK+ for the user interface components allows us to compile GTKWave
for MS-Windows or for Linux or Unix from a single set of sources.  The current
Windows version is based on the unofficial GTK+ port, however, and may contain
significant bugs and other problems.  It is expected that GTKWave for Windows
performance and stability will improve as GTK+ matures.

3.3 Libwww

   Most PhysioToolkit applications, including GTKWave, use libwww (www.w3c.org)
to access remote network records.  GTKWave for Windows comes with a custom
build of libwww which is compatible with mingw gcc and GTK+, and therefore can
access remote records.

---
Isaac C. Henry
ihenry@physionet.org

George B. Moody
george@mit.edu
20 July 2001
