PCU - Pie Chart Utility -- Ver. 6b

			D I S C L A I M E R


	This software is subject to change  without 
	notice  and should not be construed as a
	commitment by Digital Equipment Corporation. 

	DIGITAL assumes no responsibility for the use
	or  reliability of this software.

	This software is not supported by DIGITAL.


This is a description of a program called "PCU", for "Pie Chart Utility".

As its name suggests, it produces pie charts.

It is essentially a test vehicle for some algorithms I worked concerning
1) shading of pie slices, and 2) separating colored slices to avoid color
bleed.  But it can produce usable pie charts of up to 30 slices.

To run it:
	$ run gglib:pcu

The first prompt is "do you want help?".  Typing "Y"es here will give
you this help message.

The next question is "color?".  A "Y"es here will generate a multi-color pie;
a "N"o (or return) will generate a black-and-white pie with character shading
used to distinguish the slices.

PCU next asks you if you want the pie scaled for proper aspect ratio on
the LA34 hardcopy device with the "scaled for hardcopy?" prompt.
A "Y"es here will scale the pie so that it will appear circular on the
LA34 output.  A side effect of that will be to make the screen display
appear slightly oval.  Specify "Y"es if you want the hardcopy to look its
best -- specify "N"o or just carriage return if you want the display
to look its best on the screen.

If you specify hardcopy scaling, PCU now asks you if you want it to
automatically generate double-sized hardcopy output, on an attached LA34VA
printer, as soon as it has drawn your pie chart.  A "Y"es answer will
cause this to happen.  If you just want single-sized hardcopy, answer
"N"o (or just return) and type the SHIFT-PF1 "HARD COPY" key yourself
after the pie is drawn.

The next prompt asks you if you want PCU to generate test data.  This
is primarilly for the purpose of testing and/or debugging PCU itself.
If you want to chart your own data, answer "N"o, or just carriage return.

The next prompt asks you if you want data values to be added
to the pie slices as a form of annotation.  If you answer "Y"es,
the numbers corresponding to your input data for each slice will be used
as the labels for the slice, or will be added to the end of the labels
if you supply labels in your data file (see below).

The next prompt asks a similar question to find out if you want computed
percentages added to your pie slices as another form of annotation.
If you answer "Y"es, you will get these percentage numbers as labels for
each slice.  These will be added to the end of user-supplied labels,
if any.  You may request both data-value labels and percentage labels.

PCU will then prompt you for a file name of a DPP data file.  If you answer
with a file name, PCU will look for a DPP-format data file (default file
type: .DPP) and will then ask you if you want a "row" or "column"
plotted, and then asks for the name or number of the row or column.
If your data is not in a DPP-format file, just answer this question
with carriage return.

PCU also can read data in a much simpler file format, called PCU-format,
described below.  If you did not provide the name of a DPP-format file,
PCU will then prompt you for the name of the PCU-format file
(default file type: .PCU).

A PCU-format file must have one number, integer or "real", per line.
You may enter data from the terminal by entering TT: as the file name;
if you use TT:, end the sequence of numbers with a control-Z.

Each line of your PCU-format input file must have a number on it, but
that number may be optionally followed by one or more spaces followed
by a label to be used in annotating the corresponding pie slice.
The label must not have the double-quote (") character in it,
and should be no longer than 50 characters in length.  The diameter of
the pie is reduced, within limits, to accommodate long labels -- but if
the total label length is too great, part of the label may be lost
"off screen".  In that case you can abbreviate your labels.

You may specify a multi-line label by using the backslash character (\)
anywhere in your label, as many times as you like.  The label in the file
must still be entirely on one line, and still may be no longer than 50
characters, but when PCU uses the label, it will remove any backslashes and
start a new label line there.  If you want the PCU-generated labels to be
on a separate line from your label, put a backslash at the end of your label.
(PCU will try to make sure that labels for adjacent pie slices don't overlap,
but it won't try too hard!)

After either the DPP-format file or the PCU-format file is read in
(no more than 30 data records will be used), PCU
will ask you for a file name for a ReGIS (.pic) file.  If you just
type carriage return, the pie is not saved on a file.  If you type a valid
file name, PCU will create a ".pic" file by that name as it draws
on the screen.

After drawing the pie chart, the package will pause for a
carriage return before starting over again with the "do you want help?"
prompt.

If you give PCU the name of a ".pic" file, the resulting file can be
shown by the Slide Projection System (SPS) or edited by the
Graphics Editor (GE).  It is easy to add titles to pies using GE.

Each slice of the pie is grouped for individual
access by either SPS or GE.  The group name for each slice is an upper
case letter, starting with "A" and assigned consecutively from the alphabet.

A control-Z typed to any of the prompts will terminate the execution
of this program cleanly.

Have fun!

I am open to suggestions for improvement, but remember:
		PCU IS NOT A DIGITAL PRODUCT!


NOTE: color pies are exploded enough to avoid the "color bleed" problem,
whenever possible.  Depending upon the order of the pie slices,
this effect can be quite severe.  One feature of PCU is the automatic
detection of these severe cases.  When such a case is detected, PCU will
ask you if the order of the slices can be changed.  If you do not type "n"
(or "no"), PCU will then sort the data in a way that usually produces
a much better pie chart.  If you don't like the way PCU sorts the data,
you can always change the order of the data in your file until you get
the desired effect.
