### yorick-1.4 README file

    			  Yorick Version 1.4

    ***********
    * Warning *  The generic INSTALL file does not mention important details
    ***********  of Yorick installation.  See Installation below.

    What is Yorick?   Read the ANNOUNCE file in this directory.
    ---------------

    Contents
    --------
    1. Installation
    2. Yorick directory structure
    3. Configuration options and problems
    4. Optimization
    5. Fine tuning
    6. Problems
    7. Documentation
    8. Getting started
    9. Address
    10. Legal matters

    1. Installation
    ---------------

    You need an ANSI C compiler in order to build Yorick "as is".

    Yorick must find a bunch of startup files (interpreted code which it
    needs to read when it starts).  The Gist CGM browser has the same
    problem -- it needs to find a template to be able to create PostScript
    output.  The "Yorick directory structure" section below gives details.

    Your simplest option is to build Yorick right here in its source
    directory -- but be aware that if you remove the source directory at
    some future date, Yorick and Gist will stop working!  To configure
    Yorick in this way, type:

         ./configure --prefix=here

    You can leave out the --prefix=here parameter if you want to install
    Yorick in the /usr/local directory tree.  You'll most likely need to
    be root in order to do that.  See "Configuration options and problems"
    below if something goes wrong with configure.

    Now that you've configured Yorick, build the code by typing:

         make

    If the make succeeds, you can test to see if the code works by typing:

         make check

    If the check succeeds, install yorick and gist by typing:

         make install

    Finally, you will want to clean up by typing:

         make clean

    If you want to return to the state before the configure, so you can
    reconfigure Yorick for a build on a new platform, or for installation
    in a different directory, type:

         make distclean

    Before you think that you're finished building Yorick, be sure to read
    the section "Fine tuning" -- there are things the configure script
    cannot do for you that you might want to do yourself.  Also, be sure
    to follow the special instructions in "Yorick directory structure" if
    you are building Yorick on several architectures in a heterogeneous
    network.

    2. Yorick directory structure
    -----------------------------

    Architecture-independent files (text):

         Y_SITE/

            startup/
               paths.i std.i graph.i stdx.i fft.i matrix.i drat.i
               <these files are required for Yorick to start properly>
            include/
               *.i
               <Yorick interpreted code library>
            gist/
               ps.ps *.gs *.gp
               <PostScript template, style sheets, and palettes for graphics.>
            doc/
               <Yorick documentation>
            contrib/
               <optional world-writable place for local contributors>

    Architecture-dependent files (executables, object libraries, header files):

         Y_HOME/

            Maketmpl
               <Makefile template for building custom yoricks>
            lib/
               libyor.a libgist.a libyorm.a libdrat.a
               <object libraries for various parts of Yorick>
               contrib/
                 <optional world-writable place for local contributors>
            bin/
               codger     <code generator for building custom yoricks>
            h/
               <C header files for building custom yoricks>

    The user-level executable files (also architecture-dependent):

         Y_BINDIR/
            yorick gist
            <the Yorick interpreter and the Gist binary CGM browser>

    The Y_SITE and Y_BINDIR directories are the only ones necessary to run
    Yorick.  The Y_HOME directory comes into play only if you want to add
    your own compiled functions to Yorick.

    The GNU Autoconf scheme for computing the directory paths is based on
    placing Y_SITE, Y_HOME, and Y_BINDIR relative to two higher level
    directories prefix and exec-prefix.  These both default to /usr/local,
    but can be reset by specifying --prefix= or --exec-prefix= options to
    configure.  If you use these, you will get:

         Y_SITE = prefix/share/yorick/1.4
         Y_HOME = exec-prefix/lib/yorick/1.4
         Y_BINDIR = exec-prefix/bin

    You can give configure the --disable-share option if your site does
    not use "share" subdirectories; in that case, Y_SITE will be in
    prefix/lib instead of prefix/share.  See "Configuration options and
    problems" below for other alternatives.  In particular,
    exec-prefix/lib/yorick/1.4 might be visible from several different
    architectures at your site; if so you will need the --enable-suffix
    option to be able to create a version of yorick for each architecture.

    If you give configure the special prefix --prefix=here this scheme is
    disabled, and you get:

         Y_SITE = srcdir/Yorick
         Y_HOME = exec-prefix       (which defaults to srcdir in this case)
         Y_BINDIR = exec-prefix/bin

    (In this case, you probably need to either move the executables in
    Y_BINDIR to a place on your path, or make softlinks to them.)

    3. Configuration options and problems
    -------------------------------------

    If configure can't find your ANSI C compiler, set the environment
    variable CC to your ANSI C compiler's name, make sure it is on your
    execution path, and rerun configure.  (The GNU gcc compiler is available
    at prep.ai.mit.edu if you have no ANSI C compiler.)  For example:

         env CC="cc -ansi" ./configure --prefix=here

    You may also need to set the LIBS or LDFLAGS variables (see the section
    "Compilers and Options" in INSTALL).  The default optimization should be
    adequate; but see the "Optimization" section below.

    This configure script also supports the following non-standard options:

    --prefix=here
      To set the prefix to this source directory.  See the section
      "Yorick directory structure" above.  You can specify --exec-prefix
      as usual if you just want the Y_SITE files to go here.

    --with-gcc
      Use this to make configure try to find gcc instead of cc.

    --enable-share=name
    --disable-share
      The GNU default is to place architecture independent files in
      /usr/local/share (or prefix/share in general).  If /usr/local/name
      (or prefix/name in general) is more appropriate for your system,
      use this option.
      --disable-share is equivalent to --enable-share=lib

    --enable-suffix=host
      Adds the suffix "/host" to Y_HOME.  This may be necessary if you are
      building yorick for a number of different architectures, and your
      exec-prefix is visible from all of them.  For example,
      --enable-suffix=SunOS
      will cause Y_HOME to be (by default) /usr/local/lib/yorick/1.4/SunOS
      You can use this option with --prefix=here as well.

    --enable-bindir=path
    --disable-bindir
      Set Y_BINDIR to path for situations where the default calculation
      (see "Yorick directory structure" above) is wrong.
      With --disable-bindir the yorick and gist executables will be installed
      in Y_HOME/bin (with codger).  This is always a safe option, as you can
      move them or make softlinks to them later.

    4. Optimization
    ---------------

    By default, Yorick will be built with "-O" optimization.  If you have
    serious problems, you can build a debugging "-g" version by typing
    (in the top level directory):

         make clean
         make debug
         make

    and perhaps "make install".  To return to the default "-O" optimization,
    do this:

         make clean
         make optimize
         make

    On most platforms, optimization beyond "-O" does not seem to help
    Yorick's performance much.  If you want to experiment with something
    like "-aggressive" on your platform, run make optimize like this:

         make optimize O_FLAGS="+O4 -aggressive"

    On some platforms, "-aggressive" (or whatever) causes the compiler to
    fail if specified on the load line instead of the compile line.  If
    you need a different option for loading, do this:

         make optimize O_FLAGS="+O4 -aggressive" LD_FLAGS=+O4

    Again, this tinkering is probably a waste of your time.

    5. Fine tuning
    --------------

    The configure script cannot do a few things that you may want to do
    (then do a distclean and rebuild Yorick):

       (1) Most UN*X workstations will not deliver SIGFPE signals when
           you do things like divide by zero or square 1.e300.  Yorick
           expects these signals to be delivered!  (Type 1./0. at the
           > prompt after you start Yorick; it should respond angrily
           with something about ERROR.  If it meekly types something
           silly like "Inf", you have a problem that you should fix!  If
           you don't fix this, sooner or later you'll waste a large amount
           of CPU time slowly filling a 1000-by-1000 array full of Inf's
           or NaN's...)  Unfortunately, every manufacturer has a different
           idea of what you should do to get this signal delivered.  These
           fall into two categories:
           (a) a loader switch (e.g.- -fnonstd on Suns, +FPVZOD on HPs)
               This is easy.  Just set the LDFLAGS environment variable
               before you run configure (see above).
           (b) a subroutine which must be called at runtime
               In this case, you must modify the InitializeSignals
               routine in the file Yorick/sysdep.c.  Examples for several
               different architectures are shown there.

           The sysdep.c source code includes #ifdefs for SunOS, Solaris,
           HP 700 series, SGI, IBM RS6000, DEC alpha, Linux, and Cray
           machines; if you have one of these, you may not need to do
           anything yourself.  Do the 1./0. test to be sure.  The SGI
           machines are particularly baroque; beware of the TRAP_FPE
           environment variable described in the Problems section below.

           As of this writing, I have not been able to convince Ultrix to
           deliver SIGFPE.  If you know how to do this, send me e-mail.
           I have been told that the man page for_set_fpe.3f might give
           you some hints for how to do this with Fortran.

       (2) The configure script will not do anything about shared versus
           archive libraries.  Think about which you want.  You can set
           LDFLAGS before you run configure (see above) if you don't want
           default behavior.  The default is probably good enough, but if you
           use shared libraries, you need to check Yorick on any machines
           on your network whose operating system differs (even in minor
           version) from the machine where you built it.  If you go for
           archive libraries on Solaris, you may need Yorick/dlsym.c, and
           see the note in Yorick/Maketmpl.in.

       (3) The configure script knows little about Fortran compilers.  If
           you want to load special versions of Yorick which call Fortran
           routines, you may need to tinker with the Fortran section of
           the Makefile template Maketmpl, installed in Y_HOME.  After
           make install, feel free to do so.

    6. Problems
    -----------

    (1) Some DEC alpha compilers break the routine YpDo in Yorick/parse.c.
        If this happens, make check will tell you to recompile parse.c at -g.
        (If you want to retain full performance during parsing, you can
        probably figure out a way to work around the compiler bug, which is
        that the "body" argument is not passed to the SetBranchTarget routine
        correctly in parse.c:YpDo.)  The latest version of DEC's compiler
        (as of November 1996) does not have this problem; consider upgrading.

        If you have no idea how to do this yourself, try the following:
        Look through the output from make to find the line that compiled
        parse.c (just search backward for parse.c if you can).  Edit that
        line, changing the -O flag to -g then cd into the Yorick/ directory
        and execute the edited compile line.
        Finally, return to the top level, and rebuild Yorick:
           cd ..
           make
           make check
        Doing "make check" shouldn't fail any more.

    (2) On SGI machines under IRIX, Yorick may not behave properly if
    you have set the environment variable TRAP_FPE.  Yorick *wants* to
    handle floating point interrupts all by itself!  This problem shows
    up in bizarre places; if you have set TRAP_FPE, you should make
    an alias to start Yorick with it unset.

    (3) Early IRIX 6.0 machines didn't ship with a 64 bit version of libfpe.a,
    so you won't be able to make 1.0/0.0 illegal (see Fine Tuning 1).

    (4) If you use a non-HP compiler (e.g.- gcc) on a PA-RISC machine, it
    is almost certainly installed incorrectly.  The libm.a in /lib is
    *not* the correct one; you want the one in /lib/pa1.1.  After
    configure, change LOWLIBS in config.status, placing -L/lib/pa1.1
    before -lm, and rerun it (config.status).

    (5) If you yorick graphics fails with a message that it can't find
    work.gs, then you didn't install Yorick properly.  In the top level
    directory where you built it, try "make clean; make; make install".
    The same thing applies if Yorick can't find its startup include files
    (like std.i).

    (6) Some Linux libc versions have a bug in sscanf so that real numbers
    like "1.23E-4" will not be read properly.  "1.23e-4" works fine, so the
    workaround is not to use capital E in your input files (the yorick
    parser is not affected, only the read and sread functions).  Amazingly
    enough "1.23E4" is fine as well, only exponents with an explicit +-
    are a problem.

    7. Documentation
    ----------------

    I haven't finished a user's manual; what I have so far is in Yorick/doc
    as the file yorick.tex.  It is in GNU texinfo format, so you can use GNU
    Emacs to read it online as hypertext (for Emacs 19.25 or above, all you
    need do is to add the doc/ directory to Info-default-directory-list
    variable), or TeX to make a printable document.  To build the hypertext
    version, cd to Yorick/doc and type:

         makeinfo yorick.tex

    The distribution comes with a pre-built PostScript version of the
    manual yorick.ps, and the set of quick reference sheets refs.ps.  If
    you have TeX and you want to rebuild yorick.ps for A4 paper, put the
    @afourpaper macro near the top of yorick.tex and rerun tex.

    The two UNIX man pages yorick.1 and gist.1 (in this top level directory)
    can be installed if you wish.  The gist page is a complete description
    of the browser.  The yorick page tells how to get more help.

    Other documentation (in Yorick/doc) includes:

         refs.tex
            a set of 6 quick reference sheets for the Yorick language; use
            a double sided Xerox to make 3 quick reference cards

         std.doc
            alphabetized collection of DOCUMENT comments for all of the
            standard basic Yorick commands and functions

         graph.doc
            ditto for all of the plotting commands and their keywords

         math.doc
            ditto for the FFT and LAPACK matrix routines in the Math package

         drat.doc
            ditto for the transport equation solver in the Drat package

    The *.doc files are compilations of all of the DOCUMENT comments which
    can be printed interactively using Yorick's help command; type "help"
    (no quotes) after you start Yorick in order to find out more about how
    to use the help command.  They are built when you do "make install".

    The file Yorick/include/README contains a thumbnail description of the
    library functions in the Yorick/include directory.

    8. Getting started
    ------------------

    After you've had enough of the documentation, I recommend you peruse the
    Yorick/include/demo1.i file.  This is a simple 1-D hydrodynamics code
    implemented entirely in the interpreter.  It analyzes a piston moving
    into a shock tube; you can watch weak sound waves propagate, or stronger
    ones steepen into shocks.  Read the file carefully to get an idea of
    what a Yorick program looks like.  Here is an interactive session in
    which I run some demos (the stuff after the > prompt is what I typed):

    tonto[1] yorick
     Yorick ready.  For help type 'help'
    > #include "testg.i"
    > grtest       // graphics test/crude tutorial
    ...lots of explanations and descriptions...
    > #include "demo1.i"
    > help, demo1
     /* DOCUMENT demo1
          run the 1-D hydrocode demonstration.  An X window should pop up
          in which a movie of a wave propagating down a shock tube appears.
          Use the 'sound' and 'shock' commands to set two different interesting
          initial conditions; the default is 'sound'.

        SEE ALSO: sound, shock, evolve
      */
     defined at:  LINE: 275  FILE: /wrk/munro/yorick-1.4/Yorick/include/demo1.i
    > demo1        // watch jerky movie in an X window
    > animate, 1   // turn on smooth animation
    > demo1        // watch smooth movie in an X window
    > shock
    > demo1        // watch movie showing shock steepening
    > #include "demo2.i"
    > demo2        // watch 3 movies of a drumhead oscillating
    > #include "demo3.i"
    > demo3        // watch "Way cool, Dad!" chaotic pendulum movie
    > #include "demo4.i"
    > demo4        // Yorick solves an plots flow field around an airfoil
    > #include "demo5.i"
    > demo5        // demonstrate pl3d "3D" graphics functions
    > quit
    tonto[2]

    The Yorick/include/demo2.i has more eye-catching graphics than demo1.i,
    although you won't like the first and third movies unless you have a
    color monitor.  Again, reading the source code should be instructive.

    Many of the other files in the Yorick/include library provide interesting
    examples of how to use Yorick.  Read through any that interest you, using
    the Yorick/doc/*.doc files to look up the meanings of any functions you
    don't understand, and the quick reference cards to decipher any syntax
    you can't understand.  Array indexing is particularly complicated ("rich")
    in Yorick; a long (but poorly edited) section in the yorick.tex proto-manual
    will hopefully clarify this for you.

    9. Address
    ----------

    I welcome constructive comments:            munro@icf.llnl.gov

    If you find a bug (I've found a few myself), please fix it and tell me
    what you did, so I can fix the distribution.

    The ANNOUNCE file lists Yorick FTP sites, and tells how to subscribe
    to the Yorick mailing list.

    10. Legal matters
    -----------------

    (c) 1994.  The Regents of the University of California.  All rights reserved.

    Permission to use, copy, modify, and distribute this software for any
    purpose without fee is hereby granted, provided that this entire
    notice is included in all copies of any software which is or includes
    a copy or modification of this software and in all copies of the
    supporting documentation for such software.

    This work was produced at the University of California, Lawrence
    Livermore National Laboratory under contract no. W-7405-ENG-48 between
    the U.S. Department of Energy and The Regents of the University of
    California for the operation of UC LLNL.

    			      DISCLAIMER

    This software was prepared as an account of work sponsored by an
    agency of the United States Government.  Neither the United States
    Government nor the University of California nor any of their
    employees, makes any warranty, express or implied, or assumes any
    liability or responsibility for the accuracy, completeness, or
    usefulness of any information, apparatus, product, or process
    disclosed, or represents that its use would not infringe
    privately-owned rights.  Reference herein to any specific commercial
    products, process, or service by trade name, trademark, manufacturer,
    or otherwise, does not necessarily constitute or imply its
    endorsement, recommendation, or favoring by the United States
    Government or the University of California.  The views and opinions of
    authors expressed herein do not necessarily state or reflect those of
    the United States Government or the University of California, and
    shall not be used for advertising or product endorsement purposes.

    				AUTHOR

    David H. Munro wrote Yorick and Gist.  Berkeley Yacc (byacc) generated
    the Yorick parser.  The routines in Math are from LAPACK and FFTPACK;
    MathC contains C translations by David H. Munro.  The algorithms for
    Yorick's random number generator and several special functions in
    Yorick/include were taken from Numerical Recipes by Press, et. al.,
    although the Yorick implementations are unrelated to those in
    Numerical Recipes.  A small amount of code in Gist was adapted from
    the X11R4 release, copyright M.I.T. -- the complete copyright notice
    may be found in the (unused) file Gist/host.c.