This is the README file of Wafe 0.95. In short, Wafe
is a scripting language for graphical user interfaces 
based on Tcl. Wafe can be used for X Toolkit + Widget
scripts or as a frontend for programs in various programming 
languages.

Wafe seems to be pretty well accepted: since May 92, more
than 6200 requests for Wafe and components were recorded
on ftp.wu-wien.ac.at.

----

PART I:  Differences between Wafe 0.94 and 0.95:

    -  (a) uninterpreted assignment from client applications 
           to Tcl-variables
    -  (b) escaping for %s substitutions
    -  performance improvement up to a factor of 2 in
       communication buffer handling
    -  the Wafe binary accepts --e and --p together 
       (during fork of the client process a Tcl script
       can be sourced and a widget tree can be build;
       the startup of applications using Wafe as a 
       front end appears faster)
    -  support for the Layout widget (great stuff)
    -  new command:  
           [isWidget someName] 
       returns 0 if no widget someName exists, otherwise non-zero
    -  fix for XStoreBuffer 
       (thanks to Natuki ITIMARU <itimaru@lang.ai.kyushu-u.ac.jp>)
    -  bugfix, when lists are set by a single program using both
       listChange and sV .... list {...}
    -  2 XtFree bugs fixed (thanks to Linux, which complained about it)
    -  memory leak for string resources fixed (thanks to 
       Oliver Paul <Olivier.Paul@inria.fr> for the notification)
    -  a few bug fixes for the plotter widget sources
       (logarithmic scale for xyAxis, axis labeling, etc)
    -  some fixes for 64bit machines
    -  cosmetical cleanup and fixes in various application programs
    -  based on tcl 6.7 (instead of 6.6 in Wafe 0.94)
    -  based on xpm 3.2g (instead of 3.2e in Wafe 0.94)
    -  more small sample scripts in $WAFE/src/tcl/* 
       (xpaste, xs, floppymount, puzzle, worldClock,
       form.tcl, logaplot.tcl, xyplot.tcl, barplot2.tcl, 
       layout.tcl)
    -  support for Linux


(a) and (b) are the most significant changes

   (a) uninterpreted assignment from client applications (backend)
       to Tcl-variables

       Wafe 0.95 provides means to assign from a client
       application (say in Perl) to Tcl-variables without
       performing a evaluation of the string (similar
       as the communication channel, but more portable
       and easier to use).

       If the application program running under Wafe writes

       %=myvar This will become the content of the TCL-Variable myvar

       to stdout, the tcl variable myvar is set to the string
       starting with 'This' and ending with 'myvar'.

       This works as follows:

       If the first character after '%' (or the character provided
       via the --c option) is '=', the next space terminated token
       is used as a variable name, and the remainder of the line 
       is assigned to the named tcl variable.

       If the character after the '%' is a '+' followed by a
       space terminated token for the variable name then remainder
       is appended to that variable.

       If the character after the '%' is a '\' followed by a
       space terminated token for the variable name then remainder
       and a newline character are appended to that variable.

       Using this mechanism, i have implemented 'virtual files'
       from Prolog, which write into tcl variables. An open
       clears the specified variable, a write appends to it,
       the close just flushes stdout. Works like a champ.

   (b) %s substitutions:
       consider the following Wafe script

       ----------------------------------------------------------
       #!/usr/bin/X11/wafe --f

       form f topLevel
          viewport v f height 100 allowVert true
          list l v \
            list {this\ is\ a $long list\} with\ ..\{.. se\"veral en[tri]es} \
            defaultColumns 1 width 100 \
            callback {say "this is it !!%s!!"}

       proc say {string} {
         echo "i say <$string>"
       }
       realize
       ----------------------------------------------------------

       The list resource contains several nasty characters.

       In 0.94 %s is substituted in the callback by the string
       of the selected list element, after that the command is
       evaluated using tcl_Eval. For example, if someone chooses
       the element '$long' , the string 'say "this is it !!$long!!"'
       is evaluated, yielding (most probably) a 'no such variable'
       error. One could try various variant of quoting, such as

       #   callback "say %s"    ###  problem if %s contains $ blanks " [ ]
       #   callback {say "%s"}  ###  problem if %s contains $ blanks " [ ]
       #   callback "say {%s}"  ###  problem if %s contains { }

       but the problem only shifts.

       Wafe 0.95 prepares the contents of %s in a way, such it can be
       savely evaluated in Tcl under double quotes. Wafe inserts a backslash
       before $ [ : \ within the %s substituion. Starting with 0.95 
       'say "this is it !!%s!!"' is subsituted by
       'say "this is it !!\$long!!"' when $long is selected; when the
       command is evaluated the string 'this is it !!$long!!' is passed
       to the procedure say.


======================================================================

PART II: WHAT IS WAFE - A CLOSER LOOK

    Wafe (Widget[Athena]front end) is a package that implements 
    a symbolic interface to the Athena widgets (X11R5) and OSF/Motif. 
    A typical Wafe application consists of two parts: a front-end (Wafe) 
    and an application program which runs typically as a separate 
    process. The application program can be implemented in an arbitrary
    programming language and talks to the front-end via stdio.
    Since Wafe (the front-end) was developed using the extensible
    TCL shell (cite John Ousterhout), an application program can
    dynamically submit requests to the front-end to build up the
    graphical user interface; the application can also down-load
    application specific procedures into the front-end, which can
    be executed without interaction with the application program. 

    In opposite to the described two process frontend approach, wafe 
    applications can also be written purely in TCL, in which case only 
    one process is needed.

    The distribution contains sample application programs in Perl,
    GAWK, Prolog, TCL, C and Ada talking to the same Wafe binary.
    Most of the following demo applications are implemented in 
    Perl 4.0.36:

        - xwafedesign: interactive design program for wafe applications
	 - xwafeftp:    FTP front-end
	 - xwafemail:   Mail user front-end with faces, using elm aliases
	 - xwafenews:   NNTP based newsreader, using elm aliases
	 - xwafegopher: a very simple gopher interface
	 - xdirtree:    tree directory browser
	 - xprojektor:  white board program for the classroom
	 - xbm:         bitmap and pixmap viewer
	 - xwafemc:     multiple choice test answering program
	 - xruptimes:   rwho monitor like xnetload
	 - xnetstats:   network statistics, front-end for netstat -i <interval>
	 - xvmstats:    system statistics, front-end for vmstat -i <interval>
	 - xiostats:    io statistics, front-end for iostat -i <interval>
	 - xwafeping:   pings several machines an show up-status
	 - xwafecf:     a simple read only card-filer
	 - xwafetel:    a simple read only Oracle front-end for looking up
	                telephone numbers
	 - xwafeora:    a more elaborated Oracle front-end with updates 
	                capable to model an entity type with distinct
	                predicate defined subtypes, allowing multi valued 
                        attributes (it comes with sample applications 
                        "filing management" and "paper base") doing field 
                        completion and other funky stuff

	 - primfakt.awk:    primfakt program in GAWK using wafe
	 - primfakt.prolog: primfakt program in Prolog using wafe
	 - primfakt.perl:   primfakt program in Perl using wafe
	 - primfakt.c:      primfakt program in C using wafe
	 - primfakt.a:      primfakt program in Ada using wafe
	 - cprimfakt.c:     native C implementation of primfakt (single process)
	 - xprimfakt.tcl:   primfakt program in TCL using wafe (single process)

	 - perlwafe: an example program calling wafe as a subprocess of the
	   application program (normally, it is the other way round).


    HOW CAN WAFE BE USED AS A FRONTEND 

    Suppose you have an application program named "app". If we
    install a link like "ln -s wafe xapp" and execute "xapp ", the
    program "app" is spawn as a subprocess of wafe and connects its
    stdio channels with the front end.  Lines written from the
    application program to stdout are read from Wafe. If the line
    starts with a certain character (such as %) Wafe tries to
    interpret the remainder of the line as TCL command.  The
    standard TCL shell has been extended with new commands
    exploiting the X Toolkit, the Athena widget set, the 
    OSF/Motif widget set and the XPM library to build up
    user interfaces with the window system named X.

    In most example programs of the distribution the application program
    is run as a subprocess of wafe, one example (perlwafe) shows the 
    opposite constellation where the "link magic" is not needed.

    ADVANTAGES of Wafe

	-  application program can be written in wide range of programming
	   languages
	-  relatively high level interface to widget applications
	-  single wafe binary for multiple applications
	-  better refresh behavior when application program is busy
	-  click ahead
	-  better separation between user interface and
	   application program matters 
	-  no need to hack C code
	-  easier migration from existing ascii based programs to
	   X-window applications



    REQUIREMENTS FOR APPLICATION PROGRAMS

    In order to use Wafe in a two process setup, an application program 
    must be able to write **LINEBUFFERED** (or unbuffered) to stdout (the 
    application program must at least be able to flush the buffer) and 
    to read from stdio. The application program determines the syntax 
    in which Wafe talks back.


    AVAILABILITY

    Wafe was developed on DECstations 5000/200 under Ultrix 4.2
    using X11R5, and has been tested on a SparcStation 1+ under
    SunOS 4.1, RS6000/320 under AIX, on a HP 9000/720 under hpux
    8.05 and under Linux 0.99.10. Wafe can be compiled under X11R5 
    and X11R4. The preferred program-to-program communication is 
    done via socketpair, support for PIPES and SYS V streams is 
    included for systems without the socktepair system call.

    NECESSARY, BUT NOT INCLUDED 

    Most application of the distribution are written in Perl. 
    Perl 4.036 is needed to run these applications. Two applications 
    will need oraperl.  Only user with an Oracle license might find 
    wafeora and wafetel useful. User might wish to compile wafe with 
    the 3d Athena Widget library Xaw3d-0.6.tar.Z. Pointers to the 
    source can be found in the INSTALL file.


    PRERELEASE

    The current distribution is a prerelease (version 0.95). The final
    version (whatever final means) will be posted after we got some 
    feedback/suggestions from the network.


    ACKNOWLEDGEMENT

    The Wafe project would have been impossible without the
    availability of software in source form such as

	    - X11R5 distribution from the MIT
	    - TCL and TK (John Ousterhout)
	    - Perl (Larry Wall)
	    - XPM-Library (Arnaud Le Hors <lehors@sophia.inria.fr>)
	    - dbug-Library (Fred Fish)
	    - plotter widget set (Peter Klingebiel <klin@iat.uni-paderborn.de>)
	    - XmGraph (Douglas Young)
	    - Xaw3d (Kaleb Keithley <kaleb@thyme.jpl.nasa.gov>)
	    - rdd2 (Roger Reynolds <rogerr@netcom.com>)
	    - oraperl (Kevin Stock <kstock@gouldfr.encore.fr>)
	    - ftp.pl package (Alan R. Martello <al@ee.pitt.edu>)
	    - chat2.pl package (Randal L. Schwartz <merlyn@ora.com>)
	    - nntp.pl package (Randall S. Krebs)

    Only the most important packages are listed here.

    # Copyright (C) 1992,93 by Gustaf Neumann, Stefan Nusser
    #
    #     Wirtschaftsuniversitaet Wien, 
    #     Abteilung fuer Wirtschaftsinformatik
    #     Augasse 2-6, 
    #     A-1090 Vienna, Austria
    #     neumann@wu-wien.ac.at, nusser@wu-wien.ac.at
    #
    # Permission to use, copy, modify, and distribute this software
    # and its documentation for any purpose and without fee is
    # hereby granted, provided that the above copyright notice
    # appears in all copies and that both that copyright notice and
    # this permission notice appear in all supporting documentation.
    # This software is provided "as is" without expressed or implied
    # warranty.

    Every user is permitted to create derivative work to this
    program.  However, all copies of the program and its derivative
    works must contain the above copyright notice. We would like to
    ask every user to supply a copy of any change, enhancement or
    derivative work to the mailing address

		    neumann@wu-wien.ac.at

    Thank you in advance.


   Wafe 0.95 can be obtained via anonymous ftp from

	    ftp.wu-wien.ac.at:pub/src/X11/wafe/wafe-0.95.tar.gz

   (for people without name server: the ip address is 137.208.3.4)
    A split up version is available from the same directory.

   Donations for statically bound binaries of the OSF/Motif version
   of Wafe (mofe) are accepted.


MAILING LIST:

    In order to subscribe to the Wafe mailing list, 
    send a mail with the mailbody

       subscribe Wafe <Your Name>
       help

    to listserv@wu-wien.ac.at. Postings should be sent to
    wafe@wu-wien.ac.at.



-gustaf
--
Gustaf Neumann                  neumann@dec4.wu-wien.ac.at
Vienna University of Economics and Business Administration 
Augasse 2-6,  A-1090 Vienna, Austria		
Tel: +43 (222) 31-336 x4533  	Fax: 347-555
