#set TITLE = "creating dynamic graphics and plots"
#include top


.SH Creating dynamic graphics and plots
QUISP allows dynamic creation of data graphics, charts, and plots
using an embedded instance of the
#set FILE = "http://ploticus.sourceforge.net"
#set TAG = "ploticus data display engine."
#include link
This is done using \fBquisp_pl\fR, an graphic-enabled instance of QUISP 
(see the
#set FILE = "http://quisp.sourceforge.net/download"
#set TAG = "quisp download page)."
#include link
The recommended strategy is to create a temporary image file (eg. PNG), then have the browser 
display it using \fC<img src=..>\fR.
#set FILE = "#setup"
#set TAG = "More about quisp_pl and getting graphics to work.."
#include link

#include space

.SH #graphic - #endgraphic
Graphic specifics are encapsulated within\fC#graphic\fR and \fC#endgraphic\fR directives.
Ploticus prefabs or script code can be used.
Ploticus command line arguments may be specified using \fC#arg\fR (see examples below).
Usage:
.nf
 \0 #graphic  \fIresulttype   resultfilename\fR
 \0   #arg  \fIcommandline args 1\fR
 \0   #arg  \fIcommandline args 2\fR
 \0   ...
 \0   \fIploticus script code\fR
 \0 #endgraphic
.LP
\fIresulttype\fR is \fCpng\fR, \fCgif\fR, \fCsvgz\fR etc.
\fIresultfilename\fR is the pathname of a file where the image will be written.
The \fC#arg\fR directive (described below) supplies ploticus command line arguments.
\fC#endgraphic\fR terminates the construct; when the interpreter reaches the \fC#endgraphic\fR
line the graphic result file is actually generated and written to disk.
To display the graphic,
use an \fC<img>\fR tag (after the \fC#endgraphic\fR) 
containing a URL which references the image file.

#include space2
.SH #arg
Set one
#set FILE = "http://ploticus.sourceforge.net/doc/pl.1.html#options"
#set TAG = "ploticus command line argument"
#include link
or argument pair.
\fC#arg\fR must be used before any ploticus code is referenced.
All arguments are supported except \fC-f\fR and \fC-ver\fR.

#include space2
.SH Examples
The
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index#graphic"
#set TAG = "dynamic graphic demo on sourceforge"
#include link
is a good first example.  Here are some others:
.LP
1. Invoke a ploticus prefab
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @@UNIQ ".png"
  \0 #graphic  png  @@HTMLPATH/tmp/@@FILENAME
  \0   #arg  -prefab  vbars
  \0   #arg  -scale 0.8
  \0   #arg  data=@@datafile
  \0   #arg  x=1
  \0   #arg  y=2
  \0 #endgraphic
  \0 <img src="@@HTMLURL/tmp/@@FILENAME">
.fi
#include space2

.LP
2. Execute a ploticus script via \fC#include\fR.
The ploticus script can reference \fBquisp\fR variables.
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @@UNIQ ".png"
  \0 #graphic  png  @@HTMLPATH/tmp/@@FILENAME
  \0   #arg  -scale 0.8
  \0   #include plscripts/try3.pl
  \0 #endgraphic
  \0 <img src="@@HTMLURL/tmp/@@FILENAME">
.fi
#include space2

.LP
3. Execute an embedded ploticus script.  
The ploticus script can reference \fBquisp\fR variables (eg. \fC@@datafile\fR).
The args will make debug output visible in the browser.
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @@UNIQ ".png"
  \0 #graphic  png  @@HTMLPATH/tmp/@@FILENAME
  \0   #arg -debug
  \0   #arg -diagfile stdout
  \0
  \0   #proc getdata
  \0     file: @@datafile
  \0   ...
  \0   #proc areadef
  \0    rectangle: 1 1 4 4
  \0   ...
  \0   #proc pie
  \0   ...
  \0 #endgraphic
  \0 <img src="@@HTMLURL/tmp/@@FILENAME">
.fi

#include space
.ig >>
<a name=setup></a>
.>>

.SH quisp_pl build notes
.LP
In order to produce embedded graphics and charts, you'll need \fBquisp_pl\fR.
This can be built from source code or downloaded in precompiled binary form for linux and solaris.
See the
#set FILE = "http://quisp.sourceforge.net/download"
#set TAG = "quisp download page."
#include link
To \fBquisp_pl\fR use \fCMakefile_pl\fR, a simple makefile that you can edit if needed.
The executable is named \fCquisp_pl\fR by default.
.LP
\fBlibploticus\fR may be configured and built to produce PNG files, JPEG, pseudo-GIF, etc.
All except pseudo-GIF require additional libraries such as ZLIB.  This is explained on the
ploticus download page and in the ploticus \fCMakefile_api\fR.

#include space

.SH Getting graphics to work..
If you use graphics on your site you can use quisp_pl for all your pages, or use quisp_pl 
for graphic pages and quisp for other pages.  The size and memory footprint of the quisp_pl 
executable is several times bigger than that of the quisp executable.
.LP
Beginners should stick with the names \fCquisp\fR and \fCquisp_pl\fR but
advanced users can choose other names if necessary.
.LP
You'll need to set HTMLURL, HTMLPATH, CGIPROG and CGIPROG_PL 
explicitly in your project \fCconfig\fR file.  Here's what I used for the quisp
sourceforge web site:
.nf
  varvalue:       HTMLURL=
  varvalue:       HTMLPATH=/home/groups/q/qu/quisp/htdocs
  varvalue:       CGIPROG=/cgi-bin/quisp
  varvalue:       CGIPROG_PL=/cgi-bin/quisp_pl
.fi
.LP
Your internal HTML links must use @@CGIPROG or @@CGIPROG_PL when linking between 
plain and graphic-enabled pages.
.LP
The recommended approach (as used in the above examples)
is to write the PNG (or whatever) result to your project \fC./tmp\fR directory.
So that your web server can find the image file, you'll need to set up a soft link from your 
html directory to the project \fC./tmp\fR directory.  The link may be named anything,
(the canned example assumes \fCtmp\fR).


#include space2

.LP
If you need to use a 
#set FILE = "http://ploticus.sourceforge.net/doc/config.html"
#set TAG = "ploticus config file"
#include link
the way to do this is to set the PLOTICUS_CONFIG environment variable in your 
#set FILE = "config.html"
#set TAG = "quisp config file"
#include link
like this: 
.nf
  putenv:  PLOTICUS_CONFIG=/home/john/plconfig
.fi
The ploticus config file and the quisp config file are two different things.

#include space2
.LP
You can see what libploticus version you have by printing the variable \fB@@PLVERSION\fR
after \fC#endgraphic\fR.


#include bottom
