move PGPLOT-specific notes out of PDL to PGPLOT module docs

lib/PGPLOT.pm

@@ -44,14 +44,14 @@ PGPLOT - allow subroutines in the PGPLOT graphics library to be called from Perl
 
  use PGPLOT;
 
- pgbegin(0,"/xserve",1,1);  
- pgenv(1,10,1,10,0,0);        
- pglabel('X','Y','My plot');  
+ pgbegin(0,"/xserve",1,1);
+ pgenv(1,10,1,10,0,0);
+ pglabel('X','Y','My plot');
  pgpoint(7,[2..8],[2..8],17);
 
  # etc...
 
- pgend;           
+ pgend;
 
 =head1 DESCRIPTION
 
@@ -73,7 +73,7 @@ How the function calls map on to Perl calls is detailed below.
 
 =head2 Argument Mapping - Simple Numbers And Arrays
 
-This is more or less as you might expect - use Perl scalars 
+This is more or less as you might expect - use Perl scalars
 and Perl arrays in place of FORTRAN/C variables and arrays.
 
 Any FORTRAN REAL/INTEGER/CHARACTER* scalar variable maps to a
@@ -84,7 +84,7 @@ Thus you can say:
 
 To draw a line to point (42,$x):
 
- pgdraw(42,$x); 
+ pgdraw(42,$x);
 
 To plot 10 points with data in Perl arrays C<@x> and C<@y> with plot symbol
 no. 17. Note the Perl arrays are passed by reference:
@@ -117,14 +117,14 @@ from Perl:
 
 =item 1.
 
-Simply pass a reference to a 2D array, e.g: 
+Simply pass a reference to a 2D array, e.g:
 
   # Create 2D array
 
   $x=[];
