------------------------------------------------------------------------------
                                  PGSBOX 3.4
------------------------------------------------------------------------------
PGSBOX is a PGPLOT routine (FORTRAN) which draws and labels curvilinear
coordinate grids.  Example PGSBOX grids can be seen at

   http://www.atnf.csiro.au/~mcalabre/WCS/PGSBOX/index.html

PGSBOX is provided as part of WCSLIB which available from

   http://www.atnf.csiro.au/~mcalabre/WCS


Manifest
--------
   Makefile	GNU makefile for compiling PGSBOX.
   README	This file.
   CHANGES	List of changes made to PGSBOX.

   pgsbox.f     PGSBOX source code.
   pgcrvl.f     PGCRVL, a driver routine for PGSBOX provided for backwards
                compatibility.

   cpgsbox.c    C wrapper function for PGSBOX.
   cpgsbox.h    Header file for cpgsbox().

   pgwcsl.c     C function pgwcsl_() with FORTRAN-like interface defines an
                interface to WCSLIB 3.x for PGSBOX to draw celestial
                coordinate grids.
   pgwcsl.h     Header file for pgwcsl_().

   pgcrfn.f     Subroutine PGCRFN defines separable pairs of non-linear
                coordinate systems for PGSBOX.  Linear, logarithmic and
                power-law axis types are currently defined.  Further types may
                be added as required.

   pgtest.f     FORTRAN test and demo program and coding example.
   cpgtest.f    C test and demo program and coding example.
   fscan.f      Defines a non-linear coordinate grid for PGTEST and cpgtest.
   lngvel.f     Defines a non-linear coordinate grid for PGTEST and cpgtest.


Usage notes
-----------
The prologue to pgsbox.f contains usage instructions.  pgtest.f and cpgtest.c
serve as test and demonstration programs and also as well-documented examples
of usage.


FORTRAN and C
-------------
PGPLOT is implemented as a FORTRAN library with a set of C wrapper routines
that are generated by a software tool.

PGSBOX has a more complicated interface than any of the standard PGPLOT
routines, especially in having an EXTERNAL function in its argument list.
Consequently, PGSBOX has been implemented in FORTRAN but with a hand-coded C
wrapper.

While there are no formal standards for calling FORTRAN from C, there are some
fairly well established conventions.  Nevertheless, it's possible that you may
need to modify the code if you use a combination of FORTRAN and C compilers
with linkage conventions that differ from that of the GNU compilers, gcc and
g77.

As an example, in this suite the C test/demo program, cpgtest, calls the C
wrapper, cpgsbox(), passing it a pointer to a C function, pgwcsl_(), that has
a FORTRAN-like interface but links to WCSLIB 3.x, a C library.  In turn,
cpgsbox() calls PGSBOX, which invokes pgwcsl_() as an EXTERNAL subroutine.
In this sequence, a complicated C struct defined by cpgtest is passed through
PGSBOX to pgwcsl_() as an INTEGER array.


Installation notes
------------------
A simple-minded GNU makefile is provided; GNU make must be used.  It assumes
that you will be compiling with gcc and g77 and that WCSLIB 3.x has already
been built in ../C, and the FORTRAN and C include files reside in ../FORTRAN
and ../C (as in the distribution kit).  It's quite likely that you will to
modify the makefile for your own purposes.

The makefile compiles pgsbox.o as a dependency of pgtest, and cpgsbox.o as a
dependency of cpgtest.

It is suggested that pgsbox.o and pgcrfn.o be inserted in libpgplot.a;
cpgsbox.o in libcpgplot.a; and pgwcsl.o in libwcs.a.  cpgsbox.h should reside
with your other PGPLOT header files.


Author
------
Mark Calabretta, Australia Telescope National Facility
mcalabre@atnf.csiro.au

$Id: README,v 3.4 2004/02/10 23:56:37 mcalabre Exp $
