README file for  Xtc / Tek2Ps  Programs


****************
REVISION HISTORY
****************
      date         Description

 October, 1998  -- portability upgrade

--------------------------------------------------------
Note:  You need Motf to build xtc.
--------------------------------------------------------

Index:
   1. CONTENTS
   2. UNPACKING INSTRUCTIONS
   3. DESTINATIONS
   4. BUILDING INSTRUCTIONS
   5. USER GUIDE
   6. FINAL INSTALLATION

************
1. CONTENTS:  
************
This directory should contain the following files:

README:     This file.  Brief descriptions of the other files, and
            instructions for compiling, testing and installing. 

Makefile:   NOTE, "GNU make" must be used
            (usually in /usr/gnu/bin or /usr/local/bin).

Make.flags: Include file for Makefile

Xtc:        Defaults file for xtc

tek2ps.pro: Prolog file for Tek2Ps

xtc_print:  sh script to print tek file on ps printer
            ( if priner can not handle it) used by xtc.

.xtcrc 
.xtcrc_csh: scripts to setup environment end start xtc

Sources to build Xtc and Tek2Ps (*.c and *.h)

For VMS:    .com, .opt and .dat files

**************************
2. UNPACKING INSTRUCTIONS:
**************************
for tarfiles:
  > gunzip xtctek.tar.gz
  > tar xvf xtctek.tar

or, for zip archives:
  > unzip xtctek.zip

****************
3. DESTINATIONS:
****************
Or where do the files go?
(this refers to building and testing; see FINAL INSTALLATION for end result) 


When you extract the tar file you get three sub directories:
./xtstek   --  sources and Makefile
./share    --  include file Make.flags 

The makefile will create more sub directories,
obj/xtctek:   for compiled objects
exe:          for xtc and tek2ps programs

These object directories go:

If $LOCAL is defined (for TRANSP users):
----------------------------------------
$LOCAL/exe/
$LOCAL/obj/xtctek/

If $LOCAL is not defined (non-TRANSP users):
--------------------------------------------
By default these directories are created in  
./<MACHINE>, which is determined by Make.flags.
e.g.: if you are running Linux, and the tar file resides in $HOME/foo,
      the directories would be in
      $HOME/foo/LINUX/...

You can overwrite the destination by defining OBJ, as an environment
variable (e.g. export OBJ=/dir1/dir2),
or with make (e.g. "make all OBJ=..").
If OBJ is defined, the destinations will be
$OBJ/obj/xtctek and $OBJ/exe.
If OBJ is defined as ".." then, in the example above, the destination
would be $HOME/foo/exe.

The rationale behind <MACHINE> is to facilitate building for various platforms.
 

*************************
4. BUILDING INSTRUCTIONS:
*************************.


How to build the XTC program:
============================

To build Xtc and Tek2Ps:
	> (cd xtctek; gmake all)
or
        > (cd xtctek; gmake all OBJ=..)

**************
5. USER GUIDE:
**************

How to test XTC:
================

	> . xtctek/.xtcrc
or
	> source xtctek/.xtcrc_csh

will define the ENVIRONMENT and start XTC.
(Note: unless you installed xtc, it's propably not in your PATH
       so do: > <MACHINE>/exe/xtc & )

In detail:
First set the following environment variables:
	setenv PLOT     xtc_mbx_0_<user_name>
	setenv TERMINAL_TYPE XTC
To avoid acknowledging each plot (by clicking or typing <return> in the
XTC window:
	setenv TERMINAL_INPUT NONE
To make sure there are no leftover files from a previous incarnation:
	rm /tmp/xtc*<user_name>
If you do not have a default X-window file, Xtc, in your home directory:
	cp Xtc $HOME
To run the program:
	<MACHINE>/exe/xtc &

In the above, <where_to_display> is the node name for the display screen,
and <user_name> is your user name.

A handy test program is the tstp10 program provided with SGLIB:
	<MACHINE>/exe/tstp10 
	 plot number (zero for all, -1 to quit)[0]? 4
	 plot number (zero for all, -1 to quit)[0]? -1

The plot should appear in the XTC window.

How to use XTC:
==============

It is convenient to create a shell file to set up xtc:
	> cat XTCRUN
	setenv PLOT     xtc_mbx_0_thompson
	setenv TERMINAL_TYPE XTC
	rm /tmp/xtc*thompson
	xtc&

See also .xtcrc and .xtcrc_csh, which are included in the distribution.
These scripts can be used for automatic startup of xtc.


To save a plot as a file or print the file, use the List Box command
in the Commands menu.

To select a printer (other than the default PRINTER) or to re-define
file name, use "Frame Printing" or "Frame Filing" in  the Customize
menu. 

To print, you need a printer that supports tektronix style files.
If your printer can not handle tektronix files, xtc can convert them 
to ps files prior to printing.
To do this define the "Directory of tek2ps prolog" on the "Frame Printing"
menu. This must be the directory, where tek2ps.pro and xtc_print reside,
e.g. $CODESYSDIR/xtctek, $HOME/xtctek.
Note: you also must have 'tek2ps' in your PATH !


If you change any settings do "Save Current Settings" in the Customize
menu to save a new Xtc file in your home directory.

For more detailed information on XTC, go to the "XTC Help Document"
item of the TRANSP Home Page, http://w3.pppl.gov/transp.


How to test TEK2PS:
==================

The tstp10 program from SGLIB can also be used to test tek2ps:
	setenv PLOT  foo.plt
	<MACHINE>/exe/tstp10
	 plot number (zero for all, -1 to quit)[0]? 4
	 plot number (zero for all, -1 to quit)[0]? -1

The tek2ps program requires the prolog file, tek2ps.pro.  If this is in
your $HOME directory:
	setenv PRO $HOME/tek2ps.pro
	tek2ps -o foo.ps -p $PRO foo.plt
	lpr -P <printer> foo.ps


**********************
6. FINAL INSTALLATION:
**********************

Choose or create the root directory in which you wish to install the software.
Common locations would be /usr/transp or /usr/ntcc, but installation
can occur in any directory where you have appropriate permissions.

Make sure users add this directory to their PATH.

You define your choice of root directory via PREFIX.
The default for PREFIX is /usr/transp.

The assumptions are:

binaries in:  $PREFIX/bin        = $BINDIR       
man pages in: $PREFIX/man/man1   = $MANDIR/man1

To install the software, return to the top directory (the directory,
where you downloaded the tar files) and type

> gmake install  
    to install into /usr/transp/...

> gmake install PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

If you want things elsewhere, you can overwrite the default with
> gmake install BINDIR=/yyy MANDIR=/zzz


NOTE:
=====
The following files are not installed, but they must be readyly
accessable by users and should be at an appropriate location:
  -- Xtc, .xtcrc and .xtcrc_csh should be copied by users into $HOME
  -- tek2ps.pro and xtc_print

At PPPL they reside in /usr/transp/etc.

See "1. CONTENTS" for description of these files.


After you have installed the software, and manually copied above files,
you can delete the entire tree with
> cd ..
> rm -r foo
   (assuming the previous example).

-----------------------------------------------------------------------------
IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:


        Doug McCune, Princeton University
                dmccune@pppl.gov
        or

	Christiane Ludescher, Princeton University
                cludescher@pppl.gov
        or	
                ntcc_webmaster@pppl.gov
