Updated some top level docs and added some cygwin config example files

to help with compiling external dependencies.

BUGS

@@ -1,3 +1,4 @@
+
 BUG REPORTS
 -----------
 

COPYING

@@ -1,4 +1,4 @@
-  Copyright (c) 1997-2004 by the contributors named in the individual files. 
+  Copyright (c) 1997-2006 by the contributors named in the individual files. 
   All rights reserved.  This distribution is free software; you can
   redistribute it and/or modify it under the same terms as Perl itself.
 

Changes

@@ -1,4 +1,9 @@
-CED 13-AUg-2006
+CHM 14-Aug-2006
+    Touch up top level documentation files and add some config
+    files to PDL/cygwin/.  Files changed: BUGS, COPYING,
+    DEPENDENCIES, DEVELOPMENT, INSTALL, Known_problems, README,
+    Release_Notes, cygwin/INSTALL, cygwin/README.
+CED 13-Aug-2006
     - Minor fixes to Transform -- t_fits CI_J header notation;
       also: dims copied between params and main object in 
       t_spherical and t_projective.

DEPENDENCIES

@@ -1,14 +1,18 @@
 
 PDL Module Dependencies
+=======================
 
-This file lists dependencies of PDL modules on external programs/libraries.
-Some of the modules will build ok without the external software but in
-general are not very useful without it. Others require certain
-libraries/include files to be installed. See INSTALL on hints how to
-enable/disable building of some modules in the distrib if required.
+This file lists dependencies of PDL modules on external
+programs/libraries. Some of the modules will build ok
+without the external software but in general are not very
+useful without it. Others require certain libraries/include
+files to be installed. See INSTALL on hints how to
+enable/disable building of some modules in the distrib if
+required.
 
-The easiest way to resolve dependencies on other Perl modules is to use
-the CPAN module to install PDL. Installation should be as simple as
+The easiest way to resolve dependencies on other Perl
+modules is to use the CPAN module to install PDL.
+Installation should be as simple as
 
   cpan install PDL   # if the cpan script is in your path
 
@@ -20,29 +24,28 @@ or if you don't have the cpan script try
 
 MODULE          DEPENDS ON                  COMMENT
 
-PDL (all)	perl >= 5.6.x		you need at least this version
-		(5.8.x recommended)	of perl to succeed.
+PDL (all)       perl >= 5.6.x           you need at least this version
+                (5.8.x recommended)     of perl to succeed.
 
-		File::Spec		version >= 0.6 required, included
-					with recent perls (5.6.x and higher)
+                File::Spec              version >= 0.6 required, included
+                                        with recent perls (5.6.x and higher)
 
-PDL::NiceSlice  Text::Balanced		a nicer way to index piddles
-		Filter			a must-have!!
+PDL::NiceSlice  Text::Balanced          a nicer way to index piddles
+                Filter                  a must-have!!
 
-Inline::Pdlpp	Inline			version >= 0.43 required
-					module allows to define fast PP code
-					inline in your scripts
+Inline::Pdlpp   Inline                  version >= 0.43 required
+                                        module allows to define fast PP code
+                                        inline in your scripts
 
-perldl (shell)  Term::ReadLine    	perl provides a stub but if you
-					compile and install a better one
-					(Term::ReadLine or
-					Term::ReadLine::Gnu) you get proper
-					command line editing
+perldl (shell)  Term::ReadLine          perl provides a stub but if you
+                                        compile and install a better one
+                                        (Term::ReadLine or Term::ReadLine::Gnu)
+                                        you get proper command line editing
 
 PDL::Graphics::TriD
-		perl 5.6 &
+                perl 5.6 &
                 Requires OpenGL implementation. For free implementation
-                check out Mesa at http://www.ssec.wisc.edu/~brianp/Mesa.html
+                check out Mesa at http://www.mesa3d.org/
 
                                         Required. Module won't build
                                         without libraries. To disable
@@ -51,7 +54,7 @@ PDL::Graphics::TriD
 PDL::Graphics::PGPLOT
                 PGPLOT perl module and PGPLOT fortran library,
                 see http://astro.caltech.edu/~tjp/pgplot for the library
