.TH FAQ PL "Ploticus data display engine"

.ig >>
<center>
<b>Ploticus data display engine</b> <small><a href="Copyright.html">Copyright Steve Grubb</a><br></small><br>
<a href="../doc/Welcome.html"><img src="../gallery/btn/welcome.gif"></a>
<a href="../gallery/index.html"><img src="../gallery/btn/gallery.gif"></a>
<a href="../doc/Contents.html"><img src="../gallery/btn/handbook.gif"></a>
<br><h1>Frequently Asked Questions</h1>
</center>
.>>
 
.ig >>
<center>
<img src="../gallery/all.gif">
</center>
.>>

.SH NAME
Faq

.SH DESCRIPTION
Frequently asked questions about ploticus.


.SH GENERAL

.LP
\fBWhere can I get \fBploticus\fR?
.IP
\fBwww.sgpr.net\fR

.LP
\fBWhat computing environments are supported?\fR
.IP
Definitely: Solaris 2, Linux, AIX, FreeBSD, Irix.
Probably: Other modern Unix platforms.
Not for a while yet: Win32.

.LP
\fBIs ploticus Y2K compliant?\fR
.IP
Ploticus has been tested on a year=2000 machine and there
were no problems noted.  Many of the gallery examples use
2000's dates in the plot data.
Of course, as always, correctness of individual results is 
the user's responsibility.

.LP
\fBWhat is the easiest way to get started?\fR
.IP
.ig >>
<a href="../doc/Download.html">
.>>
Download 
.ig >>
</a>
.>>
the software.  If binaries are available for your
system, get them, then you don't need to compile the code.
Then use your web browser to look in the 
.ig >>
<a href="../thumbnails/index.html">
.>>
thumbnails
.ig >>
</a>
.>>

collection or 
.ig >>
<a href="../gallery/index.html">
.>>
Gallery
.ig >>
</a>
.>>
and find a plot that is close to what you
are trying to do.  Suppose it is 
.ig >>
<a href="../gallery/bars5.htm">
.>>
bars5.htm
.ig >>
</a>
.>>
When you have \fBbars5.htm\fR on your screen,
select your browser's \fBFile\fR / \fBSave As\fR menu selection,
and save the script file locally.  Then generate a plot
locally by typing: \fCpl bars5.htm\fR (to generate EPS use
\fCpl -eps bars5.htm\fR; to generate PNG use \fCpl -png bars5.htm\fR).
.IP
Then begin modifying bars5.htm with your favorite text editor.
The online 
.ig >>
<a href="../doc/Contents.html">
.>>
handbook
.ig >>
</a>
.>>
is a good resource for 
understanding the available procs, attributes and options, and 
what they do.


