#set TITLE = "Ploticus scripts"
#include top

.SH DESCRIPTION
.LP
Ploticus is controlled by scripts that a 
user creates in a text editor.
The scripts can also be created by other programs.

#include space

.SH EXAMPLE
Here is an example of a ploticus script:
.nf
.ft C
.ig >>
<br><img src="../gallery/sa1.gif"><br>
.>>
\0#proc areadef
\0  rectangle: 1 1 4 2
\0  xrange: 0 5
\0  yrange: 0 100
\0
\0#proc xaxis:
\0  stubs: text
\0	Africa
\0	Americas
\0	Asia
\0	Europe,\\nAustralia,\\n\& Pacific
\0
\0#proc yaxis
\0  label: Growth Rate
\0  stubs: inc 20
\0  minortics: yes
\0  minorticinc: 5
\0
\0#proc getdata
\0  data: 76 
\0	54 
\0	60 
\0	59
\0
\0#proc bars
\0  lenfield: 1
\0  color: teal
\0  barwidth: 0.2
\0
.ft R
.fi

.LP
As you can see, this is not low-level 3GL-style code.  It is a sort of
hybrid; plotting actions (#procs) are specified in procedural order,
but within each #proc the language is goal-driven (4GL).  Thus, traditional
procedural programming skills are not required.
.LP
The above Ploticus script invokes a number of procedures (procs).
First,
\fBproc areadef\fR to set up a plotting area, then
\fBproc xaxis\fR and \fByaxis\fR to render the axes.
Then \fBproc getdata\fR is invoked to define some data, 
and then finally \fBproc bars\fR is invoked to produce a bar graph.
.LP
For each proc, the user may specify a various attributes or options.
Attributes that are not specified use a default when possible.
In the above example, the user has invoked \fCproc areadef\fR
and specified values for these attributes: \fCrectangle\fR, \fCxrange\fR,
and \fCyrange\fR.  
All of the procs, as well as the names, types, and acceptable 
values for all attributes, are described in the 
#set FILE = "../doc/Contents.html"
#set TAG = "ploticus handbook."
#include link

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

.SH PROCEDURES (PROCS) AND ATTRIBUTES
.LP
\fBProcedures (procs)\fR are always invoked using this construct: \fC#proc \fIprocname\fR.
The word \fC#proc\fR indicates the start of a procedure specification block;
the other word is the name of a procedure (case insensitive).
.LP
\fBAttributes\fR within a procedure may be specified in any order.  
A colon (\fB:\fR) may be used after an attribute
name or a procedure name (however it is not required).  
All proc names and attribute names are case-insensitive.  
Attributes that are multiline text type
are terminated by a blank line.
.LP
The following script directives are used by ploticus in executing procedures:


.SH #proc
.IP
This directive signals the beginning of a 
#set FILE = "Contents.html#scripts"
#set TAG = "ploticus procedure"
#include link
(proc).  
.br
Example: \fC#proc bars\fR

.SH #proc endproc
.IP
This signals the end of a ploticus procedure (proc).
Only required in 
#set FILE = "endproc.html"
#set TAG = "certain cases."
#include link
.br
Example: \fC#proc endproc\fR


.SH #procdef
.IP
This directive is used similarly to #proc, but it does not
execute the procedure; it only defines it so that it may
be \fB#clone\fRd later.
The procedure should contain a \fC#saveas\fR.
.br
Example: \fC#procdef bars\fR

.SH #saveas
.IP
Makes the current proc available to be \fBclone\fRd by procs 
encountered later in the script, and assigns it an identifier
(B1 in the example below).
A gallery example that uses \fBsaveas\fR and \fBclone\fR is
#set FILE = "../gallery/rangebar1.htm"
#set TAG = rangebar1
#include link
\0.  May be used anywhere within the proc.
.br
Example: \fC#saveas B1\fR

.SH #clone
.IP
\fBclone\fR is used like an attribute.
Inherits all attribute values from a previously \fBsave\fRd proc. 
May be used anywhere within the proc.
Attributes may be overridden locally as desired.
.br
Example: \fC#clone B1\fR

.LP
Other general purpose directives are described below.

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

.SH SYNTAX AND VARIABLES

#set TDH = 1
#set PL = 1
#include /home/scg/cgipal/man/scr/cgipal

#include bottom