-                and CPAN or http://www.aao.gov.au/local/www/kgb/pgperl
+                and CPAN at http://search.cpan.org/search%3fmodule=PGPLOT
                 for the perl module
 
                                         Module builds ok without
@@ -74,7 +77,7 @@ PDL::Graphics::IIS
 
 PDL::Graphics::Karma
                 Needs Karma visualisation library and tools.
-                See http://www.atnf.csiro.au/karma. Binary distribs
+                See http://www.atnf.csiro.au/karma . Binary distribs
                 for many popular platforms available
 
                                         Module will only be built
@@ -83,56 +86,61 @@ PDL::Graphics::Karma
 
 PDL::IO::Pic
                 rpic/wpic: pbm+ or netpbm converters
-                 ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM
+                 http://netpbm.sourceforge.net/
                  and ftp://ftp.uu.net/graphics/jpeg for jpeg converter
 
                 wmpeg: mpeg_encode program,
-                  see ftp://mm-ftp.cs.berkeley.edu/pub/multimedia/mpeg/encode
+                  see http://bmrc.berkeley.edu/ftp/pub/multimedia/mpeg/encode/
 
                                         Module builds
                                         ok without converters
 
-PDL::Slatec	ExtUtils::F77		linear algebra routines
-					several other modules use PDL::Slatec
+PDL::Slatec     ExtUtils::F77           linear algebra routines
+                                        several other modules use PDL::Slatec
+
                 Slatec fortran lib is included but requires a
-		fortran compiler and the perl module ExtUtils::F77
-		(version >= 1.03) to be installed.
+                fortran compiler and the perl module ExtUtils::F77
+                (version >= 1.03) to be installed.
 
                                         Will not be built unless
                                         ExtUtils::F77 (version >= 1.03)
-					is installed and Extutils::F77
-					supports your platform.
+                                        is installed and Extutils::F77
+                                        supports your platform.
+
 PDL::GSL modules
                 Needs the GSL (Gnu Scientific Library) to build.
-		Version >= 1.0 is required
-		See http://sourceware.cygnus.com/gsl/
+                Version >= 1.0 is required
+                See http://www.gnu.org/software/gsl/
 
                                         Will not be built unless
-					GSL is installed.
+                                        GSL is installed.
+
 PDL::FFTW
-                Needs the FFTW to build. (A free C FFT library
-                including multi-dimensional, real, and parallel
-                transforms) 
-		See http://www.fftw.org/
+                Needs the FFTW version 2 (not 3!) to build. (A free C
+                FFT library including multi-dimensional, real, and parallel
+                transforms) See http://www.fftw.org/
 
                                         Will not be built unless
-					FFTW is installed.
+                                        FFTW is installed.
 
 PDL::IO::Browser
-		Requires a 'curses'-compatible library
-		not built by default (edit perldl.conf to enable)
+                Requires a 'curses'-compatible library
+                not built by default (edit perldl.conf to enable).  Build
+                appears to be broken for many platforms.
 
 PDL::IO::FITS   Needs Astro::FITS::Header for full support of all FITS
-                header features.  Will build ok, and run, without it.
+                header features.  Will build ok, and run, without it but
+                for given that Astro::FITS::Header is a Perl only module,
+                you should install it unless you specifically need not.
+                It is currently listed as a prerequisite module for the
+                purposes of building with the cpan shell.
 
 PDL::IO::NDF
                 Requires the perl/NDF interface (NDFPERL).
                 (which also requires a fortran compiler and the
-                fortran NDF library). See either
-                http://www.jach.hawaii.edu/jcmt_sw/perl/ or
-                http://www.starlink.rl.ac.uk/cgi-store/storeform2?NDFPERL
-                for information on NDFPERL. See
-                http://www.starlink.rl.ac.uk/cgi-store/storeform2?NDF
+                fortran NDF library). Get the STARPERL package from
+                http://www.starlink.rl.ac.uk/cgi-store/storeform2?STARPERL
+                to get NDFPERL. See http://www.starlink.rl.ac.uk/cgi-store/storeform2?NDF
                 to retrieve the NDF libraries.
 
                                         Module builds ok without