.LP
\fBIf I am creating a plot from scratch, what is the bare minimum of code I need?\fR
.IP
If starting from scratch, just remember that in order to
do a plot you need data (#proc getdata) a plotting area
(#proc areadef) with the X and Y ranges defined, and a
plotting proc such as #proc bars.  The plotting proc usually
requires that a data field be given.  Other parameters will
use defaults.


.LP
\fBWhy would I use ploticus rather than a MainStream
desktop spreadsheet / charting package / slides package 
to create graphs?\fR
.IP
Perhaps you are looking for an easy way to produce charts in an
automated, unattended way for a web site.  Or perhaps you are
looking for a stylistic edge for your data displays.  Or perhaps
\fBploticus\fR can do something that your current tool can't.
.IP
Of course, you can use both (e.g.
generate data displays using \fBploticus\fR then import PNG into PowerPoint,
Word, etc.)

.LP
\fBHow does ploticus compare with other freeware plotting/charting packages?\fR
.IP
Here is a list of some
.ig >>
<a href="../doc/Faq.other.html">
.>>
other plotting packages 
.ig >>
</a>
.>>
(thanks to Arthur Ferruzzi).


.LP
\fBAre there any licensing restraints related to GIF generation
with ploticus ?\fR
.IP
Because of the confusion surrounding the licensing mess, 
PNG is recommended rather than GIF (
.ig >>
<a href="../doc/web.html">more info</a>
.>>
), and GIF support may be dropped at some future point in time.
.IP
However, please note the following:
Ploticus does not read GIF files.
Ploticus writes run-length-encoded (RLE) GIF files.
Our understanding is that these RLE GIF files do not
use patented LZW compression (
.ig >>
<a href="../doc/gifpatent.html">more info</a>
.>>
).  

.LP
\fBDo IPL files work with ploticus?\fR
.IP
No.  Although the underlying structure and methodology are
similar, the IPL and Ploticus syntaxes are incompatible.
Background: \fBploticus\fR is a complete re-write of a software 
package called IPL that was distributed as freeware on the 
comp.sources.unix newsgroup
in 1989.  The re-write took place during 1998 and 1999 and
included the addition of many new capabilities and features.

.LP
\fBWhat does ploticus include?\fR
.IP
Two programs, \fBpl\fR and \fBpltab\fR.
If you download the binaries, there is no 'install' 
procedure; just move the executables
(pl, pltab, plpng, and pltabpng)
to an accessible bin and you're all set.

.LP
\fBWhat does the pl program do?\fR
.IP
\fBpl\fR generates plots and graphs, as specified in a 
.ig >>
<a href="scripts.html">
.>>
script
.ig >>
</a>
.>>
 .  
Most of the gallery examples were generated using \fBpl\fR.
It generates data displays using a page layout model, which
means that you need to specify exactly
where on the "page" each plot will be placed.
To use it, you would type a command such as this:
.br
\fBpl -gif lineplot1.htm\fR

.LP
\fBWhat does the pltab program do?\fR
.IP
Pltab is an innovative utility that takes ordinary ascii tables
and lists such as program output and creates presentable tables 
by setting them in a nice font, and often adding embellishments
such as rulings, shading, font changes, and embedded plots and graphs.
Pltab is a productive way to get plain program output (tables and lists)
into presentable form; no formatting codes or massaging of output
is required.
Pltab automatically overflows onto multiple pages and thus is useful
in creating multi-page graphical case displays such as
.ig >>
<a href="../tabgallery/caselist.html">
.>>
this
.ig >>
</a>
.>>
 .  To use \fBpltab\fR you would type a command such as this:
.br
\fBpltab table.out | lp\fR

.LP
\fBCan I invoke ploticus from C/C++/Perl/etc?\fR
.IP
Currently the best way is to invoke pl or pltab using
\fCsystem()\fR.

.LP
\fBI have a program that generates a stream of
X Y coordinates to create a special display.  How can I
display my results via Ploticus?\fR
.IP
\fBProc Drawcommands\fR may be used, assuming you can adjust
or post-process your program's output to conform to the Drawcommands 
command set.

.LP
\fBDo I have to learn the script language?\fR
.IP
Yes, but it is a simple goal-driven specifications language
rather than a purely procedural one.  As with many 
tools of this type, the best way to operate may be to
copy an existing script and modify it to suit.
The web-based handbook may be navigated quickly to find 
the names and uses of the various attributes.


.LP
\fBWhat graphics file formats can be created?\fR
.IP
You can create PNG or GIF images (typically used in web pages), 
paginated PostScript files that can be printed,
and EPS files (for printing or import into other document).
You can also use it interactively on an X11 display.


.LP
\fBWhat plot data formats are accepted?\fR
.IP
Ordinary ascii files, where fields are either
white space delimited, tab delimited or comma delimited.  
(The latter is sometimes called spreadsheet format, or .csv.)  
See
.ig >>
<a href="dataformat.html">
.>>
data formats
.ig >>
</a>
.>>
 .
.IP
Most plotting operations are done on data fields.
For example, you might do a bargraph on the values in field 3 of the data set.
If your data are not organized that way, you can get data into a usable form using
\fBproc transform\fR after the data are read.


.LP
\fBWhy isn't it interactive?\fR
.IP
While interactive WYSIWYG applications are appropriate for
many typical office graphing needs,
the process of producing more involved and complex data displays
is generally procedural and not so well suited to an interactive
mode of use.
.br
Also, \fBploticus\fR is intended for
automated generation of plots, invocation under external program control,
and repetitive use against changing data sets.


.LP
\fBAre any statistical capabilities included?\fR
.IP
There is a built-in facility (proc tabulate) for computing frequency
distributions.   Medians, quartiles, standard errors, and curve fitting
are also built-in.


.LP
\fBWhat about function plotting, formulas, and scientific notations?\fR
.IP
Ploticus is not a function or mathematical plotting package, nor would it
be a good choice for applications where mathematical formulas or scientific 
notations are to be rendered as an integral part of the data display.


.LP
\fBWhy are there no 3-D effects?\fR
.IP
Ploticus was not intended as a "marketing" graphics package.
Its goal is to display data crisply without extra decoration
and distracting "dingbats" that cloud the picture.
Thus there is currently little support for 3-D effects, 
gradient backgrounds, and so on.  


.LP
\fBHow can I render a proper less-than-or-equal-to symbol
(or other special symbol)?\fR
.IP
There is a mechanism to embed special characters
such as symbols into text.  This is available only
when working with PostScript.  See
.ig >>
<a href="../doc/specialchars.html">
.>>
special characters
.ig >>
</a>
.>>

.LP
\fBAre any character sets other than Latin1 available?\fR
.IP
Alternate postscript fonts may be specified on the command line,
or as an option in the ploticus config file, or in proc page.
As for PNG, GIF, and X11, there is currently no support for
other character sets.  


.LP
\fBWhat about large data sets?\fR
.IP
The capacities are fairly large (see
.ig >>
<a href="limits.html">
.>>
program limits
.ig >>
</a>
.>>
).  If your data set is too large, you may be able to use the \fCselect\fR or
\fCfilter\fR attributes of \fBproc getdata\fR to pair down the size.
\fCselect\fR will select only certain records; \fCfilter\fR may be used to
keep only certain fields.


.LP
\fBCan I import the graphs into PowerPoint?\fR
.IP
Yes.  
PNG and GIF files may be inserted as pictures with PowerPoint.
EPS files may be used with PowerPoint if the result will be
rendered on a PostScript film imager.


.LP
\fBHow can I view PNG or GIF files that I generate?\fR
.IP
You can view them with a locally-running web browser if you
use a URL beginning with \fCfile:///\fR, for example, 
\fCfile:///export/home/steve/plot.gif\fR (note that there are
three slashes, two for the URL syntax and one representing the
root of the file system).  You can also
use an image viewing utility such as the publicly available 
\fBxv\fR package to view images locally.
You can have ploticus invoke xv automatically to display
your results using \fC-viewer xv\fR on the command line.
.IP
Note that old versions of browsers and image viewing
tools may not support PNG.
.ig >>
<a href="http://www.cdrom.com/pub/png/pngapvw.html">Here's a list of PNG viewers</a>
.>>


.LP
\fBHow can I preview PostScript files that I generate?\fR
.IP
Use a PostScript previewing tool such as the publicly
available \fBghostview\fR package.
You can have ploticus invoke gv automatically to display
your results using \fC-viewer gv\fR on the command line.


.LP
\fBHow can I enlarge or reduce my results?\fR
.IP
Use the \fB-scale\fR command line option.

.LP
\fBHow can I make thumbnails?\fR
.IP
Just use a small scale factor, such as 0.3 or 0.2.
Very small text is rendered as lines automatically.

.LP
\fBHow can I crop my results?\fR
.IP
Use the \fB-crop\fR or \fBtightcrop\fR command line option.


.LP
\fBI took a look at your package, and I liked it.
However, the license is too strict for me, especially the following clause:
``Permission is granted to MODIFY the SOURCE CODE, however,
modified code may not be distributed to others*.''
In my opinion, this leaves open the possibility that, sooner or later,
you decide to make the code proprietary, after which all contributors lose
their efforts. Therefore, I will not use ploticus, and certainly not
contribute to it. But I do respect your standpoint.\fR
.IP
The clause you referred to exists to promote centralized version control,
to avoid "versions chaos" which is an oft-given criticism of free 
software.
.br 
If someone sends in a contribution that merits inclusion, I 
incorporate it in the next released version of the software.  Once a
version is released it may be freely distributed by anyone.  
In practice, new versions are released as frequent as changes
(contributed or done by me) warrant, which so far has been pretty
frequent :)
.br 
Therefore it is an incremental process and I don't agree that
all contributors would risk the loss of their efforts.
.br 
Unless the contributor indicates otherwise, the ownership of any
contributed code remains with the contributor.  If the package became
proprietary (which is extremely unlikely) I would be in the wrong if I
sold code owned by others without getting their consent and/or arranging
with them to participate financially.