-  for($i=0; $i<128; $i++) { 
+  for($i=0; $i<128; $i++) {
      for($j=0; $j<128; $j++) {
-       $$x[$i][$j] = sqrt($i*$j); 
+       $$x[$i][$j] = sqrt($i*$j);
      }
   }
   pggray( $x, 128, 128, ...);
@@ -134,9 +134,9 @@ Simply pass a reference to a 2D array, e.g:
 Pass a reference to a 1D array:
 
   @x=();
-  for($i=0; $i<128; $i++) { 
+  for($i=0; $i<128; $i++) {
      for($j=0; $j<128; $j++) {
-       $x[$i][$j] = sqrt($i*$j); 
+       $x[$i][$j] = sqrt($i*$j);
      }
   }
   pggray( \@x, 128, 128, ...);
@@ -151,7 +151,7 @@ as long as the number of elements match.
 If your image data is packed in raw binary form into a character string
 you can simply pass the raw string. e.g.:
 
-   read(IMG, $img, 32768); 
+   read(IMG, $img, 32768);
    pggray($img, $xsize, $ysize, ...);
 
 Here the C<read()> function reads the binary data from a file and the
@@ -168,17 +168,17 @@ binary data.
 I<Please Note>: As PGPLOT is a Fortran library it expects its images to be
 be stored in row order. Thus a 1D list is interpreted as a sequence of
 rows end to end. Perl is similar to C in that 2D arrays are arrays of
-pointers thus images end up stored in column order. 
+pointers thus images end up stored in column order.
 
 Thus using perl multidimensional arrays the coordinate ($i,$j) should be
 stored in $img[$j][$i] for things to work as expected, e.g:
 
    $img = [];
-   for $j (0..$nx-1) for $i (0..$ny-1) { 
+   for $j (0..$nx-1) for $i (0..$ny-1) {
       $$img[$j][$i] = whatever();
    }}
    pggray($$img, $nx, $ny, ...);
-   
+
 Also PGPLOT displays coordinate (0,0) at the bottom left (this is
 natural as the subroutine library was written by an astronomer!).
 
@@ -266,6 +266,93 @@ Source code is available at either of these sites
 
 =back
 
+=head2 Cygwin
+
+Build the pgplot library and install as above, but with these notes in mind.
+
+Edit drivers.list to enable the drivers you wish but
+uncommenting desired drivers by removing the leading ! on the
+line. Here are the ones used by a previous PDL maintainer:
+
+  $ grep -v '^!' drivers.list
+    LXDRIV 0 /LATEX     LaTeX picture environment
+    NUDRIV 0 /NULL      Null device (no output)                           Std F77
+    PPDRIV 1 /PPM       Portable Pixel Map file, landscape
+    PPDRIV 2 /VPPM      Portable PIxel Map file, portrait
+    PSDRIV 1 /PS        PostScript printers, monochrome, landscape        Std F77
+    PSDRIV 2 /VPS       Postscript printers, monochrome, portrait         Std F77
+    PSDRIV 3 /CPS       PostScript printers, color, landscape             Std F77
+    PSDRIV 4 /VCPS      PostScript printers, color, portrait              Std F77
+    TTDRIV 5 /XTERM     XTERM Tektronix terminal emulator                 Std F77
+    WDDRIV 1 /WD        X Window dump file, landscape
+    WDDRIV 2 /VWD       X Window dump file, portrait
+    XWDRIV 1 /XWINDOW   Workstations running X Window System              C
+    XWDRIV 2 /XSERVE    Persistent window on X Window System              C
+
+  $ vi sys_cygwin/g77_gcc.conf
+
+  # This diff command shows the lines that need changing
+  $ diff g77_gcc.conf*
+  12c12
+  <    XINCL="-I/usr/X11R6/include"
+  ---
+  >    XINCL="-I/usr/X11R6.4/include"
+  48c48
+  <    FFLAGD="-fno-backslash -I/usr/include"
+  ---
+  >    FFLAGD="-fno-backslash"
+  58c58
+  <    CFLAGC="-DPG_PPU -O2 -DNOMALLOCH -I. -I/usr/include"
+  ---
+  >    CFLAGC="-DPG_PPU -O2 -DNOMALLOCH -I."
+  75c75
+  <    LIBS="-L/usr/X11R6/lib -lX11 -lpng -lz"
+  ---
+  >    LIBS="-L/usr/X11R6.4/lib -lX11"
+
+  $ ~/pgplot/makemake ~/pgplot cygwin
+  $ make
+  $ make clean
+  $ make cpg
+  $ PGPLOT_DIR="/usr/local/pgplot/"; export PGPLOT_DIR
+
+Be sure to add C<PGPLOT_DIR> to your environment and add it to
+your PATH as well.
+
+NOTE: if problems occur, you may need to C<rebaseall> your libraries.
+
+=head1 PNG OUTPUT
+
+If PGPLOT does not write out PNG files, check these things.
+First, when compiling the pgplot libraries, make sure you uncomment the PNG
+entries in the F<drivers.list> file. Then when running 'make' you
+probably got an error like
+
+  C<make: *** No rule to make target `png.h', needed by `pndriv.o'.  Stop.>
+
+To fix this, find the line in the 'makefile' that starts with
+'pndriv.o:' (it's near the bottom). Change, for example, ./png.h to
+/usr/include/png.h, if that is where your header files are (you do
+have the libpng and libz devel packages, don't you?).  Do this for all
+four entries on that line, then go back and run C<make>.
+
+Second, if you already have the PGPLOT Perl module and PDL installed,
+you probably tried to write out a PNG file and got fatal error message
+like:
+
+  C<undefined symbol: png_create_write_struct>
+
+This is because the PGPLOT Perl module does not automatically link
+against the png and z libraries. So when you are installing the PGPLOT
+Perl module (version 2.19) from CPAN, don't do C<install PGPLOT>, but
+just do C<get PGPLOT>. Then exit from CPAN and manually install
+PGPLOT, calling the makefile thusly:
+
+  C<perl Makefile.PL EXLIB=png,z EXDIR=/usr/lib>
+
+assuming that there exist files such as /usr/lib/libpng.so.*,
+/usr/lib/libz.so.*. Then do the standard C<make;make test;make
+install;> sequence. Now you can write png files from PDL!
 
 =head1 AUTHORS