DEVELOPMENT

@@ -1,3 +1,4 @@
+
 This file has some information on how to get access to
 the latest PDL sources (mainly of interest for potential
 developers). This should not be confused with the latest
@@ -11,7 +12,7 @@ From version PDL-2.003 onwards the source distribution is in a
 publicly accessible CVS repository. The project is hosted at the
 sourceforge site at
 
-  http://www.sourceforge.org/project/?form_grp=612
+  http://sourceforge.net/projects/pdl/
 
 Starting from that URL you will find directions on how to check out
 the current sources, browse the CVS repository online, etc.
@@ -22,12 +23,13 @@ URL) to apply for write access to the repository. We strongly believe
 in the power of open source development!
 
 If you do not know how to use CVS try 'man cvs' or 'info cvs' and/or
-have a look at some of the online tutorials available on the web. A
-nice concise one is at
+have a look at some of the online tutorials available on the web.
+The main CVS home page is at
 
-  http://www.cyclic.com/cvs/doc-blandy-text.html
+  http://www.nongnu.org/cvs/
 
-and a very good/complete one is the online version of the CVS book at
+and a very good/complete CVS reference is the online version of the
+CVS book at
 
   http://cvsbook.red-bean.com/cvsbook.html
 
@@ -54,20 +56,21 @@ PDL CVS repository.
 
 2) Make sure you add a test case in the 't' directory for any
    significant additional capability you add to the PDL package.
-   Please use one the Test modules available within Perl - ie
-   "use Test::More;" - rather than doing-it-yourself as most of
-   our tests
-   do!
+   Please use one the of the Test modules available within Perl
+   rather than doing-it-yourself as many of our tests do!  The
+   recommended testing module is Test::More which now distributed
+   with the perl distribution.
 
 3) Don't commit before you successfully built and passed 'make
-   test'. But then again, don't keep your changes private for too long
-   to avoid conflicts with other developers.
+   test'. But then again, don't keep your changes private for too
+   long to avoid conflicts with other developers.
 
 4) Bugs reported on the list should be entered into the bug database
    and bugs closed when a patch has been committed as a fix. (Primary
    responsibility for this task is the pumpking, but other devels
    should be able to help.)
 
+
 PDL Developer Notes:
 --------------------
 
@@ -79,16 +82,16 @@ improve or add to PDL (please do):
 See the pdl-porters email list; details for subscription and access to
 the archives can be found on the PDL web page at:
 
-  http://pdl.perl.org/maillists/index_en.html
-  http://pdl.perl.org/maillists/index_de.html
+  http://pdl.perl.org/maillists/index_en.html  (English)
+  http://pdl.perl.org/maillists/index_de.html  (German)
 
 *) Access to PDL's configuration
 
 If you need to access the configuration for PDL then use the
 %PDL::Config variable. Prior to 2.4.1 this was a mess since you
 had to use %PDL_CONFIG within Makefile.PL and PDL::Config from
 *.pm/tests. The build process has been changed (I hesitate to say
-"cleaned up" ;) to just use %PDL::Config.
+"cleaned up" ;) to just use %PDL::Config consistently throughout.
 
 - %PDL::Config is automatically available to you when you are in a
   Makefile.PL within the PDL distribution. You can change the hash

INSTALL

@@ -9,6 +9,8 @@ upgrade get at least this version.
 
 See win32/INSTALL for details on installing PDL on windows platforms.
 
+See cygwin/INSTALL for details on installing PDL on cygwin platforms.
+
 The file DEPENDENCIES summarizes the dependencies of various
 PDL modules on libraries/other packages. The location of
 some of these files needs to be specified in the file perldl.conf.
@@ -25,6 +27,10 @@ or if you don't have the cpan script try
   perl -MCPAN -e shell
   cpan> install PDL
 