.LP
\fBWhy is garbage being displayed at the end of my title?\fR
.IP
Attributes that are multi-line need to be terminated with a blank
line.  Perhaps the blank line was left out.

.LP
\fBI have changed an attribute value but nothing happens.\fR
.IP
If the attribute in question follows a multi-line attribute,
you may have forgotten to terminate the multi-line attribute
with a blank line.

.LP
\fBWhat are #clone and #saveas and how do they work?\fR
.IP
\fB#clone\fR and \fB#saveas\fR are used
when doing several similar plots, such as a set of four
bar graphs that have the same style.  \fB#saveas\fR saves
the attribute settings for one proc invocation.  \fB#clone\fR
uses a set of attribute settings that was saved earlier.
An example is
.ig >>
<a href="../gallery/volunteers.htm">
.>>
volunteers
.ig >>
</a>
.>>
See also the
.ig >>
<a href="../doc/scripts.html">
.>>
script syntax description
.ig >>
</a>
.>>
 .

.LP
\fBI have a graph where I set up the plotting area with procs 
areadef, yaxis, and two separate invocations of proc xaxis.  I
want to replicate this plotting area several times.  How do
I clone the plotting area?\fR
.IP
You need to use #saveas within every proc that is involved (with
different instance names), and then use #clone all of the procs.
There is no way to clone a set of procs together in one operation.

