GnuDraw  -- General comments
----------------------------
GnuDraw is an ox package meant for creating GnuPlot graphics from Ox.
The interface is completely based on the work of Jurgen Doornik, in his
OxDraw package. Likewise, the documentation (see gnudraw.html, referred
to below) is also largely a copy of Jurgen Doornik's oxdraw.html.

On Unix, SetDrawWindow can be used to have the graphs appear in the
same screen for every new plot, thus allowing for animations to appear
on screen. See packages/gnudraw/samples/ar1.ox.

The resulting GnuPlot-files are in plain ASCII, and can be adapted to 
fit final needs.

Output of the GnuPlot files can be of many different types. Included is
support for EPS (bw and color), PDF, PNG (gif-like format), SVG, XFIG,
and TeX.

Apart from these general comments, below are given short usage
instructions, an overview of the extended functionality of GnuDraw,
installation instructions, a description of directories, of script/batch
files, and of sample files.


GnuDraw  -- Usage
-----------------
Usage of GnuDraw is intended to be simple. Use it just like you would
use the original ox drawing routines, changing only the line
  #include <oxdraw.h>
to
  #include <packages/gnudraw/gnudraw.h>

See the original ox documentation for usage instructions of the normal
routines, and also the file packages/gnudraw/doc/gnudraw.html for
gnudraw-specific explanation


GnuDraw  -- Extended functionality
----------------------------------
First of all, extra output formats are available in GnuDraw. GIF images
can be created for use on web pages, and pure (Pic)TeX for inclusion in
TeX documents. The GnuPlot output files are more easily edited (also on
Unix) to change the final appearance of graphs, without having to resort
to re-running the Ox-programs or changing to a Windows computer to run
GiveWin.

Other extensions include:
  DrawTitle             Includes the option (using -1 as the area
                        designator) to put a title on top of the entire
                        graphing area, instead of only on top one of
                        the windows.
  DrawACF, DrawCorrelogram                        
                        Option is included to combing plots of the
                        autocorrelation function into one graphing
                        window.
  DrawBivDensity        Draw a bivariate density plot of a multivariate
                        sample
  DrawDensity, DrawBivDensity
                        Includes the option to plot a density of a
                        weighted sample.
  DrawXYZ               Draw a surface/contour plot of XYZ data
  DrawT, DrawTMatrix    Now includes the possibility to draw irregularly
                        spaced time series data.
  DrawAdjust            Options are included to plot a series against a 
                        second x- or y-axis.
  SetDrawWindow         On Unix, the graphics output can be directed
                        to appear in the same plot window over and over
                        again, allowing updating of graphs as in the
                        Windows version in combination with GiveWin.                        


GnuDraw -- Installation instructions
------------------------------------
To install GnuDraw version 6, follow the next steps:

 (1) Unzip the file <a href="software/gnudraw7.zip">gnudraw7.zip</a> from
     your Ox folder (using folder names). This creates files in the
     directory <ox-home>/packages/gnudraw, and a few in <ox-home>/bin. 
     In this case, no change of the OX7PATH environment variable is
     needed. The <ox-home> directory can be /usr/share/oxmetrics7/ox (on
     Unix), /Apps/oxmetrics7/ox (on Mac OS X), or e.g. c:\program
     files\oxmetrics7\ox (on Windows)

     Installation in a local directory is also possible; e.g. if you
     install GnuDraw under Windows in h:\bin\ox, resulting in files in
       h:\bin\ox\packages\gnudraw
     then make sure that the directory h:\bin\ox is included in the OX7PATH
     variable. Set this variable on Windows XP using 
      Start - Settings - Control panel - System
    Choose tab 'Advanced', button 'Environment variables' and set a user
    variable with name
      OX7PATH          
    and value
      h:\bin\ox;c:\progra~1\oxmetrics7\ox\include;c:\progra~1\oxmetrics7\ox
    Note that, if you installed 32-bit Ox on 64-bit Windows, you may
    need to set 
      OX7PATH=h:\bin\ox;c:\progra~2\oxmetrics7\ox\include;c:\progra~2\oxmetrics7\ox
    instead, where c:\progra~2 refers to the "c:\program files (x86)"
    directory.  