+NOTE: if this is your first time running the cpan shell, you'll be
+propted to configure the running environment.
+
+
 perldl.conf
 -----------
 
@@ -72,6 +78,7 @@ There is also another make item:
 
 creates the documentation database for use in the perldl shell.
 
+
 f77 configuration
 -----------------
 
@@ -89,6 +96,7 @@ Note that almost always it is better to use ExtUtils::F77. Only use the
 F77CONF mechanism if you have a good reason to. Win32 is special. See
 win32/INSTALL.
 
+
 COMMON PROBLEMS
 ---------------
 

Known_problems

@@ -12,35 +12,32 @@ PDL:
   including for the following files: PLplot.xs, GD.xs, GD.c, INTERP.xs,
   RNG.xs, and RNG.c.
 
-? Modern versions of MakeMaker (e.g. 6.22) fail to compile PDL, apparently
-? because of the removal of the magic pm_to_blib target.  Current
-? versions (such as 6.17, bundled with the current perl, v5.8.6) work OK. 
-? With PDL 2.4.2, we have followed the core perl team in our use of
-? earlier MakeMaker versions.
-
-? If @INC has '.' at the front of the search path part of the build will
-? fail (specifically mkpdlconv will not be able to 'use English' since
-? it uses Exporter.pm from Basic/Core and not the system Exporter.pm).
-?   [added by Tim Jenness on 15 Apr 2000]
-?   [This appears to be fixed but this note is left FYI for the 2.4.2 release -- CED 16-Dec-2004 ]
-
-? PDL::Graphics::TriD doesn't seem to link correctly on the Mac, under 
-? MacOS 10.5 & 10.6.  It has not been fixed in part because TriD needs an 
-? overhaul anyway, and in part because the code is cryptic.  If you'd like 
-? to fix it, please do!  Patches welcome.  (PDL::Graphics::TriD is disabled
-? by default on Mac installs, thanks, Doug)
-
-? SourceForge bugs outstanding at time of release:
-?
-?   1530666  bugs in Transform.pm
-?   1505171  failure in MatrixOps::eigens in CVS
-?   1476324  How to force a completely clean installation
-?   1465864  limits_round.t test failure
-?   1465603  flexraw fails on Intel OS X with gfortran
-?   1465414  Need lib64 version in various lib search paths for AMD64
-?   1435189  Installation with cpan2rpm
-?   1339530  pdlcore.c fails to build on IRIX and AIX
-?   1205359  PGPLOT Window does not store full state info
+- Modern versions of MakeMaker (e.g. 6.22) fail to compile PDL, apparently
+  because of the removal of the magic pm_to_blib target.  Current
+  versions (such as 6.17, bundled with the current perl, v5.8.6) work OK. 
+  With PDL 2.4.2, we have followed the core perl team in our use of
+  earlier MakeMaker versions.  As of PDL 2.4.3 this may have been resolved.
+  If it works for you, please let us know!  Thanks.
+
+- PDL::Graphics::TriD doesn't seem to link correctly on the Mac, under 
+  MacOS 10.5 & 10.6.  It has not been tested for the 2.4.3 release.  The
+  TriD build has been cleaned so this problem may have been resolved.
+  If you'd like to test/fix it, please do!  Patches welcome.
+  (PDL::Graphics::TriD is disabled by default on Mac installs, edit
+   the perldl.conf file if you wish to test this feature)
+
+- The following SourceForge bugs are outstanding at time of the 2.4.3
+  point release:
+
+  1530666  bugs in Transform.pm
+  1505171  failure in MatrixOps::eigens in CVS
+  1476324  How to force a completely clean installation
+  1465864  limits_round.t test failure
+  1465603  flexraw fails on Intel OS X with gfortran
+  1465414  Need lib64 version in various lib search paths for AMD64
+  1435189  Installation with cpan2rpm
+  1339530  pdlcore.c fails to build on IRIX and AIX
+  1205359  PGPLOT Window does not store full state info
 
 For more information on these and other PDL issues, and for
 submissions of patches (bug patches are always welcome!),