.LP
\fBI have large files containing dates and times of events.
I would like to plot them as histograms across time.
Some events happen concurrently (at the same time).
Thus I need to run a frequency distribution on the date and time,
however, proc tabulate has an upper limit of 200 unique instances.
Is there a way to do this?\fR
.IP
Yes, use \fBproc transform\fR with the \fBcount\fR action (introduced
in version 1.3).
Your data will have to be sorted (or at least grouped) so that
all like datetimes are together.  A gallery example where this 
is done is
.ig >>
<a href="../gallery/hitcount.htm">
.>>
hitcount
.ig >>
</a>
.>>

.LP
\fBIs there any way to make an axis progress from a large value to a small value?\fR
.IP
Yes, although it is not entirely straighforward.
See gallery example
.ig >>
<a href="../gallery/hbars4.htm">
.>>
hbars4
.ig >>
</a>
.>>
Ploticus can only do axes from low to high.  In order to go high to low,
you must reverse the sign of your data values (proc getdata's filter attribute
might be used to do this), and define your plotting range accordingly.
Then you can use proc axis's reversesign option (introduced in version 1.3) 
to present the axis stubs.

.LP
\fBIs there a way to do a broken Y axis?\fR
.IP
Yes, although broken axes cannot be done in an automated way.
See gallery example
.ig >>
<a href="../gallery/brokenaxis.htm">
.>>
brokenaxis
.ig >>
</a>
.>>
and the man page for
.ig >>
<a href="../doc/breakaxis.html">
.>>
proc breakaxis
.ig >>
</a>
.>>

.LP
\fBI am producing bar graphs in postscript.  
There are seven different types of bars, using seven shades of gray.
It is hard to distinguish between
some of the grays, especially after photocopying.\fR
.IP
Beginning in Version 1.3, hatch patterns were introduced as a color option,
which may be useful in getting more distinguishable bar shades.

.LP
\fBWhen I print on an Apple Laserwriter the grays look different than
on an HP (w/ postscript cartridge).\fR
.IP
The halftoning process used to render grays on PostScript printers has
some hardware dependencies, hence the differences in appearance.

.LP
\fBCan I use hatch patterns in pie graphs?\fR
.IP
No, they may only be used to fill rectangular areas such as bars.

.LP
\fIMore to come....\fR