(2a Unix)
     Install GnuPlot if it wasn't done before, by downloading and
	 installing the lastest rpm or other package. Use version 4.2 or
     higher. RPMS or deb-files should come included with your
     distribution, or install from source downloading from
	 SourceForge.net
       	   http://sourceforge.net/project/showfiles.php?group_id=2055
(2b Windows)	 
     Install GnuPlot if it wasn't done before. Download the windows
     binary from 
	   http://sourceforge.net/project/showfiles.php?group_id=2055
	 Unzip the file into
	   c:\program files\
     (or into
       c:\program files (x86)\
     on 64-bit Windows.
     
	 Check afterwards that the wgnuplot.exe binary indeed ended up in
	   c:\program files\gnuplot\binary\ 
     If you cannot write the binary in this directory, you can instead
     set a user variable
       set GNUPLOTEXEC=h:\bin\gnuplot\binary\wgnuplot.exe
     as explained above for OX7PATH (if you unzipped GnuPlot in h:\bin) 
     to indicate the full location of the executable.
(2c Mac OS X)
    Install GnuPlot if it wasn't done before, by first installing 
    MacPorts, downloading the dmg for your system from
    http://www.macports.org/install.php and double-clicking on the pkg
    inside. Then, from a terminal, type
      sudo port upgrade --force installed
      sudo port install gnuplot 
(3 Unix, optional)
     Copy (a link to) 
       /usr/share/oxmetrics7/ox/packages/gnudraw/bin/plb2x
     to a directory in your path, e.g. using 
       cd ~/bin
       ln -s /usr/share/oxmetrics7/ox/packages/gnudraw/bin/plb2x
(3 Mac OS X, optional)
     Copy (a link to) 
       /Apps/oxmetrics7/ox/packages/gnudraw/bin/plb2x
     to a directory in your path, e.g. using 
       cd ~/bin
       ln -s /Apps/oxmetrics7/ox/packages/gnudraw/bin/plb2x
(3 Windows, optional)
     Include the <ox-home>\bin directory in your path (if it wasn't
     already) or copy the file
       c:\program files\ox\packages\gnudraw\bin\plb2x.bat
     to directories in your path.       
(4a) Put the file packages/gnudraw/doc/gnudraw.html in your list of
     bookmarks, or, better even,
(4b) Edit <ox-home>/doc/oxmenu.html, adding a line
       <tr><td><a href="../packages/gnudraw/doc/gnudraw.html">GnuDraw graphics</a></td></tr>
     after the line referring to the original OxDraw documentation
     such that the documentation is available from the standard Ox
     documentation.

(5 Optional)
     Associate files with extension .plt with
	   c:\progra~1\gnuplot\bin\wgnuplot.exe
	 and those with extension .plb with the batch file
	   <ox-home>/packages/gnudraw/bin/plb2x (Unix)
	 or
       <ox-home>\packages\gnudraw\bin\plb2x.bat (Windows)
(6 Optional)
     For use in OxEdit, one could create extension for managing GnuDraw
     plots in the modules menu, from the menu item
       Preferences - Add/remove modules - Load from
     and point to the file 
       packages/gnudraw/oxedit_gnudraw.tool
     This will add entries to run OxGauss through GnuDraw, to run
     GnuPlot, and to transform plb-files to EPS, PNG, or show them on
     screen.    

On all Windows systems you can encounter an error message of the type
  "Windows cannot find 'C:\Progam'.  Make sure you typed the name
   correctly, and then try again." 
In this case, you should get rid of spaces in your path/OX7PATH
statements. You can do so by changing in your Configuration
Panel-System-Advanced-Environmental variables the variables OX7PATH and
PATH to read
  c:\progra~1
every time that a 
  c:\program files  
was there originally. If your OX7PATH variable was not available yet,
create a USER VARIABLE with the value
  c:\progra~1\oxmetrics7\ox;c:\progra~1\oxmetrics7\ox\include;
Under Windows XP you can also reach these variables through My
Computer; a right-click gets you to Properties, Advanced, Environmental
Variables, Variable.

GnuDraw  -- Directories
-----------------------
Included in the file gnudraw7.zip are the following directories:
  bin/
      Unix/Dos/Windows batch files used for getting gnuplot output converted
  packages/gnudraw/doc
      The documentation in HTML format
  packages/gnudraw/
      The gnudraw package itself, and this explanation file
  packages/gnudraw/lib
      Libraries for computing kernel approximation to a density, and
	  also for building bivariate plots using the oxdraw plotting
	  routines
  packages/gnudraw/samples
      Example files


GnuDraw  -- Sample files
------------------------
In the directory <ox-home>/packages/gnudraw/samples/ some example files
are given. The ox-programs create the gnuplot files, and if possible
will create the eps/png/latex graphic files. Running gnuplot on files
with extension *.plt recreates the final graphic files, which can be
viewed using Ghostview or another image viewer, depending on the
graphic file type. The plb-files can be translated using batch file
plb2x.

Sample files include:
  ar1.ox          A copy of the simulation class example file in
                    <ox-home>/samples/simula/ar1.ox, only referring to
                  gnudraw instead of oxdraw. It shows the
                  possibilities of using SetDrawWindow to animate a
                  graph (works only on Unix).
  drawacf.ox      Show the drawing of multiple autocorrelation functions
                  together in one graphing window
  drawbiv.ox,     Display bivariate plotting capabilities
  drawbiv_ox.ox   This example uses the ox library densest, implementing
				  DrawBivDensity for oxdraw, without using gnudraw
				  (nor gnuplot) itself, and show the same bivariate 
                  plotting capabilities
  drawdensis.ox   Display a density plot for a weighted sample.
  drawfan.ox      Show some usage modes of drawing fan plots                  
  drawz.ox        Use several options of DrawZ
  example.ox      Creates the necessary files for example_latex.tex and
                  example_pdflatex.tex
  example_latex.tex,example_pdflatex.tex     
                  LaTeX files providing an example of inclusion of EPS
                  and TeX figures in LaTeX and PdfLaTeX.


GnuDraw  -- Script/batch files
------------------------------
Included in the directory packages/gnudraw/bin (Unix) or
packages/gnudraw/bat (Windows) are batch-files which simplify the use of
the output files with extension .plb. The batchfiles are called passing
along the filename (without extension, under Windows), and optionally
an indication of the font size and the size of the output graph.

Standard way of calling plb2x is
  plb2x [-size x y] [-fontsize z] [-type] <filename> [<filename2>]
where x and y indicate the size of the output graph (note that the the
measures depend on the type of file, e.g. in inches for fig-files, in
points for png, and as a scale up to 1 for eps or screen files), the
fontsize z, and type which can be 
  -scr  Show <filename> on the screen, default
  -eps  Build <filename>.eps in black & white
  -epsc Build <filename>.eps in color
  -emf  Build <filename>.emf in black & white
  -emfc Build <filename>.emf in color
  -gif  Build <filename>.gif
  -png  Build <filename>.png
  -pdf  Build <filename>.pdf
  -svg  Build <filename>.svg
  -tex  Build <filename>.tex, for inclusion in tex document, 
        using \input{<filename>.tex}
  -etex Build <filename>.tex and <filename>.eps, for inclusion in tex
        document, using \input{<filename>.tex}
On windows, the filenames have to be specified without the extension
.plb. Multiple filenames can be given in a row. 

GnuDraw  -- Further information
-------------------------------
- The GnuPlot help-file is quite extensive. I tend to use GnuDraw for
creating the rough graphs, saving the .plb files, and later on I
embellish the graphs if necessary changing the internal GnuPlot
commands in the ASCII file. In case of large difficulties, the
(very active) mailing list comp.graphics.apps.gnuplot may be of help.

- The file ps_guide.ps, included in many of the GnuPlot installations,
explains how to use enhanced postscript to include mathematical
symbols in the Encapsulated Postscript output of GnuPlot; the
necessary commands can be given from within Ox.

GnuDraw  -- Open ends
---------------------
The GnuDraw package is still under development. Newer versions
might appear once in a while. For information, check my homepage.

While creating graphs, temporary files are used. I try to delete all
such files after usage, but some might be left. These files may have
extensions *.log, or look like gd_<some number>.plt. 

Please let me know of installation problems, I was not able to check it
on many different systems. Also, please drop me a line if you encounter
bugs or are missing special functionality.


            Charles Bos
            c.s.bos@vu.nl
            http://personal.vu.nl/c.s.bos/
            February 28, 2012

