------------------------------------------------------------------------------
                                  PGSBOX 4.1
------------------------------------------------------------------------------
    PGSBOX 4.1 - a non-linear coordinate axis plotter for PGPLOT.
    Copyright (C) 1997-2005, Mark Calabretta

    PGSBOX is free software; you can redistribute it and/or modify it under
    the terms of the GNU General Public License as published by the Free
    Software Foundation; either version 2 of the License, or (at your option)
    any later version.

    PGSBOX is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
    details.

    You should have received a copy of the GNU General Public License along
    with PGSBOX; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA
------------------------------------------------------------------------------

PGSBOX is a PGPLOT routine (FORTRAN) that 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 is 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 GNU makefile is provided; GNU make (referred to below as gmake) must be
used.  A few variables that you may need to tailor for your purposes are
defined at the start of the makefile; instructions are given in the makefile
itself.

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 4.1 2005/08/19 14:07:45 cal103 Exp $
