*******************************************************************************
  1ST_README
  Z151193
*******************************************************************************

       A Very Short "Documentation" for XCCPJIFFY class applications
       -------------------------------------------------------------

     Contents
     --------

     0. Introduction
     1. Installation
     2. Using
     3. Other useful programs
     4. Format of the input files
     5. What to do with a new computer system



  0. Introduction
     ------------

     Dear user,

     This piece of text will try to describe some X-windows applications,
     which are in principle stand-alone, but maybe are useful for people
     running CCP4 crystallographic program suite in X-windows environment.

     If you really want to understand how the jiffies work, you must be
     familiar with terms X-windows environment, X-toolkit, (Athena) widget
     set, application, application class, application resources and
     application default file. However, in most cases this is not necessary,
     but it is recommended, that installation is performed by somebody who
     at least feels what is going on.

     Currently following xccpjiffies are available:

  a. xloggraph       - which reads specially formatted log file produced by
                       some of the CCP4 programs, recognizes "tables" and
                       "graphs" described in it and produces their graphic
                       representation.

  b. xplot84driver   - which reads plot84 graphic metafile and interprets it.

  c. xccpjiffy2idraw - plain filter which converts postscript file created
                       by xccpjiffy into idraw postscript format. (idraw
                       is mentioned in part 3.)

     


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

  a. Distribution
     xccpjiffies are distributed as a UNIX tar file containing XCCPJIFFY
     directory. Untar the tar file 1st. File Imakefile gives the installation
     information for various types of UNIX machines.

  b. Requirements:
     I. UNIX operating system
    II. ANSI C compiler
   III. X-windows X11 release 4 - properly installed
    IV. Corresponding Athena widget set
     V. F77 compiler

  c. Machine dependencies
     I. Fortran global symbol names in file tom_fortran_interface.h
    II. System include files in sys_includes.h
        Current version should work well on SGI, ESV, ALLIANT_2800, Convex.
   III. Imakefile - you have to edit it during installation.

  d. Site dependencies - please edit Imakefile, see section e, f
     Symbols:
        IRIX_4, ESV_2... in machine specification section
        BINDIR       (executable directory)
        TOMFONTDIR   (Tom Oldfield's fonts directory)
        XAPPLRESDIR  (directory for application resource default files)
        TOM_FONT     (Tom Oldfield's font name)
        PLOT_COMMAND (Postscript spooler)
        PRINT_COMMAND(Text spooler)
      all are in Imakefile

  e. Site dependencies for CCP4 users
     If you are installing xccpjiffies from ccp4 environment (after
     customizing and sourcing ccp4.setup file), variables
     BINDIR, TOMFONTDIR, XAPPLRESDIR, TOM_FONT are pre-set for you.
     BUT ... DO NOT forget to set your machine specification & PLOT_COMMAND.

  f. Procedure
     I. cd .../XCCPJIFFY
    II. Edit Imakefile
   III. xmkmf
    IV. make depend
     V. make install
    VI. make clean   - if you wish to delete garbage
   VII. edit XCCPJiffy application default file in directory given by
        XAPPLRESDIR symbol from Imakefile (If really necessary).

  g. User environment
     The presence of application resources for running XCCPJiffies
     is vital. Please be sure that environment variable
     XUSERFILESEARCHPATH or one of the others is set up properly before
     any of the X programs is run. For information, how to set this
     variable read X11 manuals or see the local Guru. CCP4 users
     are an exception.

  h. User environment for CCP4 users
     If you use standard CCP4 environment, XUSERFILESEARCHPATH environment
     variable should be set for you by ccp4.setup.


  2. Using
     -----

     Run xloggraph/xplot84driver application without any parameters.
     the manual will be printed (on stderr, normally the terminal).
     There are several EXAMPLE data files in the XCCPJIFFY directory.
     Note that plot84 file format is binary - system dependent.
     Once the control window is displayed, push buttons & explore.


  3. Other useful programs
     ---------------------

  a. idraw - public domain X oriented 2D editor. The main advantage is
     a postscript like external data format and floating coordinates no-
     tation. Very useful for manual interventions to pictures ...
     Disadvantage - written in C++ (do you have a compiler?).
     Source & some executables: interviews.stanford.edu


  4. Format of the input files
     -------------------------

     run xloggraph without any parameters

     xloggraph

     Manual will be printed on the screen. Try to understand and compare
     your knowledge with examples, which contain table descriptions.

     xplot84driver uses plot84 metafile format, which is described in
     appropriate documentation (I do not know where).


  5. What to do with a new system
     ----------------------------

     xccpjiffies have been successfully used on machines mentioned in
     Imakefile. Using a new machine can cause several problems:

       a. Compilers (ANSI C & F77) options in Imakefile may be inappropriate

       b. C system header files (???.h) can cause problems - see sys_includes.h

       c. Implementation of calling fortran routines from C and vice versa
          can be different. See tom_fortran_interface.h

       d. Any others unpredictable problems - help yourself please



Z261093                       Good Luck
                              J.Zelinka  zelinka@yorvic.york.ac.uk

