#!/bin/sh
#! -*-perl-*-
eval 'exec perl -x -wS $0 ${1+"$@"}'
  if 0;

=begin copyright

Tridens density plot program

Copyright 2003, 2011 John Lapeyre, All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

=end copyright

=cut

package Tridens;

our $VERSION = '0.19';

# use POSIX module for log10 and floor functions
use POSIX;
use Pod::Simple::Text;    # for processing the docs
use Term::ReadLine;
use Text::ParseWords;
use Text::Wrap;
use Data::Dumper;
use Carp;

sub deb;

#  use this to avoid failure of the entire program if a function is missing
#use autouse MODULENAME;

# Tue Oct 20 17:45:24 CEST 2009
#  Fixed pod interpreter complaints
#  Added -square -tri -sidelength options.
#  changed documentation
#  changed a "die" to just an exit at line 641
#  Fixed several other bugs. Eg, in is_power_2
#  Fixed pdf output
#  Added a bunch of things that would take too much work to list
#  and is not worth the trouble
# Nov 15 2009, version 0.15. More refined calculation of height for superscript.
# 0.16 Feb 25 2010
#  * set ColorMapLo default to 0.2.
#  * add viewerscale feature
# 0.17
#  * added -nosameunits feature
#  * fixed some small bugs
#  * improved docs
#  * added tab completion
#  * fixed portrait to landscape and back bug
#  * set some fonts
#  * strip some trailing zeros in postscript
#  * changed dot to x in sci notation
#  * correctly detect if gv processs is killed
# TODO
# *  add ability to write tick labels with numbers multiplied by powers
# of ten, so that the power of ten can be put into the label
# * also ability to to sci notation on the tick labels.
# * lots of code cleaning: eg uses routines to check values (not 'xpdf' everywhere, etc.)
# * saving and restoring not complete
# * number of labels on key should be selected, not the skip value
# * completion with show, set, etc. needs improvment (remove useless completions
#  etc.
# * optionally doing the /pd postscript routine in perl might make rendering to pdf faster
# * send commands to xpdf, such as 'raise' upon plotting

=begin comment

   tridens -- Programmers' notes.
   An identifier begins with a capital letter if and only if it is 
   global (declared with 'our').
   Sections of this file and related groups of routines are separated
   by a bar like this '#==== ...'. 
   A block that serves only to implement scoping of variables to be shared
   by some routines is enclosed with bars like this '#*=*=*=* ...' .


This file is organized (!) as follows from top to bottom: 

* Pod documentation. This is the source for man page, html, etc. as is usual with
  pod. It also has to local directives that are used to extract short interactive
  help messages. So the format (not documented) should be followed.

* The interactive mode code. It is in the Shell package.

* Hmm the rest has been put into comment boxes marked with the string 'SECTION'.

=end comment

=cut 

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#  User documentation that is extracted from this file and formatted in various ways. #
#                                                                                     #
#                                                                                     #
#=====================================================================================#

=head1  NAME

B<tridens> --  create density plots on a triangular or square lattice in postscript
or pdf format.

=head1  SYNOPSIS

usage: tridens [options] [F<infilename1>, F<infilename2> ...]

=head1 DESCRIPTION

tridens reads data from the input files specified on command
line and, for each one, writes color or grayscale density
plots.  The input data is on a triangular lattice (or,
optionally, a square lattice.) For the triangular(square)
lattice, each coordinate pair in the input file is covered
with a hexagon(square).  The output file format is
PostScript or PDF. tridens also operates in an interactive mode.

=head2 Quick start

C<tridens data.dat> -- write a density plot data.dat.pdf of a regular square
(or rectangular) array of data points from a file with lines of the form
'x y val'.

C<tridens -i data.dat> -- write a density plot and display the result in the
pdf viewer and enter interactive mode.

C<tridens -tri data.dat> -- write a density plot data.dat.pdf of data on a triangular
lattice from a file with lines of the form 'x y val', where at least one of the nearest
neighbors to the first point is present. (There can be 'holes' or missing points in the
remainder of the data set.)

=head2 Why another plotting program?

=over 1

=item 1   I could not find a program that can make a density plot of hexagonal tiles on
a triangular lattice.

=item 2 The method of producing plots is different from most
other methods. For instance, gnuplot's pm3d can be applied
in more cases, but produces an essentially different plot.

=item 3 To produce PostScript plots, tridens requires only a
standard perl installation, which is present on all Linux
and nearly all Unix machines.  (But you probably want to
generate eps or pdf, in which case ghostscript is required,
but this is also standard on Unix/Linux; see below.)  The
tridens program is a single file that needs no compilation
or installation and generates its own documentation and
parameter files. I wrote it after trying
downloading/compiling/getting licenses/libraries for a bunch
of programs that couldn't do a density plot on a triangular
lattice anyway. (This was in 2003, perhaps there are more programs
available now that are easier to install.) See
REQUIREMENTS AND DEPENDENCIES below for other features and requirements.


=back

=head2 Plotting options

Most plotting options, (axes, labels, etc.) are controlled
through command line options or interactively, more are available by setting
parameters in a parameter file. Command line
options override settings in the parameter file. If you need to set
more options than are available on the command line (or prefer to use
a configuration file) type

C<tridens -paramfile>

to generate the file F<.tridens> with the default parameters
in the current directory.  Then edit this file to suit your
needs. It will be read each time tridens is run.  This
parameter file is moderately well commented.  Any parameters that
are deleted from or 'commented out' of F<.tridens> will be
determined by the built-in defaults.  If you copy F<.tridens>
to F<infilename.p> and edit the result, then, only when
processing data file F<infile>, the file F<infilename.p>
will be read after F<.tridens> and any parameters present
will override previously set values. There
is a copy of F<.tridens> inside the F<tridens> executable program,
which is a plain text file. If you edit these internal parameters,
then they become the default parameters.
In summary parameters are set in this order: 1) internal (default) parameters,
2) parameters in F<.tridens>, 3) parameters in F<infilename.p>, 4) parameters
given on the command line. 5) parameters set interactively.
In this list, settings with higher numbers override 
settings with lower numbers.

=head2 Interactive mode

Interactive mode is entered by either omitting a data filename on the command line
or giving the option B<-i>.
Here is an example:

 myshellprompt > tridens -i -o sq.pdf sq1.dat
 tridens> plot
 tridens> set -title 'This is the title'
 tridens> plot
 tridens> plot 'other.dat'

In the example, the plot is drawn twice, adding a title the second time. Then, data from
a second data file is plotted. If Term::Readline is installed on your system (It is available
as a package in all linux distributions.) the you can use command history and tab completion.
Try tab completion in various contexts. (In particular, this document may be out of date,
and tab completion can show available commands or arguments.)
The following lists commands recognized in the interactive mode.

=head3 Commands in interactive mode


=over 1

=item B<h> 

Print command line options

=item B<help> I<TOPIC>

Print brief help on a topic. Hit TAB twice to see list of topics (if perl-gnu readline is installed).
The content of brief help is taken from the man and html pages.

=item B<man>

View long documentation as unix man page.


=item B<html>

Print documentation to  tridens.html and try to open it in a browser (firefox by default)

=for trihelp commands start

=item B<plot> I<FILENAME>

write (or rewrites) the output plot file. If FILENAME is given as an argument (in single quotes) then
the data is read (or reread) from the file. If there is no argument, then the most recently read
data is used. If you have set the option B<-dis> then tridens will try to display the plot
immediately in a viewer (which can be configured to be xpdf or ghostview.)

=item B<replot>

Reread the data from the most recently read input data file
and replot the data. If an argument is given, data is
instead read from the file named in the argument. This is
equivalent to using 'read' and then 'plot'.

=item B<set> I<OPTION> I<VALUE> ...

Set the value of an option (or options). If the option is boolean then I<VALUE>
must be omitted.
In interactive mode, boolean options are set with B<set> and unset with B<unset>. 
When starting tridens from the command line
boolean options are unset by prefixing the option name with 'no'.
For example: C<set cmgray title 'title of plot'>, sets the title and sets grayscale
mode.
On the commadline C<-nokey> supresses drawing the color key, while in interactive mode
this is done with C<unset key>.  The leading '-' can
be omitted from the first option to be set. For example C<set xmin 0> to set the lower
limit of the x-axis to 0. You may also put an '=' between the option and the value.


=item B<unset>

see B<set>.

=item B<show> I<OPTION> ...

Display the value variables set by an option (or options)
You can omit the leading dash '-' on the option when using show.
For example if the color map is set to 'cmhue' rather than 'cmgray':

  tridens> show cmgray title
  ColorMap = hue
  Title = ''

=item B<fshow> I<PATTERN>

print all plot parameter values preceded by a list of
command line switches that can be used to set them. This list
of options is printed because more than one option
may set the same variable, eg, B<-axis> and B<-noaxis>. The
optional argument I<PATTERN> causes fshow to print only those
parameters matching the argument. (The pattern is typically
a string, but it can be a perl regular expression.)
Currently, they are shown in alphabetical order, which is
not so useful. For example 'fshow axis' prints all parameters or options
containing the string 'axis'.

=item B<viewer>

Launch a viewer that displays the plot.
Useful for instance to relaunch the viewer if it is killed or crashes.
(But this should happen automatically in most cases.)


=for trihelp commands stop

=item B<example> I<N>

Write example plot number I<N> and display it in the viewer.

=item B<demo>

Display demonstration plots in the viewer.

=for trihelp commands start

=item B<read> I<somefile.data>

Reads the data from the file, that can then be plotted with 'plot'. Use this to force rereading of data file.
You can also use "plot  'filename'", but it will not re-read the data.

=item B<save> I<configfile>

Save the current plotting options to the file I<configfile> or 'save.tridens' if I<configfile> is omitted.
There is no 'save' command for the plot itself, as it always written to a file.

=item B<load> I<configfile>

Load saved plotting options from the file I<configfile> or 'save.tridens' if I<configfile> is omitted.

=item B<listcolors>, B<listsymbols>, B<listfonts>, B<findcolors> 

=for trihelp commands stop

These are commands corresponding to
the commandline options of the same names described below.

=item B<exit>  

quit interactive mode and exit tridens

=back

All commands above may be abbreviated. Although not normally
useful, typing the name of a
'variable' prints its value, with the variable as it appears
in the configuration file F<.tridens> (described below)
except that it is prepended with I<Tridens::>, eg
I<$Tridens::Title>.  To change plot parameters you may use
B<set> as in the example above. Although usually not necessary,
you may also use the variables as they appear in the file F<.tridens>, again with
the prefix. For example $Tridens::Title = 'title of plot'.
Note that all variables begin with a dollar sign, as in the
perl language.

If possible a viewer is started to monitor
the output file and update upon replotting. The default viewer is xpdf
which is set in the configuration file F<.tridens> (see below).

With the addition of recognizing a few commands, the
interactive mode is executing your input as perl code. So
you can enter things like C<1+1> and C<sin($Pi/4)> .  ($Pi
and $E are defined.) The user can declare new variables
without the prefix for use only in the interactive
shell. For example:

 tridens> $x = 1
 1
 tridens> set -title 'Plot number $x'
 tridens> pl 'sq1.dat'

Note that the value of $x is interplotated into the title string. (In perl
single quotes do not cause interpolation, but here they do.)

If a line begins with '!' the remainder will be passed to the
shell. For example '!ls' will list the directory contents (in unix-like OS's).

The reason for the cumbersome prefix Tridens:: is to allow
access or modify all data and subroutines in tridens from
the interactive mode, while making it difficult for the
interactive user to accidentally change an important
subroutine or variable with harmful results.

=head3 Command line editing

The up-arrow and down-arrow recall the previous and next
command in the command history. Ctrl-p and Ctrl-n do the
same thing. Command line editing is in the 'emacs' style by
default. That is ctrl-a goes to the beginning of the
line. Ctrl-e to the end. ctrl-d deletes a character, etc. It
is probably possible to change this somehow. You can press the tab while
entering commands to display possible completions.
All these editing features are part of the
perl 'Readline' packages and may vary with or be missing
from your perl installation. Full support is offered by the
perl interface to gnu readine (Named something like
libterm-readline-gnu-perl) is available in linux
distributions.)

=head2 Data file format

An attempt is made to detect one of the supported formats automatically
(but this behavior can be disabled or overidden. See
B<-autodata> and  B<-grided>.)
In the standard format, the input data file must have lines of the form

 x y val

which causes a polygon with coloring representing val to be
drawn at the point x,y.  Numbers can be separated by
whitespace (spaces,tabs) or commas or anything not used to
denote numbers (ie, digits . + - e E). Leading whitespace is
ignored. Comment lines in the data file can start with the
characters $ % ; ! # .  If the option B<-grided> (with
details described below) is set (or autodata detection is
set)  then the data file must consist
of only the values, with the coordinates implied by the row and column of
the number. With the grided format an n by m plot will be produced from a data file with m lines
and n numbers in each line.

The program does not assume that the data is on a triangular
grid-- the coordinates x,y can be any numbers. But a hexagon
(or square) is drawn at the coordinates of each data point
in the input file, so that, if a data point exists for each
vertex of a triangular(square) lattice within a region, all
space on the plot is filled and no hexagons(squares)
overlap. You do not have to have a data point for each point
in the region plotted; there can be holes in the data.

The length of the sides of the polygons is computed from the distance from the first
data point to the point nearest to the first point in such a way that all the plot surface is covered
with no overlap. This can be turned off with option '-noautolength' or by giving the
option '-sidelength', in which case the length of the side must be set explicitly on
the command line or in interactive mode.

If the data is on a square lattice with different units on
the x- and y- axes (e.g. time and distance) use the
-nosameunits option below (this is the default). In this
case nearest points to the first point in both the x- and y-
directions are computed to determine the length of the sides
in physical units.

This is  tested under Linux. It probably will
not work on MS and Apple platforms without some work.

=head2 Output file format

The output file can be one of F<infilename.ps>,
F<infilename.eps>, or F<infilename.pdf>.  You need to have
ghostscript installed in order to write eps or pdf.  (All
Linux and most Unix installations should have
ghostscript. It is available for MS platforms. If you can
view a PostScript document under Linux/Unix/MS Windows you
almost certainly have ghostscript installed as the
backend. )  You may also use some external conversion
program to get pdf and eps from the ps generated by tridens.

=head2 Text in title and labels

Arguments that are text strings are enclosed in single or double quotes.
Superscripts and subscripts, fonts, colors, and fine control
of spacing are implemented using escape codes in the text
strings. Each code consists of a backslash '\' followed by
one or more characters (neither backslash nor space)
followed a space. For example the option: B<-xlabel> I<'\sym
x\^ 2'> prints a Greek letter xsi with a superscript "2" as
the x-axis label. The string I<'e\^ \h-2 -\sym x\rm \^2 2'>
prints I<e> with I<-xsi> as a superscript and I<2> as a
supersuperscript, with a negative horizontal half space
before the minus sign. This is roughly equivalent to the TeX
code I<e^{-\xi^2}>; here TeX is smart enough to
automatically position the elements, whereas with F<tridens>
fine spacing must be done manually.

The codes are as follows:

=over 1

=item '\rm '  '\sym '  '\bf '  '\it '  '\bi '

Select roman, symbol, boldface, italic, or boldface-italic
font. (The symbol font has Greek letters and other math symbols)
The specific fonts
corresponding to these codes can be changed in the
F<.tridens>. You can set the environment variable GS_FONTPATH of the shell in which
you run tridens to use fonts than that are not in the default path
of ghostscript. There is a $FontPath parameter in F<.tridens> that does
the same thing. If you produce pdf using B<-pdf> then the fonts will
be embedded by gs in the file containing the plot, making the plot portable.
(Currently this is not available for ps and eps. But producing pdf and
then using a program such as pdftops will produce an eps plot with high
quality embedded fonts.)

=item '\^ '  '\^2 '  '\_ '  '\- '

Switch to superscript, supersuperscript, subscript, or no super-/sub- script mode. The
code I<'\- '> is used to leave super and subscript modes. These are a bit crude in positioning,
but they can be adjusted, for instance with spacing codes given below.

=item '\h+ ' '\h+2 '  '\h- ' '\h-2 '  '\v+ ' '\v+2 '  '\v- ' '\v-2 '

These are horizontal space, horizontal half space, horizontal negative space, horizontal negative half
space and the corresponding vertical spaces. You can write '\h+n ' etc. for n=2,3,4,5, where the
spaces decrease in size by a factor of one half with each increment of n. For instance '\v-5 ' is a negative
one-sixteenth vertical space.

=item '\colorname '

This changes the text color. To see the list of color names, type C<tridens -listcolors n>,
or C<listcolors n> in interactive mode. If you omit the 'n',
then four columns are printed. If you include an integer argument 'n', then n columns
are printed. These colors are approximately the X11 colors, which can be found (with swatches)
many places on the web (eg Wikipedia). Any spaces in color names are converted to underscores
in tridens. In addition to those listed, there are gray1, through gray99, which goes from
almost black to almost white. For example: I<-title '\red A \blue B \green C'>.

=item '\symbolname'

This prints a symbol from the Adobe symbol font by name, without explicitly changing the font. That is,
you can insert theses symbol names in normal text. To see a list of symbol names use the option
B<-listsymbols>. For example: I<'\sigma \^ 2'>. There are also some aliases from TeX/LaTeX to
the Adobe symbol names

=item  '\\'  '\nnn'

A double backslash is used to represent a literal backslash. A backslash followed by three digits I<nnn>
prints the character corresponding to the octal character code I<nnn>. Refer to
PostScript documentation for a list of these character codes. Note these
two codes do not include a final space ' '.

=back

The font and super/sub script changes remain in effect until they are
changed by another font or super/sub script code.

=head1 EXAMPLES

C<tridens  mysdata>

Write a density plot to F<mysdata.pdf>
after reading data on a square grid from file F<mysdata>. Size of squares covering the
plot are computed automatically: The distance to the closest data point from the
first data point is used for the length of a side.

C<tridens -eps -tri mytdata>

Write density plot on triangular grid (covered with hexagons) to F<mytdata.eps> after reading data 
from file F<mytdata>. Size of hexagons computed automatically.


Further examples of plots illustrating the use of various arguments can be generated using B<-ex> I<n>. For instance
I<tridens -ex 2>  creates the second example plot. You can see the example plot immediately if you
use I<tridens -display -ex 2>.

Using I<tridens -demo>, produces all the examples sequentially and launhces the viewer to view them,
prompting the user after each plot. I<tridens -demo N> instead pauses for N seconds between example
plots.

=head1 HINTS

It is usually necessary to enclose strings such as the title
string in single quotes rather than double quotes to prevent
perl or the shell from trying to interpret the escaped
tridens codes.

If labels or other elements of the plot are clipped by the edge of the drawing surface,
try reducing the size of the plot with B<-plotwidth>

=head1 OPTIONS

Important! Setting an option to false is done by prefixing the option
with 'no' when passing command line options to tridens from a shell
(ie B<-nokey>). In interactive mode, the option is set to false with
'unset' (ie B<unset key>).

They can also be used in interactive
mode using the 'set' command. In this case the leading '-' may
be omitted. Any options below that take an
argument can have either spaces between the option name and
the argument or a '=' between the option name and the
argument. You are only required to give enough of the
characters in an option to distinguish it from other
options. For example B<-sa> for B<-saturation>.  All gray
values use: 0=black, 1=white.


B<-i> Run in interactive mode

=for trihelp options start

B<-batch> I<FILE>
Process commands in file I<FILE> as if in interactive mode.
If the last statement in I<FILE> is not 'exit', then interactive mode continues after
I<FILE> is processed.

=head2    Documentation:

B<-h> 
print short(ish) help message.

B<-man> 
view long documentation as unix man page. Broken on
some platforms (eg, BSD), but -mandoc might still work.

B<-mandoc> 
print documentation as man page to file tridens.1

B<-htmldoc> 
print documentation to  tridens.html

B<-html> 
print documentation to  tridens.html and try to open it in a browser (firefox by default)

B<-textdoc> 
print documentation as plain text to standard output.

B<-pdfdoc> 
print documentation as a pdf file via latex. You must have latex and
pdflatex installed.

B<-paramfile> 
write parameter startup file template to the file .tridens
This template can be edited. If present, it will be read before
processing command line arguments.

=head2     Plot Contents:

If  B<-square>, B<-tri>, or B<-circle> are set interactively, then 'replot' rather
than 'plot' must be used.

B<-square>
(default) Cause squares to be drawn at data coordinates, not hexagons. By default
this uses the B<-nosameunits> option. But for a data file with a nearest neighbor of the
first point absent in one of the x or y directions, setting B<-sameunits> will be sucessful
as long as a nearest  neighbor is present in one direction.

B<-tri>
assume a triangular lattice, I<ie> hexagons are drawn. This option automatically
sets the B<-sameunits> option.

B<-circle>
draw circles on data coordinates.  This option automatically
sets the B<-sameunits> option.

B<-sidelength> I<SIDELENGTH> 
length of sides of polygons covering the density plot. By
default, this is computed automatically and this option need not be given.

B<-xsidelength> I<SIDELENGTH> 
length of sides on x-axis. Use only if -nosameunits
and -noautolength are both set.


B<-ysidelength> I<SIDELENGTH> 
length of sides on y-axis. Use only if -nosameunits
and -noautolength are both set.

B<-autolength>  B<-noautolength>  
(default) compute length of side of polygon from smallest distance
between data points.

B<-sameunits>  B<-nosameunits>
If set, assume x and y coordinates are in the same units (triangular lattice tiled
with hexagons makes more sense this way.) Finding the separation between data points on the x-y
plane is computed using Euclidean distance. Use 'replot' after setting this interactively.
If unset,(default) assume x and y coordinates have different units. That is, one might be time and another
length. When finding the separation between data points to compute the size of the tiling square,
x-axis and y-axis are treated separately. This does not work with triangular lattice.
Use 'replot' after setting this interactively.

B<-aspectratio> I<VALUE>
Sets the aspect ratio of the plot area. A value of 1 is square. A value greater (less) than 1 makes
a wide (tall) plot.

B<-numberpoly>  B<-nonumberpoly>  
write numeric value in each hexagon.

B<-polyborder> B<-nopolyborder>
draw a black border around each polygon or not

B<-lattice> B<-nolattice> 
draw the underlying triangular lattice. If used with square lattice
the results will be nonsensical.

B<-latticegray>  I<GRAYVALUE> 
shade for the lattice lines if drawn

B<-xmin>,  B<-xmax,-ymin,-ymax>  I<FLOAT>  
set boundaries of plot area, overriding automatic boundaries.
If I<FLOAT> is ommitted, then the corresponding boundary is once again set automatically.
If these are set interactivly, you must reread the file with the "replot" command in order for
them to take effect. (Or use 'read' and then 'plot'.)

=head2      Density to Color map:

B<-cmgray>  
Make a grayscale density plot. That is the value of the data is represented by shades of gray.

With the following three color maps, the value of the data is represented
by the named color parameter (hue,saturation, or brightness). In each case
the remaining two color parameters may be set manually and will change the
appearance of the plot.

B<-cmhue> 
(default)  set color map to 'hue' for density plot. This is a 'false color'
plot. If B<-cmhue> is set, then  B<-saturation> and B<-brightness> set constant
saturation and brightness

B<-cmbrightness>  I<HUE>
(HUE is from 0 to 1)
set color map to 'brightness' for density plot. An optional argument
sets the hue. The hue can also be set with B<-hue>. The saturation
can be set independently to a constant with B<-brightness>  I<SATURATION>.

B<-cmsaturation>   I<HUE>
(HUE is from 0 to 1)
set color map to 'saturation' for density plot. An optional argument
sets the hue.  The brightness
can be set independently to a constant with B<-brightness>  I<BRIGHTNESS>.

B<-cmsatbright>     I<hue>
(hue is from 0 to 1) set color map to 'satbright' for density plot. Both the saturation
and brightness are set by the data value.
An optional argument sets the hue.

The following three parameters set to a constant any hsb values that are I<not> mapped
from the data via  the color map chosen above. That is, B<-hue>, has no effect if B<-cmhue> is chosen, etc.

B<-hue>  I<SATURATION> 
(default 1) from 0 to 1

B<-saturation>  I<SATURATION> 
(default 1) from 0 to 1

B<-brightness>  I<BRIGHTNESS> 
(default 1) from 0 to 1

The raw data is normalized so that it can be mapped to color hues
in the range 0 to 1. To use only a subset of these colors, the upper
and lower limits of this normalization can be changed. If grayscale plot is chosen via B<-cmgray>,
then these cmlo and cmhi are interpreted instead as grayscale values. If B<-cmsaturation> is
chosen, they are interpreted as saturation values, and likewise with B<-cmbrightness>.

B<-cmlo>  I<HUE> 
(HUE is from 0 to 1 )(default 0) Lowest value of range of hue in mapping data to hue

B<-cmhi>  I<HUE>  
(HUE is from 0 to 1) (default 1) Upper limit of range of hue.
For example, if these values for range of color parameter are reversed, the color mapping is reversed.

B<-uselinear> 
(default) Do not raise the data values to a power prior to plotting.

B<-usepower>   
raise data values to a power before mapping to colors

B<-power> I<POWER> 
(default value .5) power to use with -usepower

=head2     Labels, Ticks, Axes, Border, Key etc:

B<-title> I<'The Title'>
plot title

B<-titleyoffset> I<FRAC> 
Fractional part of frame height by which title is separtated from
frame. Ie, use this to move the title up and down.

B<-titlexoffset> I<FRAC> 
Fractional part of plot width by which title is separtated from
frame. Ie, use this to move the title left and right.

B<-xlabel> I<'the x label'>
set the string used as the x-axis label.

B<-ylabel> I<'the y label'>
set the string used as the y-axis label.

B<-rotylabel>, B<-norotylabel>
(default) Rotate (or not) the y-axis label by 90 degrees

B<-xlabelxoffset> I<FRAC>
(default 0) Shift the xlabel left or right by I<FRAC> times
the plot width.

B<-xlabelyoffset> I<FRAC>
(default 0.07) Draw the xlabel at a distance  I<FRAC> times
the plot height below the plot frame.

B<-ylabelxoffset> I<FRAC>
(default 0.07) Draw the ylabel at a distance  I<FRAC> times
the plot height to the left of the plot frame.

B<-ylabelyoffset> I<FRAC>
(default 0) Shift the ylabel up or down by I<FRAC> times
the plot height.

B<-fontscale> I<SCALE> 
(default value 1.0) Scale all character fonts by this factor. Characters
in various places have their own scaling; ie title, key, etc. B<fontscale> is an additional
factor that multiplies each of these.

B<-subscale> I<SCALE> 
Scale subscript relative to normal script by this amount.

B<-supscale> I<SCALE> 
Scale superscript relative to normal script by this amount.

B<-ssupscale> I<SCALE> 
Scale super-superscript relative to normal script by this amount.

B<-listcolors> I<N>  
print a list of color names (about 400) for use in strings (for the title, etc.)
If I<N> is given, then color names are listed in I<N> columns. I<N> defaults to four if the argument
is omitted.

B<-findcolors> I<STRING> 
print a list of all color names
that contain I<STRING> as a substring. For example:
C<tridens -findcolors red> lists all colors with 'red' in
the name.

B<-listsymbols> I<N>  
print a list of Adobe symbols for use in strings (for the title, etc.)
If I<N> is given, then symbol names are listed in I<N> columns. I<N> defaults to four if the argument
is omitted. A few aliases to latex symbol names are given.

B<-key>  B<-nokey>
draw the color key. The color key shows the numerical value
correpsonding to colors on the plot. Default is set.

B<-keynbars>  I<NUM> 
(default 33) the number of bars (that is the number of different colors) to draw in the color key.

B<-keylabelskip>  I<NUM> 
(default 4) Print a numerical label on a color bar in the key for
only every NUMth bar. By default there are then 9 numerical labels on the color bars.

B<-explim> 
(default 1) largest power of ten to write in normal, rather than scientific 
notation in the key.

B<-keydigits> I<DIGITS>
(default 2) Number of digits to write in mantissa in key labels.

B<-ticklabeloffset> 
changes distance of tick from frabme

B<-ticksshiftouter> B<-noticksshiftouter> 
(default unset) Offset the outermost ticks slightly to make them more visible.

B<-ticklinew>  I<NUM> 
scale factor for width of tick lines

B<-axislinew>  I<NUM> 
scale factor for width of line in axes

B<-polylinew>  I<NUM> 
scale factor for width of line around polygon

B<-framelinew>  I<NUM> 
scale factor for width of line in frame.

B<-ticklength>  I<NUM> 
(default 1) A scale factor for the ticklength.


These are scale factors for text in various places on the plot. In addition, there
is an overall scale factor set by B<-fontscale>.

B<-tickfontscale> I<NUM> 
Scale factor for text labeling ticks (default 1)

B<-keyfontscale> I<NUM>
Scale factor for text labeling color bars in key (default 1)

B<-axisfontscale> I<NUM>

B<-exponentfontscale> I<NUM>

B<-numberpolyfontscale> I<NUM>

B<-shownorm>  
show range of hue values rather than raw data range in key (see B<-showraw>)

B<-showraw>
(default is set) show range of raw data in key rather than hue values (see B<-shownorm>)

B<-yaxis> B<-noyaxis>
draw y-axis or not(default)

B<-xaxis> B<-noxaxis>
draw x-axis or not(default)

B<-axis> B<-noaxis>
(default)  draw both x and y axis, or neither

B<-ticks> B<-noticks>
Draw tick marks on all four sides of the frame (default set)

B<-ticksl> B<-noticksl>
Draw tick marks on left side of frame

B<-ticksr> B<-noticksr>
Draw tick marks on right side of frame

B<-tickst> B<-notickst>
Draw tick marks on top side of frame

B<-ticksb> B<-noticksb>
Draw tick marks on bottom side of frame

B<-frame> B<-noframe>
Draw a rectangular frame around the plot (default true)

B<-xbuf> I<XFRAC> , B<-ybuf> I<YFRAC>, B<-buf> I<FRAC> (default 0.03)  
space left between plot and frame as a fraction of
plot width. In interactive mode, you must use 'replot' for this change to take effect. Use B<-buf> to
set both the x and y buffer fractions to the same value.

=head2  Output:

B<-outfile> I<FILENAME> 
write the plot to file I<FILENAME> rather than the default, which is to append
a filename suffix (.ps,.eps,.pdf) to the input filename.

B<-infile> I<FILENAME> 
The final non-option arguments on the command line are also interpreted as
input filenames. This is intended for interactive use. But the B<plot>
command also can set the input filename.

B<-display> B<-nodisplay> 
Launch external viewer if possible (ghostview by default). The command to launch
the viewer is given by the $ViewerGvCmd parameter.
If unset, theen suppress launching viewer, even in interactive mode.


B<-plotwidth> I<PLOTWIDTH>  (default 12) 
the width of the plotted data area in centimeters. If the plot
is too big for the page and eps or pdf are requested, then the plot is automatically rescaled
to fit on the page.

B<-viewerscale> I<SCALE> 
If using gv as a viewer, scale (that is, magnify) the viewing area by
this amount. If you use a different viewer, change the variable $ViewerScaleOpt in the
configuration file.

Note that if you change the file type in interactive mode with the following three commands, you
must enter 'viewer' to launch a new viewer for the new output plot.

B<-ps>       
Set the output file format to ps, PostScript.

B<-eps>
Set the output file format to eps, Encapsulated PostScript.
(must have ghostscript installed)

B<-pdf>
Set the output file format to pdf. (default)
(must have ghostscript installed)  

B<-latexrun>  B<-nolatexrun>
(default unset) Process the text (eg in title and labels) as latex commands. This calls
the ipe program to run latex and replace the text with the output of latex.
For instance set xlabel '$e^{x^2}$' will give the desired result. The numbers in the
key are not rendered correctly by ipe unless the B<-latexnumbers> option is also
set. The pdftoipe program does not try to recenter the resulting image. You may have
to do something like
set xlabel ' \white .................\black  $e^{x^2}$', to put a series of invisible
dots to acheive centering. Or try the option B<-xlabelxoffset>. Backslashes in
latex code must be escaped with a backslash. Ie. $\\frac{1}{2}$


B<-latexnumbers>
Write numbers in the key as latex commands. If option B<-latexrun> is set, they
will be processed by latex with the ipe program.

B<-bbpad> I<PSPOINTS>
(default 5) Number of PostScript points by which to enlarge the bounding box in each direction.
Increase this if part of the plot is clipped at the edge. Decrease this if too much white space
is shown around the plot. (This is relevant for 'eps' and 'pdf' formats)


B<-whitebox> B<-nowhitebox>
(default on) Draw a white (invisible) frame around 
the entire plot (including amount specified by option B<bbpad>.) 
Some programs such as ipe recompute the bounding box, which defeats
the purpose of bbpad. These programs will  compute the bounding box around this white
frame. Otherwise small errors can cause a small part of the plot or text to
be clipped.


B<-portrait>
(default)

B<-landscape>
Rotate the plot by 90 degrees.

=head2  Miscellaneous:

B<-readline> B<-noreadline>
If set, (some of) command history, commandline editing and command completion are 
enabled. This only works in interactive mode and depends on having one of
the  perl readline libraries installed (the perl gnu readline library is probably best).

B<-autodata> B<-noautodata>
(default is set) Attempt to detect the data file format. A line with three columns of
data is interpreted as "x y val". A line with more data on a line is assumed to be
on a grid ('grided') If B<-grided> is set, then this detection is overriden even
if B<-grided> is set. For instance, if the data is intended to be on a grid that is
three data points wide (rather uncommon), each line will be misinterpreted
as "x y val".

B<-grided>  B<-nogrided>
(default is unset) If unset then data file must have lines of triples "x y value".
(But see option B<autodata> to set data format automatically.)
If B<-grided> then  the data file must have rows separated by newlines interpreted as follows:
The number in row j, column i is the value of a data point at position i,j;
that is, the data is assumed to be on a grid of unit squares.

B<-ex> I<n>  
write example plot number I<n>. If B<-display> is given, show plot in viewer.

B<-demo> I<n>  
write and display all example plots. If optional number I<n> is given,
there is a pause of I<n> seconds between plots.

B<-v>   
verbose print more messages during operation.

B<-version>  
print tridens version number and exit.

B<-test>  
run the test suite. requires first running B<-generatetest> with a good copy of tridens.

B<-generatetest> 
generate the test suite. only for development. Currently broken

=for trihelp options stop

=head1 REQUIREMENTS AND DEPENDENCIES

Tridens requires a standard perl installation to produce postscript.

ghostscript ('gs') must  be installed to produce eps and pdf files.

ghostview ('gv') or xpdf must be installed if you want
tridens to launch viewers at the appropriate time.  It is
probably possible to use other viewers as well.

While not necessary for interactive mode, a perl readline
package must be installed in order for readline support
(command history, command line editing, tab completion) to
be enabled. This makes the interactive mode much more friendly. The
perl gnu readline is probably best.

The ipe program is necessary for the B<-runlatex> option to process latex
text.

kdialog is used by command gset.

=head1 AUTHOR

John Lapeyre <lapeyre aaat physics doot arizona dat edu>

=head1 BUGS


=head1 FILES

Tridens is distributed as a single file.

=head1 COPYRIGHT

Copyright 2003, 2011 John Lapeyre, All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

=cut

# END User documentation that is extracted from this file and formatted in various ways.

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#  Shell package is interactive mode code. Readline, etc. Interactive commands        #
#  are handled here.                                                                  #
#                                                                                     #
#                                                                                     #
#=====================================================================================#

#==========================================================================
# We must put this shell routine first lexically, if I want to use the 'our'
# variables below in the main program

package Shell;

sub Shell::TRUE ()  { 1 }
sub Shell::FALSE () { 0 }

sub Shell::deb {
    my $s = shift;
    print "$s\n";
}


# libterm-readline-gnu-perl is fucking brain dead.
# Of course this won't work when the guts, or interface changes

# almost this is an exact copy (modulo change of varnames)
# of readline method  in Gnu.pm.
# removed 'autohistory' feature. This gave better control of
# history. Like not adding same command twice in a row.

sub Shell::tri_readline {
    my $term = shift;
    my $Attribs = $term;
    my $self = $term;
    my ($prompt, $preput) = @_;

    my $module = $term->ReadLine();
    return $term->readline(@_) unless $module eq 'Term::ReadLine::Gnu' ;

    # ornament support (now prompt only)
    $prompt = ${$Attribs->{term_set}}[0] . $prompt . ${$Attribs->{term_set}}[1];
    
    $Attribs->{completion_entry_function} = $Attribs->{_trp_completion_function}
	if (!defined $Attribs->{completion_entry_function}
                && defined $Attribs->{completion_function});

    # TkRunning support
    #    if (not $Term::ReadLine::registered and $Term::ReadLine::toloop
    #	and defined &Tk::DoOneEvent) {
    #	$self->register_Tk;
    #	$Attribs->{getc_function} = $Attribs->{Tk_getc};
    #    }

    # call readline()
    my $line;
    if (defined $preput) {
	my $saved_startup_hook = $Attribs->{startup_hook};
	$Attribs->{startup_hook} = sub {
	    $self->rl_insert_text($preput);
	    &$saved_startup_hook
		if defined $saved_startup_hook;
	};
	$line = $self->rl_readline($prompt);
	$Attribs->{startup_hook} = $saved_startup_hook;
    } else {
	$line = $self->rl_readline($prompt);
    }
    return undef unless defined $line;

    # history expansion
    if ($Attribs->{do_expand}) {
	my $result;
	($result, $line) = $self->history_expand($line);
	my $outstream = $Attribs->{outstream};
	print $outstream "$line\n" if ($result);

	# return without adding line into history
	if ($result < 0 || $result == 2) {
	    return ''; # don't return undef which means EOF.
	}
    }

    # add to history buffer
    #    $self->add_history($line)
    #	if (defined $self->{MinLength} && $self->{MinLength} > 0
    #	    && length($line) >= $self->{MinLength});
    return $line;
}                               # end sub tri_readline {


our (%ComActs);
#no strict 'vars';  # maybe this is not needed ??


# commands set,unset,gset send their args here
# for processing.
sub Shell::set_options {
        my ( $setflags, $st ) = @_;
        my %h = ();
        $Tridens::SettingOpts = TRUE;
        my ( $st1, $res );
        $st =~ s/\\/\\\\/g;    # double the backslash
        $st =~ s/\"/\\\"/g;    # escape the double quotes
        no warnings 'all';     # we handle user error
        if ( $InterpolateCmd == TRUE ) {
            &Tridens::verbose( "evaluating input:" . "\$st1 = \"$st\"" )
              ;                # do interpolations
            $res = eval "\$st1 = \"$st\"";    # do interpolations
            &Tridens::verbose( "evaluated input:'" . $res . "', $st1" );
        }
        else {
            $st1 = $st;
            $res = 1;
        }
       use warnings 'all';                   # we handle user error
        if ( not defined $res ) {    # double quotes now work for string
            print STDERR "Error in input.\n";
            if ( $st =~ /\"/ ) {
                print STDERR "Did you use \" instead of ' ?\n";
                $@ = '';

            }
            return undef;
        }
        &Tridens::verbose( "parsing:'" . $st1 . "'" );

        #  warn "WARNING $@" if $@;
        $st1 = quote_complex_interactive_command_args($st1);
        @ARGV = Text::ParseWords::shellwords($st1);    # preserve quoted strings
        if ( @ARGV == 0 ) {
            print STDERR "No argument supplied.\n";
            return;
        }
        &Tridens::verbose( "words: " . join( ":", @ARGV ) );
        $ARGV[0] = '-' . $ARGV[0] unless $ARGV[0] =~ /^\-/;
        return undef unless GetOptions( \%h, @Tridens::Optlist );
        if ( @ARGV > 0 ) {
            print STDERR "Ignoring extra words at end of line '"
              . "Did you mean: -$ARGV[0] or forget to use single quotes?\n";
        }
        Tridens::first_process_command_line_options( $setflags, \%h );
        Tridens::process_command_line_options( $setflags, \%h );
        return undef;
}

# note  this variable my be useful: attempted_completion_over
sub Shell::command_completion_function {
    my ( $text, $line, $start ) = @_;
    my @coms = sort keys %ComActs;
#    print("<<$text>><<$line>><<$start>>\n");
#    $term->Attribs->{filename_completion_desired} = 1;
#    $term->Attribs->{filename_quoting_desired} = 1;
#    $term->Attribs->{filename_quote_characters} = " ";
#    deb   "basic '" . $term->Attribs->{basic_quote_characters} . "'";
#    deb   "fname q ch '" . $term->Attribs->{filename_quote_characters} . "'";
#    deb   "bas wb ch <<" . $term->Attribs->{basic_word_break_characters} . ">>";
#    deb   "compllete qu ch <<" . $term->Attribs->{completer_quote_characters} . ">>";
    $term->Attribs->{completer_quote_characters} = "'\""; # this one is necessary
    my $completion_words = [];
    if ( $line =~ /^\s*!/ ) {
        return();
    }
    if ( $line =~ /^\s*[^\s]*$/ ) {
             $completion_words = [@coms];
    }
    if ( $line =~ /^\s*(set|se)\s+[^\s]*$/ ) {
	$completion_words =  \@Tridens::Optlistnames_set;
    }
    if ($line =~ /^\s*(set|se)\s+batch/ ) {
        return (); # empty list defaults to filename completion
    } 
    if ( $line =~ /^\s*(show|sh|sho)\s+[^\s]*$/ ) {
	$completion_words =  \@Tridens::Optlistnames_show;
    }
    if ( $line =~ /^\s*se\w+\s+font\s+[^\s]*$/ ) {
	$completion_words = [ keys %Tridens::FontList];
    }
    if ( $line =~ /^\s*(h|he|hel|help)\s+[^\s]*$/ ) {
	$completion_words = [sort keys %Tridens::HelpInteractive];
    }
    if ( $line =~ /^\s*(u|un|unse|unset)\s+[^\s]*$/ ) {
	$completion_words = \@Tridens::BoolVars;
    }
    if ( $line =~ /^\s*(p|pl|plo|plot)\s+/ ) {
	return (); # empty list defaults to filename completion
    }
    if ( $line =~ /^\s*(load|save)\s+[^\s]*$/ ) {
	return (); # empty list defaults to filename completion
    }
    foreach my $command (keys %Tridens::CommandCompletions) {
	if ( $line =~ /^\s*se[^\s]+\s+$command\s+[^\s]*$/ ) {
		$completion_words = $Tridens::CommandCompletions{$command} ;
	}
    }
    $term->Attribs->{completion_word} = $completion_words;
    my @matches = $term->completion_matches($text,
                                     $term->Attribs->{'list_completion_function'});
    return @matches if @matches > 0;
    return (''); # '' prevents defaulting to filename completion
}

# More command actions are defined inside sub run_shell
# They use my variables in run_shell
%Shell::ComActs = (

    'plot' => sub {
	$_[0] =~ s/^\s*[\'\"]//;
	$_[0] =~ s/[\'\"]\s*$//;    #remove literal quotes
	Tridens::plot_or_replot( $_[0] );
	return undef;
    },

    'replot' => sub {
	$_[0] = $Tridens::Infile if $_[0] =~ /^\s*$/;    # replot old file
	if ( not defined $_[0] ) {
	    Tridens::herror("No input file");
	    return undef;
	}
	&Tridens::read_data( Text::ParseWords::shellwords( $_[0] ) );
	$_[0] =~ s/^\s*[\'\"]//;
	$_[0] =~ s/[\'\"]\s*$//;
	Tridens::plot_or_replot( $_[0] );
	return undef;
    },
    '!' => sub { my $s = `$_[0]`; chomp($s); $s },
    'fshow' =>
         sub { &Tridens::print_all_parameters( $_[0] ); return undef },
    'gset'    => sub { 
	my ($opt) = @_;
	my ($arg,$h);
	    if ( exists $Tridens::OptHandlers{$opt}) {
		$h = $Tridens::OptHandlers{$opt};
	    }
        	else {
		print "Can't gset that option\n";
		return;
	    }
	    if ( ref($h) ne 'ARRAY' and exists $h->{GUI} and  $h->{GUI} eq 'inputfile' ) {
		    $arg = &Tridens::get_kdialog_openfilename(); 
	    }
	    else {
		print "Can't gset that option\n";
		return;
	    }
	    set_options( { SET   => 1 }, ("$opt '$arg'") ) },
        'set'    => sub { set_options( { SET   => 1 }, @_ ) },
        'unset'  => sub { set_options( { UNSET => 1 }, @_ ) },
        'viewer' => sub {
            $Tridens::ViewerStarted = FALSE;
            Tridens::check_viewer();
            return undef;
        },
        'read' => sub {
            &Tridens::read_data( Text::ParseWords::shellwords( $_[0] ) );
            return undef;
        },
	'print_data_info' => \&Tridens::data_file_info_print,
# undef outfile here so that subsequent plots recompute the outfilename based on input file
        'example' => sub {
            my $n =  $_[0];
            &Tridens::setup_example_plots();
            if ( not defined $n or not &Tridens::is_posint($n) or $n > $Tridens::NumberOfExamplePlots ) {
                &Tridens::herror("example needs an example number between 1 and $Tridens::NumberOfExamplePlots");
                return;
            }
            &Tridens::do_example( $_[0], 'view' );
            $Tridens::Outfile = undef;
        },
        'man'  => sub { &Tridens::show_man_page();  undef; },
        'html' => sub { &Tridens::show_html_page(); undef; },
        'demo' => sub {
            $Tridens::DoAllExamples = 0;
            &Tridens::do_all_examples();
            undef;
        },
        'h' => sub { &Tridens::show_short_help(); undef; },
        'save' => sub { &Tridens::dump_parameters(@_); },
        'load' => sub { &Tridens::load_parameters(@_); }
    );


    # perl gnu readline is a miserably fucked up package.
    # It is impossible to get simple reasonable behavior out 
    # of it. But it takes forever to figure that out because
    # the docs are so miserable and fucked up.
    # Eg, whoever wrote the interface added a great 'autohistory' feature
    # that is hardwired to 'on'.

sub Shell::start_readline {
    $term = Term::ReadLine->new('tridens');
    $term->MinLine(3); # min linelength for history. my hack makes this useless
    eval '$term->read_history( ".history.tridens", 0, 5000 )';
    $@ = '' if $@;
    my $attribs = $term->Attribs;
    if ( defined $term->Features->{attribs} ) {
	$term->Attribs->{completion_query_items} = 200;
        $term->Attribs->{attempted_completion_function} = \&command_completion_function;
    }
    return $term;
}

sub Shell::run_shell {
    my $exit;
    my $term = undef;
    use Getopt::Long;
    $E  = 1;              # only to stop warning
    $Pi = 1;
    $Pi = $Tridens::Pi;
    $E  = $Tridens::E;
    my $showsub = sub {
        $Tridens::SettingOpts = FALSE;
        @ARGV                 = Text::ParseWords::shellwords( $_[0] );
        foreach (@ARGV) { $_ = '-' . $_ unless /^\-/; }    # prepend dash
        my %h = ();
        GetOptions( \%h, @Tridens::OptlistShow );
        Tridens::first_process_command_line_options( \%h );
        Tridens::process_command_line_options( \%h );
        return undef;
    };

    $ComActs{exit} = sub { $exit = TRUE; };
    $ComActs{show} = $showsub;
    $ComActs{help} = sub {
            my ($opt) = @_;
            if ( defined $opt ) {
                $opt = &Tridens::strip_spaces($opt);
                my $h = $Tridens::OptHandlers{$opt};
                $h = [$h] unless ref($h) eq 'ARRAY';
                if ( exists  $Tridens::HelpInteractive{$opt} ) {
		    my $c = 80;
		    my $r;
		    if ($Tridens::UseReadline == TRUE) {
			eval '( $r, $c ) = $term->get_screen_size()';
			$c = 80 if $@;
			$@ = '';
		    }
                    $Text::Wrap::columns = $c - 20;    # works kinda
                                                       #	deb("columns $c");
                    print
                       &Text::Wrap::wrap( '', '', $Tridens::HelpInteractive{$opt} ) . "";
                    return undef;
                }
            }
            print "Try 'man' or 'html' for help or 'h' for short help.\n"
		. "Type 'help' and TAB twice to get a list of help topics\n"
              . "Try 'example n' to run example number n.\n";
            undef;
    };


    # make commands out of these things that are also called via 'set'
    foreach my $com (qw( listcolors findcolors listsymbols listfonts )) {
        $ComActs{$com} = sub {
            Tridens::process_command_line_options( { $com => $_[0] } );
            return undef;
          }
    }
    # fonts , etc. should be handled through a data structure
    # that also does checking with check_string_args below
    # I think that the first two examples in the perl/gnu readline manual will
    # 

    $term = start_readline() if ( $Tridens::UseReadline == TRUE );

    my $prompt = "tridens> ";
    my ($input);
    my @batch_lines;
    print "tridens v$VERSION  Type 'help'.\n";

#    while ( scalar(@batch_lines)> 0 or defined ($input = $term->readline($prompt)) ) {
    my @coms = sort keys %ComActs;
    for ( ; ; ) {
        if ( defined $Tridens::BatchFile ) {
            deb "here is $Tridens::BatchFile";
            if ( $Tridens::BatchFile eq '-' ) {
                @batch_lines = `cat`;
            }
            elsif ( not -e $Tridens::BatchFile ) {
                &Tridens::herror("Batch command file '$Tridens::BatchFile' does not exist.");
            }
            else {
                @batch_lines = `cat \"$Tridens::BatchFile\"`;
            }
            $Tridens::BatchFile = undef;
        }
        if ( $Tridens::UseReadline == FALSE ) {
	     $term = undef; 
	}
	else {
	    $term = start_readline() unless defined $term;
	}
        my $cflag = FALSE;
        $exit = FALSE;
        if ( @batch_lines > 0 ) {
            $input = shift(@batch_lines);
            chomp($input);
            print "$prompt$input\n";
            $Tridens::BatchFile = undef unless @batch_lines > 0;
        }
        elsif ( defined $term ) {
#            $input = $term->readline($prompt);
            $input = Shell::tri_readline($term,$prompt);
        }
        else {
            print $prompt;
            $input = <STDIN>; # need the STDIN !
        }
        last unless defined $input;
        $input = &Tridens::strip_spaces($input);
        my $tinp = $input;
        my $res;
        if ( $tinp =~ s/^\s*(\!)|((\w+)(\s+|$))// ) {
            # check for a command in first word
            # the '!' does not need a space, other commands do.
            my $incom;
            if   ( defined $1 and $1 eq '!' ) { $incom = $1 }
            else                              { $incom = $3 }
            foreach my $com (@coms) {
                if ( $com =~ /^$incom/ ) {    # only need type first part of com
                    $res   = &{ $ComActs{$com} }($tinp);
                    $cflag = TRUE;
                    last;
                }
            }
            if ( $cflag == FALSE ) {
                #print "Unknown command '$incom'\n";
                #next;
            }
        }
        if ( $exit == TRUE ) { return; }
        $res = eval($input) unless $cflag == TRUE;
        warn "error: $@" if $@;
        print $res, "\n" if defined $res and not $@;
        $@ = '';
	if ( $Tridens::UseReadline == TRUE  and defined $term) {
	    my ($ilast, $last_input);
	    $ilast = $term->Attribs->{history_length};
	    eval '$last_input = $term->history_get($ilast)';
	    if ( $@ ) {
		$@ = '';
	    }
	    else {
		$term->add_history($input) unless ($input eq $last_input) or length($input) < 3;
	    }
	}

    }    # end for(;;)
    eval '$term->write_history(".history.tridens")' if $Tridens::UseReadline == TRUE
	and defined $term;
    print "\n";
} # end sub run_shell

# only used now for set mark
sub Shell::quote_complex_interactive_command_args {
    my ($s) = @_;
    $s =~ /^\s*(\S+)\s+(.+)/;
    my $h = \%Tridens::OptHandlers;

    #    deb( "quote got '$1' : '$2'");
    return $s unless defined $1;
    my $com = $1;
    my $arg = $2;
    if (    exists $h->{$com}
        and ref( $h->{$com} ) eq 'HASH'
        and exists $h->{$com}->{VALTYPE}
        and $h->{$com}->{VALTYPE} eq 'string' )
    {
        return $s if $arg =~ /^\s*[\'\"]/;
        return ( $com . " '" . $arg . "'" );
    }
    return $s;
}

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#  Declare our varables in Tridens pacakge                                            #
#                                                                                     #
#                                                                                     #
#=====================================================================================#


package Tridens;
use strict;
use Getopt::Long;

sub Tridens::TRUE ()  { 1 }
sub Tridens::FALSE () { 0 }

# Declare user settable parameters, and most other global variables

our ($OptionArg)
  ;    # kludge. use this var temporarily for storing value when setting option

our (
    $PlotWidth,    $AspectRatio,  $LandScape,     $Xmin,           $Xmax,
    $Ymin,         $Ymax,         $XTickStart,    $XTickInt,       $YTickStart,
    $YTickInt,     $ZeroAbs,      $Pow2Eps,       @MagicIntervals, @Divisions,
    $ColorMap,     $Hue,          $XLabel,        $YLabel,
    $RotateYLabel, $Title,        $TitleYOffset,  $TitleXOffset,
    $LBound,       $HBound,       $TickInterval,  $NumberOfSides,
    $AutoLength,   $LengthOfSide, $XLengthOfSide, $YLengthOfSide,
    $SameUnits,    $Rotation,     $Rotation2,     $PSFormat,
    $BoundingBoxPad, $TTickDraw,              $BTickDraw,       $LTickDraw, $RTickDraw,
    $FrameDraw,
    $PolyBorder,     $TriHexDraw,         $LatticeGray, $NumberPoly,
    $NumberPolyDig,  $NumberPolySciLim,   $NumberPolyZero,
    $NumberPolyGray, $NumberPolySciScale, $LatexNumbers,
    $DotForTimes,        $XAxis,          $YAxis,   $DataNorming,
    $DataTransformPower, $UseColTrans,    $ColorMapHi,
    $ColorMapLo,         $ShowNormalized, $DrawKey, $NumKeyBars,
    $KeyLabelSkip,       $KeySepGray,     $KeyExpRaise, $Xbuf, $Ybuf,
    $PlainFontname,      $ItalicFontname, $Font,        $BoldFontname,
    $BoldItalicFontname, $Saturation,     $Brightness,  $KeyYOffset,
    $KeyXOffset,         $KeyWidth,       $KeyHeight,
    $XLabelYOffset,   $YLabelXOffset,   $XLabelXOffset,  $YLabelYOffset,
    $KeyDigits,       $ExponentLimit,
    $TickLabelOffset, $TicksShiftOuter, $PolyLineWScale, $FrameLineWScale,
    $KeyLineWScale,   $AxisLineWScale, $TickLineWScale,
    $TickLengthScale, $TickFontScale,  $KeyFontScale,

    #$TitleFontScale,
    $AxisFontScale, $NumberPolyFontScale, $ExponentScale,
    $WriteBBox,    $WhiteBoxDraw, $PostScriptInterpreter, $BBoxCommand,
    $GridDataFile, $DetectDataFormat, $RunShell,     $UseReadline,     $InterpolateCmd,
    $LatexRun, $FontScale, $Subscale, $Supscale, $SSupscale,
    );

our (
    $Outfile,                      $ExampleNumber,
    $DoAllExamples,                $ViewerGvCmd,
    $ViewerXpdfCmd,                $Viewer,
    $PdfToIpe,                     $IpeToIpe,
    $ViewerScaleOpt,               $ViewerScale,
    $PostScriptInterpreterOptions, $FontPath,
    $Display,                      $HaveData,
    $ViewerStarted,                $ViewerPid,
    $Pi,                           $E,
    @Optlist,                      @OptlistShow,
    @Optlist_non_interactive,      @Optlist_setable,
    @Optlistnames_set,             @Optlistnames_show,
    $BatchFile,                    $Browser,
    $PdfLatex,                     %RgbCodes,
    @RgbNames,                     $NumberOfExamplePlots,
    %Symcodes,                     @Symcodelist,
    %Symaliases,                   @Symaliaslist,
    $SScriptScale
);

our ( $InterruptSent, $ParameterList );

our (%Marks);
our (%FontList);
our ($ShortHelp);
our (%DataFileInfo);


#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#  User parameter file. This is maybe not as useful as before interactive mode was    #
#  written                                                                            #
#                                                                                     #
#=====================================================================================#

#==========================================================================
# User parameters. These can be set by the user to change the behavior of the program.

=for comment
 The default values of the user parameters are set be eval'ing
 the string $ParameterList. This string can also be printed to 
 a file that can be edited and read, as well.

=cut 

BEGIN {
    
    our $ParameterList = <<'EOPARAMS';

# You can use TRUE or 1 to set options and FALSE or 0 to unset them.
    
# Set to TRUE to run in interactive mode.
$RunShell = FALSE;

# Desired width of plot in cm, excluding key and
# tick labels.
$PlotWidth = 12;

$AspectRatio = 1;

#  Set to one to plot landscape
$LandScape = FALSE;
#$LandScape = TRUE;

# Set the plot range. A limit is automatic if any of these is not defined.
# These are ranges in units of input data.
#$Xmin = -20;
#$Xmax = 25;
#$Ymin = -20;
#$Ymax = 20;

# Use color or grayscale to denote data value.
# color 1, grayscale 0
$ColorMap = 'hue';  
#$ColorMap = 'cmgray';
#$ColorMap = 'saturation';

# These are the title and labels strings. Escape codes can be used as described in
# the manual.
$XLabel = '';
$YLabel = '';
$Title = '';
# Distance from plot border to title as fraction of plot height
$TitleYOffset = 0.07; 

# move title some from center
$TitleXOffset = 0; 
# set this to 1 or 0 to rotate the y axis label or not
$RotateYLabel = FALSE;

# Whether to draw ticks on L,R,B,T sides of frame
$TTickDraw = TRUE;
$BTickDraw = TRUE;
$LTickDraw = TRUE;
$RTickDraw = TRUE;

$FrameDraw = TRUE;

# for labeling tick marks, numbers smaller than this are zero.
$ZeroAbs = 1e-12;  

# if a number is closer than this to a power of 2. Replace it with
# closest integer in test for power of 2 for tick marks.
# This could cause a problem if we are plotting over a range smaller
# than pow2eps
$Pow2Eps = 1e-12;

# Choose Either Squares of Hexagons here.

# set this to 1 to compute the nearest neighbor distance
# and to set the length of the side of the squares or hexagons automatically.
# This takes more time and requires that there is a data point at a nearest
# neighbor of the first data point in the file. This will override the
# LengthOfSide set below.
# In order to use LengthOfSide you *must* set AutoLength=FALSE;

$AutoLength = TRUE;
#$AutoLength = FALSE;

# If the x and y axes have the same units, set this to TRUE.
# If they have different units (eg different physical quantities), set this
# to FALSE.
$SameUnits = FALSE;

# set to FALSE if data file has lines of triples "x y value"
# set to 1 if data file has rows separated by newlines interpreted as follows
# the number on row $j, column $i is the value of a data point at position $i,$j,
# that is the data is assumed to be on a grid of unit squares.
$GridDataFile = FALSE;

# try to guess the data file, format. eg. grided or not.
$DetectDataFormat = TRUE;

# Select these to plot Hexagons
# Input x and y values for data should then be
#  points on a triangular lattice.
# If the lattice spacing on the triangular lattice is 1, then the
# correct hexagon has side length 1/sqrt(3), and is rotated 
# 30 degrees.
#$NumberOfSides = 6;
#$LengthOfSide =   1/sqrt(3);
#$Rotation = '30';

# Select these to plot Squares. Input x and y values for data
# should then be points on a square lattice.
$NumberOfSides = 4;
$LengthOfSide = 1;
$Rotation = '0';

# define these to override automatic setting of side lengths
# if -nosameunits is set.
#$XLengthOfSide =  $LengthOfSide;
#$YLengthOfSide =  $LengthOfSide;

# This is used for triangles. Currently broken.
$Rotation2 = '0';

# Whether to make ps, eps or pdf file.
# use  'ps', 'pdf', or 'eps'.
# This script alone will make ps files.
# if you set this for pdf or ps, you must have
# the ghostscript program installed. (See $WriteBBox
# below if it is not a standard installation)
$PSFormat = 'pdf';
#$PSFormat = 'eps';
#$PSFormat = 'ps';

# pad the bounding box by this number of points
$BoundingBoxPad = 5;

# draw a white (invisible) box around entire plot image, to prevent
# other programs from recomputing bounding box and removing the 
# BoundingBoxPad
$WhiteBoxDraw = TRUE;

# If TRUE, draw a black border around each polygon
# as well as its density color.
$PolyBorder = FALSE;

# whether to draw underlying triangular lattice on Hexes
# 0 = don't draw
# 1 = draw only on hexes corresponding to data points
# 2 = draw triangular lattice over entire plot
$TriHexDraw = 0;
$LatticeGray = 0; # darkness of line (0=black, 1=white);

# whether to write the numeric data value inside the polygon
$NumberPoly=FALSE;
# number of digits after decimal to write
$NumberPolyDig = 3;
# use sci. notation for abs(exponent) greater than this
$NumberPolySciLim = 2;
# set to zero to supress printing values equal to zero
$NumberPolyZero = FALSE;
# gray level for numbers (0=black, 1=white)
$NumberPolyGray = 0;
$NumberPolySciScale = .7;

# Whether to draw x and y axes.
$XAxis = FALSE;
$YAxis = FALSE;

# Data must be transformed into [0,1] for a density plot.
# This chooses how data values are mapped onto colors or gray values.
# If 'power' is chosen, set value of the power below.
# Notice that there is one more transform that maps the normed data in
# [0,1] onto a subinterval of [0,1]. This can be used to choose just
# subset of gray or color values, or to invert their meanings. These
# transform is set with $UseColTrans and $ColorMapHi and $ColorMapLo
$DataNorming = 'linear';
#$DataNorming = 'power';

# if taking root of data for plotting, use this power.
# If data is normalized between 0 and 1, a fractional power
# here will spread out the colors on the values near 1.
# If set to 1, the power will not be taken even if $DataNorming = 'power'.
$DataTransformPower = (1/2);

# parameters for linear transform of color/gray scale

# That data is normalized to the values that hue can assume in an
# RGB color. But, we may want to do an additional linear transform.
# Whether to do this transform (described below). 0=no, 1=yes
$UseColTrans = TRUE;

# maps normalized data values in [0,1]  into an subinterval
# of the color space (which is also  [0,1]. )
# This allows inversion or cutting out some
# colors. ColorMapHi=1, ColorMapLo=0 is the identity transform.
# reversing these inverts the color or grayscale.
# These numbers are the endpoints of the subinterval.
$ColorMapHi =  1;
$ColorMapLo =  .2;

# whether to show the normalized data, or raw data on key
# and in hexes. If set to zero, raw data values will be printed in
# the key. If set to 1, the linearly normalized data is show in the key.
# That is the effects of  power, log, color transform etc., are not
# shown on the plot.
$ShowNormalized = FALSE;
#$ShowNormalized = TRUE;

# Draw key to plot if = TRUE
$DrawKey = TRUE;

# number of colors/grays to show in key for plot
$NumKeyBars = 33;

# The key shows several bars with colors. Put a numerical label on every
# nth bar, where n is KeyLabelSkip. Eg, a value of 1 means print a label on
# every bar.
$KeyLabelSkip = 4;


# Gray value for horizontal lines separating key colors
# Currently these lines are not drawn, so this does nothing
$KeySepGray = .5;

# space between plot area and frame drawn around plot
# as fraction of plot width.
$Xbuf = 0.03;
$Ybuf = 0.03;

# Choose font names.

$Font = 'times';
# below will be overwritten if above is defined
$PlainFontname = 'Helvetica';
#$PlainFontname = 'lmr10';
$ItalicFontname = 'Helvetica-Oblique';
$BoldFontname = 'Helvetica-Bold';
$BoldItalicFontname = 'Helvetica-BoldOblique';

# A colon separated list of directories where fonts (Type 1) are located.
# This is only necessary if you want to use one or more fonts in these directories,
# and you are writing a pdf file
#$FontPath = "";
#$FontPath = "/usr/share/texmf/fonts/tfm/public/lm";
$FontPath = "/usr/share/texmf-texlive/fonts/type1/public/cm-lgc";

# This is multiplier for the size of all fonts to make them bigger or smaller.
# Eg, $FontScale = 2 or $FontScale = 0.5, to make the fonts twice as big or half as big.
# Additional scaling of each font size is set in parameters below.
# $FontScale also affects the positioning of the characters.
$FontScale = 1.0;

#  Scaling factors for sub,super,supersuper script fonts,
#  relative to normal font.
$Subscale = .60;
$Supscale = .62;
$SSupscale = .55;

# this scale factor is for the amount of vertical shift for a superscript
# Take the height of the character on which we want to put the superscript and
# multiply it by this amount. So a value of 1 puts is just above the character.
# (except there are a host of other imprecisions that move it a bit)
$SScriptScale = .95;

# parameters for color map. Colors are chosen with hue,saturation,
# brightness model.
# If $ColorMap is set to 'hue' via option cmhue, then only Saturation and
# Brightness have an effect on the plot, because the hue is determined by
# the value of the data point.
$Hue = .1;
$Saturation = 1;
$Brightness = 1;

# Key is drawn flush with bottom right corner of plot, unless
# offsets are nonzero.
# $KeyYOffset is fraction of height of frame. So 0.1 will move it 1 tenth
# up the frame. $KeyXOffset is fraction of width of frame. So 0.07 means shift
# to the right by a distance 7% of the frame width.
# Key height will be frame height times $KeyHeight.
# So $KeyHeight=1 make the key run the entire length of the frame
# $KeyWidth is fraction of frame width. 
$KeyYOffset = 0.0;
$KeyXOffset = 0.1;
#$KeyWidth = 0.04;
$KeyWidth = 0.03;
$KeyHeight = 1;

# Fraction of character height to raise exponent in scientific notation in the key
$KeyExpRaise = 0.55;

# how far to move axis labels off of frame. As fraction of dimension of frame.
$XLabelYOffset = 0.07;
$YLabelXOffset = 0.07;

# text is normally centered use these to adjust, range -1 to 1
$XLabelXOffset = 0;
$YLabelYOffset = 0;

# How many digits to print to right of decimal in floating point numbers in they key
$KeyDigits = 2;

# Max. absolute value of exponent before we switch to using scientific notation
# rather than ordinary decimal notation.
$ExponentLimit = 1;

# Tick labels are drawn flush with frame unless this is non-zero.
# This gives a fraction of frame width to move labels away from frame.
$TickLabelOffset = 0.01;
#$TickLabelOffset = 0.0;

# set true to move outermost ticks in
$TicksShiftOuter = FALSE;

# Default Line-widths/lengths will be multiplied by these numbers
$PolyLineWScale    = 1;  # scale linewidth of drawn polyborder
$FrameLineWScale     = 1;  # for frame around plot
$KeyLineWScale     = 1;  # for frame around plot
$AxisLineWScale     = .5;  # for lines denoting the axes
$TickLineWScale    = 1;  # for tick marks
$TickLengthScale  = 1;   # scale length of ticks
$TickFontScale    = 1;   # scale tick font
$KeyFontScale    = .8;   # scale numbers on color key
#$TitleFontScale    = 1;   # scale numbers on color key
$AxisFontScale   = 1;  # scale labels on axes
$NumberPolyFontScale = .7; #number inside polygon
$ExponentScale   = 0.75; # scale down size of displayed exponent

# whether to put bounding box in a ps file. For eps and
# pdf $WriteBBox is ignored and a bbox is always needed.
# The bbox is produced by ghostscript.
# This is ignored if you choos $PSFormat = 'eps' or 'pdf'
$WriteBBox = FALSE;

# Command Name of PostScript interpreter 
# (probably gs for ghostscript)
# Set this to '' if you do not have ghostscript installed
$PostScriptInterpreter = 'gs';
#$PostScriptInterpreter = '';

# a list of command line arguments given when invoking the interpreter
#$PostScriptInterpreterOptions = ' -dSAFER ';
# more threads seems to have no effect here.
$PostScriptInterpreterOptions = ' -dSAFER -dNumRenderingThreads=2   ';

# whether to launch a viewer after writing the plot
$Display = FALSE;

# which viewer to use. eg gv or xpdf
$Viewer = 'xpdf';

$ViewerXpdfCmd = 'xpdf -remote TridensServ -z page -aaVector no  ';
# how to invoke the ghostview or other postscript viewer
# We are signaling gv to reload by sending sighup to its pid.
# If this is broken, fall back on ' -watch'.
#$ViewerGvCmd = 'gv -watch';

$ViewerGvCmd = 'gv ';

# following two only work now with gv
$ViewerScaleOpt = ' -scale=%n -spartan ';

$ViewerScale = 2.0;

$PdfToIpe = 'pdftoipe -literal ';

$IpeToIpe = 'ipetoipe ';

# Command to launch your web browser
$Browser = 'firefox';

# command to make pdf from latex
$PdfLatex = 'pdflatex';

# If true, print LaTeX expressions for numbers that can be processed
# by another program, such as ipe. If FALSE we use our own routines
# to write scientific notation
$LatexNumbers = FALSE;

$LatexRun = FALSE;

# draw a dot rather than a times symbol for multiplication
$DotForTimes = FALSE;

# whether to use readline. If false, then just read from a simple loop
$UseReadline = TRUE;

$InterpolateCmd = FALSE;

##########
# Probably never need to change the things below.

# Computing the bbox for eps files would be a PITA.
# I assume a ghostscript interpreter is present and
# ask it to compute the bbox.
$BBoxCommand = $PostScriptInterpreter .  $PostScriptInterpreterOptions .
    " -q -dNOPAUSE -dBATCH -sDEVICE=bbox ";

# List of "pleasing" intervals between ticks on graph.
# Tick intervals are these numbers times the appropriate
# power of ten.
@MagicIntervals = ( 1.0, 2.0, 2.5, 5.0, 10.0 );

# This chooses from  3 to 7 tick marks.
# Preference is given to more ticks:
#@Divisions = (7,6,5);  
@Divisions = (7,6,5,4,3);

# Some Tick Options
# Don't touch these, I think.
$LBound = 'auto';
$HBound = 'auto';
$TickInterval = "auto";

# These are manual tick values. This is currently disabled.
# These are the starting point and interval for ticks.
# Ticks are drawn both directions  from start point, till
# the edge of the plot is reached.
$XTickStart = 0;
$XTickInt = 3;
$YTickStart = 0;
$YTickInt = 3;


EOPARAMS

    eval $ParameterList;

# END User parameters. These can be set by the user to change the behavior of the program
#==========================================================================

}    # end of BEGIN {

our $Verbose;
our $Initfilename = '.tridens';
our $Infile;    # data file name
our $ScriptName = $0;

=for comment
  This prints some messages if the user has selected verbose mode.

=cut

# looks like this is not used
sub INT_handler {
    $InterruptSent = 1;
}

# disable this for now
#$SIG{'INT'} = \&INT_handler;

$InterruptSent = 0;

# debugging routine.
sub Tridens::deb {
    my $s = shift;
    print "$s\n";
}

sub dosys {
    my $s = shift;
    print "$s\n";
    system "$s\n";
}

sub verbose {
    my $mess = shift;
    print STDERR "$mess\n" if $Verbose;
}

sub verbosesys {
    my $com = shift;
    verbose $com;
    system $com;
}


# exit unless we are in interactive mode
sub iexit {
    my ($code) = @_;
    $code = 0 unless defined $code;
    exit($code) unless $RunShell == TRUE;
}

sub herror {
    my $s = shift;
    print STDERR "$s\n";
    iexit(1);
}



#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#  Process command line options. Also handles options set from interactive mode       #
#  Command line completion and interactive help is created here because it comes      #
#  from options setting data. However these are used above in Shell.                  #
#                                                                                     #
#=====================================================================================#

#============================================================================
# Process Commandline Options

=begin comment

  This block parses command line options and takes actions before
  and routines are executed.

=end comment

=cut

{    # initialization block

    $ShortHelp = <<"EOSHH";
Usage: tridens [options] infilename ... 

infilename ... are the input data files

EOSHH

    $Verbose = 0;

   # some of these are not used interactively. Others are not used interactively
   # via 'set' but are promoted to 'commands' in the hash %ComActs.
   # These can be used interactively, but dont show up in completion lists
   # and so forth for 'show' and 'set' since they have no vars associated with
   # them. So this list is actually misnamed.

    @Optlist_non_interactive = (
        'h',            'v',             'i',         'listcolors:i',
        'findcolors:s', 'listsymbols:i', 'ex:i',      'listfonts',
        'man',          'mandoc',        'htmldoc',   'html',
        'pdfdoc',       'textdoc',       'paramfile', 'version'
    );

    # removed because broken: 'hex'
    # these are used both interactively and on the command line
    @Optlist_setable = (
        'verbose!',      'mark:s',
        'latexnumbers!', 'latexrun!',
        'dotfortimes!',
        'cmhue', 'aspectratio=f',
        'bbpad=i',       'subscale=f',   'supscale=f',     'ssupscale=f',
        'buf=f',         'saturation=f', 'brightness=f',   'hue=f',
        'cmhi=f',        'shownorm!',    'showraw!',       'keynbars=i',
        'cmsatbright:f', 'title=s',      'titleyoffset=s', 'titlexoffset=s',
        'xlabelxoffset=f', 'ylabelxoffset=f', 'xlabelyoffset=f',
        'ylabelyoffset=f',
        'explim=i', 'keydigits=i', 
	'viewerpid=i', 'viewer:s', 'readline!',
	'fontscale=f',
        'display!', 'batch=s',     'grided!',  'autodata!',
        'demo:i',     'outfile=s', 'infile=s',  'keylabelskip=i', 'key!',
        'xbuf=f',     'ybuf=f',
        'keywidth=f', 'keyheight=f', 'keyxoffset=f',   'keyyoffset=f',
        'xaxis!',   'yaxis!',  'ticksb!', 'tickst!','ticksl!', 'ticksr!',
        'ticks!',
        'axis!', 'usepower!', 'uselinear!', 
        'numberpoly!', 'square', 'tri', 'circle', 'ps', 'eps',
        'numberpolyfontscale=f', 'viewerscale=f', 'font=s', 'pdf'
        ,             'sidelength=s', 'xsidelength=s', 'ysidelength=s',
        'portrait!',  'landscape!',   'plotwidth=f',   'xlabel=s',
        'power=f',    'lattice!',     'latticegray=f', 'cmlo=f',
        'sameunits!', 'autolength!',
        'ticklabeloffset=f', 'ticksshiftouter', 'polylinew=f', 'framelinew=f',
        'frame!',
        'keylinew=f',        'keyexpraise=f',
        'ticklength=f', 'tickfontscale=f', 'keyfontscale=f',
        'whitebox!',

        #   'titlefontscale=f',
        'axisfontscale=f', 'exponentfontscale=f',
        'ticklinew=f', 'axislinew=f', 'xmin=s',   'xmax=s',
        'ymin=s',      'ymax=s',      'ylabel=s', 'rotylabel!',
        'polyborder!', 'cmgray',      'cmsaturation:f',
        'cmbrightness:f'
    );

    @Optlist = ( @Optlist_non_interactive, @Optlist_setable );
    @OptlistShow = @Optlist;
    foreach (@OptlistShow) { s/[\=\:\!].?// }

    # tab completion with 'show'
    @Optlistnames_show = ( @Optlist_non_interactive, @Optlist_setable );
    foreach (@Optlistnames_show) { s/[\:\=\!].?// }    # strip type symbols

    # tab completion with 'set'
    @Optlistnames_set = @Optlist_setable;
    foreach (@Optlistnames_set) { s/[\:\=\!].?// }     # strip type symbols

    my @optlist2 = ( 'generatetest', 'test' );

    # Should change this implementation, But actually OptHandlers is close
    # to good enough as is.
    # Have a structure here that has option names as keys,
    # eg axis , explim. The structure says: whether a noaxis command
    # should be contstructed. which variables are affected, what their
    # data type is, etc. a help string. possibly call backs.
    # Whether this option should showup in 'set' completion list, etc.
    # The list of variables can be extracted from
    # this. There may need another structure for some things that don't
    # fit in this. There might be a flag to say that this option should
    # be promoted to a command in interactive mode, rather than used
    # via 'set'. Almost all information for setting and showing the variables
    # and using them in commands would be contained in this structure.
    # Routines would then build various data structures from this one.

# Handlers:
# VAR is the variable to set
# OPTVAL => 1 means set from the argument given by user
# VAL means no argument, just set a value given in the handler
# VALTYPE eq 'string' forces quotes around the arg before eval'ing
# POSTSUB is a routine to do further processing, update quantities depending on VAR
# DOUNDEF: if no argument is given then variable is set to undef
    our %OptHandlers = (
        verbose  => { VAR => 'Verbose',      VAL => 1, VALTYPE => 'bool' },
        display  => { VAR => 'Display',      VAL => 1, VALTYPE => 'bool' },
        readline  => { VAR => 'UseReadline',  VAL => 1, VALTYPE => 'bool' },
        whitebox => { VAR => 'WhiteBoxDraw', VAL => 1, VALTYPE => 'bool' },
        cmhue  => { VAR => 'ColorMap', VAL => '"hue"',  VALTYPE => 'scalar' },
        cmgray => { VAR => 'ColorMap', VAL => '"gray"', VALTYPE => 'scalar' },
        cmsaturation => [
            { VAR => 'ColorMap', VAL => '"saturation"', VALTYPE => 'scalar' },
            { VAR => 'Hue', OPTVAL => 1, OPTDEFAULT => '$Hue' }
        ],    # trick to leave Hue unchanged
        cmbrightness => [
            { VAR => 'ColorMap', VAL => '"brightness"', VALTYPE => 'scalar' },
            { VAR => 'Hue', OPTVAL => 1, OPTDEFAULT => '$Hue' }
        ],
        cmsatbright => [
            { VAR => 'ColorMap', VAL => '"satbright"', VALTYPE => 'scalar' },
            { VAR => 'Hue', OPTVAL => 1, OPTDEFAULT => '$Hue' }
        ],
        numberpoly => { VAR => 'NumberPoly', VAL => 1, VALTYPE => 'bool' },
        autolength => { VAR => 'AutoLength', VAL => 1, VALTYPE => 'bool' },
        landscape  => { VAR => 'LandScape',  VAL => 1, VALTYPE => 'bool' },
        portrait   => { VAR => 'LandScape',  VAL => 0, VALTYPE => 'bool' },
        polyborder => { VAR => 'PolyBorder', VAL => 1, VALTYPE => 'bool' },
        axis       => [
            { VAR => 'XAxis', VAL => 1, VALTYPE => 'bool' },
            { VAR => 'YAxis', VAL => 1, VALTYPE => 'bool' }
        ],
        noaxis => [
            { VAR => 'XAxis', VAL => 0, VALTYPE => 'bool' },
            { VAR => 'YAxis', VAL => 0, VALTYPE => 'bool' }
        ],
        square => [
            {
                VAR => 'NumberOfSides',
                VAL => 4,
            },
            { VAR => 'LengthOfSide', VAL => 1 },
            { VAR => 'Rotation',     VAL => '0' }
        ],
        tri => [
            { VAR => 'NumberOfSides', VAL => 6 },
            { VAR => 'LengthOfSide',  VAL => '1/sqrt(3)' },
            { VAR => 'Rotation',      VAL => '30' },
            { VAR => 'SameUnits',     VAL => 1 },
        ],
        circle => [
            { VAR => 'NumberOfSides', VAL => 0 },
            { VAR => 'LengthOfSide',  VAL => '1/2' },
            { VAR => 'Rotation',      VAL => '0' },
            { VAR => 'SameUnits',     VAL => 1 }
        ],
        sameunits   => { VAR => 'SameUnits', VAL => 1, VALTYPE => 'bool' },
        viewerscale => {
            VAR     => 'ViewerScale',
            OPTVAL  => 1,
            VALTYPE => 'scalar',
            CHK     => 'posfloat'
        },
        xaxis   => { VAR => 'XAxis',      VAL => 1, VALTYPE => 'bool' },
        yaxis   => { VAR => 'YAxis',      VAL => 1, VALTYPE => 'bool' },
        ticksb  => { VAR => 'BTickDraw',      VAL => 1, VALTYPE => 'bool' },
        tickst  => { VAR => 'TTickDraw',      VAL => 1, VALTYPE => 'bool' },
        ticksl  => { VAR => 'LTickDraw',      VAL => 1, VALTYPE => 'bool' },
        ticksr  => { VAR => 'RTickDraw',      VAL => 1, VALTYPE => 'bool' },

	ticks => [
	    { VAR => 'BTickDraw',      VAL => 1, VALTYPE => 'bool' },
	    { VAR => 'TTickDraw',      VAL => 1, VALTYPE => 'bool' },
	    { VAR => 'LTickDraw',      VAL => 1, VALTYPE => 'bool' },
	     { VAR => 'RTickDraw',      VAL => 1, VALTYPE => 'bool' },
         ],

        lattice => { VAR => 'TriHexDraw', VAL => 1, VALTYPE => 'bool' },
        key     => {
            VAR     => 'DrawKey',
            VAL     => 1,
            VALTYPE => 'bool',
        },
        keywidth => {
            VAR    => 'KeyWidth',
            OPTVAL => 1,
            CHK    => 'posfloat1',
        },
        keyheight   => { VAR => 'KeyHeight',   OPTVAL => 1, CHK => 'posfloat' },
        keyxoffset  => { VAR => 'KeyXOffset',  OPTVAL => 1, CHK => 'float' },
        keyyoffset  => { VAR => 'KeyYOffset',  OPTVAL => 1, CHK => 'float' },
        keyexpraise => { VAR => 'KeyExpRaise', OPTVAL => 1, CHK => 'float' },
        aspectratio => { VAR => 'AspectRatio', OPTVAL => 1, CHK => 'posfloat' },

        #	 'keywidth:f','keyheight:f','keyxoffset:f','keyyoffset:f'
        showraw  => { VAR => 'ShowNormalized', VAL => 0, VALTYPE => 'bool' },
        shownorm => { VAR => 'ShowNormalized', VAL => 1, VALTYPE => 'bool' },
        latexnumbers => { VAR => 'LatexNumbers', VAL => 1, VALTYPE => 'bool' },
        latexrun     => { VAR => 'LatexRun',     VAL => 1, VALTYPE => 'bool' },
        dotfortimes  => { VAR => 'DotForTimes',  VAL => 1, VALTYPE => 'bool' },
        pdf          => {
            VAR     => 'PSFormat',
            VAL     => '"pdf"',
            VALTYPE => 'scalar',
            POSTSUB => \&change_ps_suffix
        },
        eps => {
            VAR     => 'PSFormat',
            VAL     => '"eps"',
            VALTYPE => 'scalar',
            POSTSUB => \&change_ps_suffix
        },
        ps => {
            VAR     => 'PSFormat',
            VAL     => '"ps"',
            VALTYPE => 'scalar',
            POSTSUB => \&change_ps_suffix
        },
        usepower =>
          { VAR => 'DataNorming', VAL => '"power"', VALTYPE => 'scalar' },
        explim => {
            VAR     => 'ExponentLimit',
            OPTVAL  => 1,
            VALTYPE => 'scalar',
            CHK     => 'nonnegint',
        },
        keydigits => {
            VAR     => 'KeyDigits',
            OPTVAL  => 1,
            VALTYPE => 'scalar',
            CHK     => 'posint',
        },
        uselinear =>
          { VAR => 'DataNorming', VAL => '"linear"', VALTYPE => 'scalar' },
        plotwidth => {
            VAR    => 'PlotWidth',
            OPTVAL => 1,
            UNIT   => 'centimeters',
            CHK    => 'posfloat'
        },
        title => { VAR => 'Title', OPTVAL => 1, VALTYPE => 'string' },
        titleyoffset => { VAR => 'TitleYOffset', OPTVAL => 1, CHK => 'float' },
        titlexoffset => { VAR => 'TitleXOffset', OPTVAL => 1, CHK => 'float' },
        xlabel => { VAR => 'XLabel', OPTVAL => 1, VALTYPE => 'string' },
        ylabel => { VAR => 'YLabel', OPTVAL => 1, VALTYPE => 'string' },
        rotylabel => { VAR => 'RotateYLabel', VAL => 1, VALTYPE => 'bool' },
        xlabelxoffset =>
          { VAR => 'XLabelXOffset', OPTVAL => 1, CHK => 'float' },
        xlabelyoffset =>
          { VAR => 'XLabelYOffset', OPTVAL => 1, CHK => 'float' },
        ylabelyoffset =>
          { VAR => 'YLabelYOffset', OPTVAL => 1, CHK => 'float' },
        ylabelxoffset =>
          { VAR => 'YLabelXOffset', OPTVAL => 1, CHK => 'float' },
        sidelength => { VAR => 'LengthOfSide', OPTVAL => 1, CHK => 'posfloat' }
        ,    # this may be overwritten by square and tri. fix it
        xsidelength =>
          { VAR => 'XLengthOfSide', OPTVAL => 1, CHK => 'posfloat' },
        ysidelength =>
          { VAR => 'YLengthOfSide', OPTVAL => 1, CHK => 'posfloat' },
        saturation => { VAR => 'Saturation', OPTVAL => 1, CHK => 'posfloat1' },
        brightness => { VAR => 'Brightness', OPTVAL => 1, CHK => 'posfloat1' },
        hue        => { VAR => 'Hue',        OPTVAL => 1, CHK => 'posfloat1' },
        xbuf       => {
            VAR     => 'Xbuf',
            OPTVAL  => 1,
            UNIT    => 'times plot width',
            CHK     => 'float',
            POSTSUB => \&compute_buffers_on_frame
        },
        ybuf => {
            VAR     => 'Ybuf',
            OPTVAL  => 1,
            UNIT    => 'times plot height',
            CHK     => 'float',
            POSTSUB => \&compute_buffers_on_frame
        },
        buf => [
            {
                VAR    => 'Xbuf',
                OPTVAL => 1,
                UNIT   => 'times plot width',
                CHK    => 'float'
            },
            {
                VAR     => 'Ybuf',
                OPTVAL  => 1,
                UNIT    => 'times plot height',
                CHK     => 'float',
                POSTSUB => \&compute_buffers_on_frame
            }
        ],
        keynbars     => { VAR => 'NumKeyBars',   OPTVAL => 1, CHK => 'posint' },
        keylabelskip => { VAR => 'KeyLabelSkip', OPTVAL => 1, CHK => 'posint' },
        cmhi => { VAR => 'ColorMapHi', OPTVAL => 1, CHK => 'posfloat1' },
        cmlo => { VAR => 'ColorMapLo', OPTVAL => 1, CHK => 'posfloat1' },
        latticegray =>
          { VAR => 'LatticeGray', OPTVAL => 1, CHK => 'posfloat1' },
        power =>
          { VAR => 'DataTransformPower', OPTVAL => 1, CHK => 'posfloat1' },
        outfile   => { VAR => 'Outfile',   OPTVAL => 1, VALTYPE => 'string' },
        infile   => { VAR => 'Infile',   OPTVAL => 1, VALTYPE => 'string', GUI => 'inputfile' },
        fontscale => { VAR => 'FontScale', OPTVAL => 1, CHK     => 'posfloat' },
        bbpad     => {
            VAR    => 'BoundingBoxPad',
            OPTVAL => 1,
            UNIT   => 'PostScript points',
            CHK    => 'float'
        },
        xmin      => { VAR => 'Xmin',      OPTVAL => 1, DOUNDEF => 1 },
        ymin      => { VAR => 'Ymin',      OPTVAL => 1, DOUNDEF => 1 },
        xmax      => { VAR => 'Xmax',      OPTVAL => 1, DOUNDEF => 1 },
        ymax      => { VAR => 'Ymax',      OPTVAL => 1, DOUNDEF => 1 },
        subscale  => { VAR => 'Subscale',  OPTVAL => 1, CHK     => 'posfloat' },
        supscale  => { VAR => 'Supscale',  OPTVAL => 1, CHK     => 'posfloat' },
        ssupscale => { VAR => 'SSupscale', OPTVAL => 1, CHK     => 'posfloat' },
        ticklabeloffset =>
          { VAR => 'TickLabelOffset', OPTVAL => 1, CHK => 'float' },
        polylinew =>
          { VAR => 'PolyLineWScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        framelinew =>
          { VAR => 'FrameLineWScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        frame =>
          { VAR => 'FrameDraw',  VAL => 1, VALTYPE => 'bool' },
        keylinew =>
          { VAR => 'KeyLineWScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        axislinew =>
          { VAR => 'AxisLineWScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        ticklinew =>
          { VAR => 'TickLineWScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        ticklength =>
          { VAR => 'TickLengthScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        tickfontscale =>
          { VAR => 'TickFontScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        ticksshiftouter =>
          { VAR => 'TicksShiftOuter', VAL => 1, VALTYPE => 'bool' },
        keyfontscale =>
          { VAR => 'KeyFontScale', OPTVAL => 1, CHK => 'nonnegfloat' },

   #	titlefontscale =>{VAR => 'TitleFontScale', OPTVAL => 1,CHK=>'nonnegfloat'},
        axisfontscale =>
          { VAR => 'AxisFontScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        numberpolyfontscale =>
          { VAR => 'NumberPolyFontScale', OPTVAL => 1, CHK => 'nonnegfloat' },
        exponentfontscale => {
            VAR    => 'ExponentScale',
            OPTVAL => 1,
            CHK    => 'nonnegfloat',
         },
        grided => [
            { VAR => 'GridDataFile', VAL => 1, VALTYPE => 'bool' },
            { VAR => 'AutoLength',   VAL => 0, VALTYPE => 'bool' }
        ],
        autodata => 
	      { VAR => 'DetectDataFormat' , VAL => 1, VALTYPE => 'bool' },
        viewerpid => { VAR => 'ViewerPid', OPTVAL => 1 },
        font      => {
            VAR     => 'Font',
            OPTVAL  => 1,
            VALTYPE => 'string',
            SETSUB  => \&choose_font_names
        },
        batch =>  {
            VAR => 'BatchFile',
            OPTVAL  => 1,
            VALTYPE => 'string',
#            SHOWSUB => sub {},
        },
        viewer => {
            VAR     => 'Viewer',
            OPTVAL  => 1,
            VALTYPE => 'string',
            CHK => [ ['xpdf', 'gv'] , 'pdf viewer program'],
#            SETSUB  => \&choose_viewer
        },
        mark => {
            VAR     => 'Marks',
            VARTYPE => 'hash',
            VALTYPE => 'string',
            SETSUB  => sub {
                my ($argst) = @_;
                my (@args) = split( ' ', $argst );
                my $markname;
                if ( $args[0] eq 'n' ) {
                    shift(@args);
                    $markname = shift(@args);
                }
                if ( @args == 0 ) {    # delete mark
                    if ( exists $Marks{$markname} ) {
                        delete $Marks{$markname};
                        return;
                    }
                }
                my ( $x, $y ) = @args if @args == 2;
                if ( not defined $markname ) {
                    my @mnames = sort { $a <=> $b } keys %Marks;
                    my $n = @mnames;
                    $markname = 1;
                    $markname = $mnames[ $n - 1 ] + 1 if $n > 0;
                }
                if ( not exists $Marks{$markname} ) {
                    my $nm = {};
                    $nm->{X}          = $x;
                    $nm->{Y}          = $y;
                    $nm->{SIZE}       = 0.005;
                    $Marks{$markname} = $nm;
                }
            },
            SHOWSUB => sub {
                $Data::Dumper::Terse = 1;
                my @mnames = sort { $a <=> $b } keys %Marks;
                foreach my $name (@mnames) {
                    print "Mark number $name: " . Dumper( $Marks{$name} );
                }
                $Data::Dumper::Terse = undef;
              }
        }
    );    # end our %OptHandlers = (

    our @HelpTopics;
    our %HelpInteractive;
    our @BoolVars;
    our %BoolVarList;

# Only some command completions are handled this way. Those that can
# be done automatically from a list of string values  in the OptsHandlers hash
    our %CommandCompletions = ();
    sub setup_command_completion {
	foreach my $okey ( keys %OptHandlers ) {
	    my $hand = $OptHandlers{$okey};    #
	    $hand = $hand->[0] if ref($hand) eq 'ARRAY';
 	    if ( exists $hand->{VALTYPE} and $hand->{VALTYPE} eq 'string' and exists
                 $hand->{CHK} ) {
#		deb( "Setting up '$okey'");
		$CommandCompletions{$okey} = $hand->{CHK}->[0];
	    }
	}
    }


   sub convert_pod_fragment_to_text {
       my ($string_fragment) = @_;
       my $ostr;
       my $parser = Pod::Simple::Text->new();
       $parser->output_string( \$ostr );
       my $docs = "=head1\n" . $string_fragment . "\n";
       $parser->parse_string_document($docs);
       $parser = undef;
       return $ostr;
   }

# note that the followin relies on a particular format of the pod
# documentation, which I have not documented. But edit the pod
# doc carefully!
# Thus far, only options from the pod doc are entered here. (and 
# whether to use set , show, or a command is sometimes muddled)
    sub setup_interactive_help {
	my ($fh,$line,$option);
	%HelpInteractive = ();
	my $res = open $fh, '<', $ScriptName;
	return unless $res;
	my $help_type = '';
	while ($line = <$fh>) {
	    if ( $line =~ /^\=for trihelp (\w+) start/) {
		$help_type = $1;
#		print $help_type,"\n";
		$option = '';
		next;
	    }
	    if ( $help_type ne '' and $line =~ /^\=for trihelp $help_type stop/) {
		$help_type = '';
#		print "stopping\n";
		next;
	    }
	    if ($help_type eq 'options' or $help_type eq 'commands' ) {
		$line =~ s/B<-/B</g if $help_type eq 'options';
		if ($line =~ /^\s*$/ and $help_type eq 'options' ) {
		    if ($option ne '' ) {
			$HelpInteractive{$option} = convert_pod_fragment_to_text($HelpInteractive{$option});
		    }
		    $option = '';
		    next;
		}
		if ($line =~ /^B<([^>]+)/ and $help_type eq 'options') {
		    $option = $1;
		    $line =~ s/B<no$option>//; # remove boolean negation option
		    my $comf = FALSE;
		    foreach ( qw( listcolors findcolors listfonts listsymbols
                              html man ex ) ){
			if( $option eq $_ ) { $comf = TRUE ;last}
		    }
		    if ($comf == TRUE) {
		        $line = '[command] ' . $line . ' : ';
		    }
		    else {
			my $us = '';
			$us = ' (unset) ' if (exists $BoolVarList{$option} );
			$line = "[option] set $us" . $line . ' : ';
		    }
		}
		if ($line =~ /^=item B<([^>]+)>/ and $help_type eq 'commands') {
		    if ($option ne '' ) {
			$HelpInteractive{$option} = convert_pod_fragment_to_text($HelpInteractive{$option});
		    }
		    <$fh>;
		    $option = $1;
		    $line =~ s/=item//;
		    $line = '[command] ' . $line . ' : ';
		}
		if ($option ne '' ) {
		    $HelpInteractive{$option} = '' unless exists $HelpInteractive{$option};
		    $HelpInteractive{$option} .= $line;
		}
	    }
	    
	}
	close($fh);
#	print Dumper(\%HelpInteractive);
    }


    foreach my $okey ( keys %OptHandlers ) {
        my $hand = $OptHandlers{$okey};    
        $hand = [$hand]
          unless ref($hand) eq 'ARRAY';    # put single handler in an array
        foreach my $h (@$hand) {
            push( @HelpTopics, $okey ) if exists $h->{HELP};
	    if (exists $h->{VALTYPE} and $h->{VALTYPE} eq 'bool') {
		push( @BoolVars, $okey );
		$BoolVarList{$okey} = 1;
	    }
        }
    }
    
    # save most parameters to a file
    sub dump_parameters {
        my ($fname) = @_;
        $fname = 'save.tridens' unless defined $fname and not $fname =~ /^\s*$/;
        my $hands = \%OptHandlers;
        my @okeys = keys %$hands;
        my %v;
        my ( @vals, @names );
        my (%seen);
        foreach my $key (@okeys) {

            #	deb("doing '$key'");
            my $opt = $hands->{$key};
            $opt = [$opt] unless ref($opt) eq 'ARRAY';
            foreach my $h (@$opt) {
                if ( exists $h->{VAR} ) {
                    my $var = $h->{VAR};

                    #		my $st = '$v{' . $var . '} = $' . $var;
                    #		deb($st);
                    #		eval $st;
                    if ( not defined $seen{$var} ) {
                        my $val;
                        if ( exists $h->{VARTYPE} ) {
                            $val = eval '\%' . $var if $h->{VARTYPE} eq 'hash';
                        }
                        else {
                            $val = eval '$' . $var;
                        }
                        push @vals,  $val;
                        push @names, '*' . $var;
                        $seen{$var} = 1;
                    }
                }
            }
        }
        open OHAND, ">$fname" or die "Can't save tridens state";
        print OHAND "# tridens saved state\n";
        print OHAND Data::Dumper->Dump( \@vals, \@names );
        print OHAND "1\n";
        close(OHAND);
    }

    sub load_parameters {
        my ($fname) = @_;
        $fname = 'save.tridens' unless defined $fname and not $fname =~ /^\s*$/;
        do $fname;
        choose_font_names($Font) if defined $Font;
    }

    # print all parameters, optionally, those matching $pat
    sub print_all_parameters {
        my ($pat) = @_;
        chomp($pat);
        my @okeys = keys %OptHandlers;
        my %invopt;
        foreach my $okey (@okeys) {    # make inverted hash of OptHandlers vars
            my $hand = $OptHandlers{$okey};   # h is the handler for option $key
            $hand = [$hand]
              unless ref($hand) eq 'ARRAY';    # put single handler in an array
            foreach my $h (@$hand) {
                next unless exists $h->{VAR};
                my $var = $h->{VAR};
                $invopt{$var} = {} unless exists $invopt{$var};
                foreach my $vkey ( keys %{$h} ) {    # copy the hash
                    $invopt{$var}->{$vkey} = $h->{$vkey};
                }
                $invopt{$var}->{OPTS} = []
                  unless exists $invopt{$var}
                      ->{OPTS};    # put all options setting this var in hash
                push @{ $invopt{$var}->{OPTS} }, $okey;
            }
        }
        foreach my $key ( sort keys %invopt ) {
            my $h      = $invopt{$key};
            my $optstr = join( ",", @{ $h->{OPTS} } );
            my $flag  = FALSE;
            if ( defined $pat and $pat ne '' ) {
                $flag = TRUE unless $optstr =~ /$pat/i or $h->{VAR} =~ /$pat/i;
            }
            next if $flag == TRUE;
            print "$optstr: ";
            if ( exists $h->{VAL} or exists $h->{OPTVAL} ) {    # get var
                if ( exists $h->{VALTYPE} and $h->{VALTYPE} eq 'bool' ) {
                    my $s = 'TRUE';
                    $s = 'FALSE' if eval( '$' . $h->{VAR} ) == 0;
                    print $h->{VAR} . " = $s\n";
                }
                else {
                    my $s = eval( '$' . $h->{VAR} );
                    $s = 'undefined' unless defined $s;
                    $s = "'$s'"
                      if exists $h->{VALTYPE} and $h->{VALTYPE} eq 'string';
                    print $h->{VAR} . " = $s";
                    print " " . $h->{UNIT} if exists $h->{UNIT};
                    print "\n";
                    $s = eval( '$' . $h->{VAR} );
                }
            }
        }
    } # end  sub print_all_parameters { ...

    our %CheckSubs = (
        'posfloat'    => \&is_posfloat,
        'posfloat1'   => \&is_posfloat1,
        'float'       => \&is_float,
        'int'         => \&is_int,
        'posint'      => \&is_posint,
        'nonnegint'   => \&is_nonnegint,
        'nonnegfloat' => \&is_nonnegfloat,
    );

    our %CheckNames = (
        'posfloat' => 'a positive floating point (including integers) number',
        'posfloat1' =>
          'a positive floating point number less than or equal to 1',
        'float'       => 'a floating point number',
        'int'         => 'an integer number',
        'posint'      => 'an positive integer number',
        'nonnegint'   => 'a non-negative integer number',
        'nonnegfloat' => 'a non-negative floating point number'
    );

# $h is entire option hash for a single option
# $val is value that user is attempting to set
    sub check_value_type {
        my ( $val, $h ) = @_;
        return $val unless exists $h->{CHK};
	my ($code,$res);
	if ( exists $h->{VALTYPE} and $h->{VALTYPE} eq 'string' and 
	   ref($h->{CHK}) eq 'ARRAY'  ) {
	    my $legal_args = $h->{CHK}->[0];
	    my $msg = $h->{CHK}->[1];
	    $res = check_string_args($val,$legal_args,$msg);
	    return $res;
	}
	else {
	    $code = $CheckSubs{ $h->{CHK} };
	}
        $res  = &$code($val);
        if ( not defined $res ) {
            herror(
                $h->{VAR} . " must be a " . $CheckNames{ $h->{CHK} } . "." );
            return undef;
        }
        return $val;
    }

    #This is from the perl cookbook.
    # It converts a string to a floating point number,
    # or returns undef on failure.
    sub to_float {
        my $str = shift;
        $str =~ s/^\s+//;
        $str =~ s/\s+$//;

        #    deb("to_float $str");
        $! = 0;
        my ( $num, $unparsed ) = strtod($str);
        if ( ( $str eq '' ) || ( $unparsed != 0 ) || $! ) {
            return;
        }
        else {
            return $num;
        }
    }

    sub is_posfloat {
        my $x = shift;
        $x = to_float($x);
        return if not defined $x;
        return if $x <= 0;
        return 1;
    }

    sub is_posfloat1 {
        my $x = shift;
        $x = to_float($x);
        return if not defined $x;
        return if $x <= 0;
        return if $x > 1;
        return 1;
    }

    sub is_nonnegfloat {
        my $x = shift;
        $x = to_float($x);
        return if not defined $x;
        return if $x < 0;
        return 1;
    }

    sub is_nonnegint {
        my $x   = shift;
        my $ans = is_integer($x);
        return if not defined $ans;
        return if $x < 0;
        return 1;
    }

    sub is_float {
        my $x = shift;
        $x = to_float($x);
        return if not defined $x;
        return 1;
    }

    sub is_posint {
        my $x   = shift;
        my $ans = is_integer($x);
        return if not defined $ans;
        return if $x <= 0;
        return 1;
    }

    # return 1 if number is an integer,
    # undef, otherwise.
    # don't accept leading zeroes
    sub is_integer {
        my $num = shift;
        $num =~ s/^\s+//;
        $num =~ s/\s+$//;
        return 1 if $num eq '0';
        return undef if $num =~ /^[+-]?0/;
        return 1     if $num =~ /^[+-]?\d+$/;
        return undef;
    }

    # set this to FALSE for getting opts, true for setting.
    our $SettingOpts = TRUE;
    my %h = ( 'v' => \$Verbose );    # hash for options
    GetOptions( \%h, ( @Optlist, @optlist2 ) );

    # input data file name from command line
    # other arguments are  already taken by GetOptions()
    $Infile = $ARGV[0];
    initialize();
    process_command_line_options( \%h );
    first_process_command_line_options( \%h );

    # process command line options via handlers. the next routine , process_
    # does the remaining options by hand.
    # %opth is hash of options and values given by user
    # find the handler her for each one.
    sub first_process_command_line_options {
        my ( $setflags, $opth ) = @_;
        if ( not defined $opth ) {
            $opth = $setflags;
            $setflags = { SET => 1 }

        }
        foreach my $key ( keys %$opth ) {
            next unless exists $OptHandlers{$key};
            my $hand = $OptHandlers{$key};    # h is the handler for option $key
            $hand = [$hand]
              unless ref($hand) eq 'ARRAY';    # put single handler in an array
            foreach my $h (@$hand) {
                if ( exists $h->{VAR} ) {
                    my $var = $h->{VAR};
                    if (    exists $setflags->{UNSET}
                        and exists $h->{VALTYPE}
                        and $h->{VALTYPE} ne 'bool' )
                    {
                        herror("Can't unset '$key'");
                        return;
                    }
                    if ( $SettingOpts == TRUE ) {

                        #  print Dumper($opth);
                        if ( exists $h->{VAL} ) {    # set variable
                            my $val = $h->{VAL};
                            if (    exists $h->{VALTYPE}
                                and $h->{VALTYPE} eq 'bool'
                                and $opth->{$key} == 0 )
                            {                        # negation ! on commandline
                                $val = 1 - $val;
                            }
                            if ( exists $setflags->{UNSET} ) {
                                $val = 1 - $val;
                            }
                            my $setst = '$' . $var . " = " . $val;
                            eval $setst;
                        }
                        elsif ( exists $h->{OPTVAL} ) {    # set variable
                             # actually, font name, viewer namem, etc could be handled
                             # through check val
                            if ( exists $h->{SETSUB} ) {    # handled specially
                                &{ $h->{SETSUB} }( $opth->{$key} );
                                next;
                            }
                            my $oval = $opth->{$key};
			    $oval = check_value_type( $oval, $h );
                            next unless defined $oval;
                            $oval = "'$oval'"
                              if defined $h->{VALTYPE}
                                  and $h->{VALTYPE} eq 'string';
                            if ( exists $h->{DOUNDEF} )
                            {    # no arg undefines value
                                $oval = 'undef' if $oval =~ /^\s*$/;
                            }
                            if ( exists $h->{OPTDEFAULT}
                                and $opth->{$key} eq '' )
                            {
                                $oval = $h->{OPTDEFAULT};
                            }
                            my $setst = '$' . $var . " = " . $oval;
                            eval $setst;
                        }
                        if ( exists $h->{POSTSUB} ) {
                            &{ $h->{POSTSUB} }( $opth->{$key} );
                        }
                    }
                    else {    # showing: so return value
                        if ( exists $h->{SHOWSUB} ) {
                            &{ $h->{SHOWSUB} };
                            next;
                        }
                        if ( exists $h->{VAL} or exists $h->{OPTVAL} )
                        {     # get var
                            if ( exists $h->{VALTYPE}
                                and $h->{VALTYPE} eq 'bool' )
                            {
                                my $s = 'TRUE';
                                $s = 'FALSE' if eval( '$' . $var ) == 0;
                                print $var . " = $s\n";
                            }
                            else {
                                my $s = eval( '$' . $var );
                                $s = 'undefined' unless defined $s;
                                $s = "'$s'"
                                  if exists $h->{VALTYPE}
                                      and $h->{VALTYPE} eq 'string';
                                print $var . " = $s";
                                print " " . $h->{UNIT} if exists $h->{UNIT};
                                print "\n";
#                                $s = eval( '$' . $var );
#                                deb "on exit $s";
                            }
                        }
                    }
                }    #  if (exists $h->{VAR})
                else {
                    if ( $SettingOpts == TRUE ) {
                        if ( exists $h->{SETSUB} ) {
                            &{ $h->{SETSUB} }( $opth->{$key} );
                        }
                    }
                }
            }
        }
    }

    sub print_codes_columns {
        my ( $codes, $n ) = @_;
        for ( my $i = 0 ; $i < @$codes ; $i++ ) {
            print $codes->[$i];
            if   ( $i % $n == $n - 1 ) { print "\n" unless $i == @$codes - 1; }
            else                       { print ", " unless $i == @$codes - 1; }
        }
        print "\n";
    }

    sub process_command_line_options {
        my ( $h, $setflags ) = @_;
        verbose "processing command line options";
        if ( exists $h->{h} ) {
            show_short_help();
        }
        if ( exists $h->{generatetest} ) {
            setup_example_plots();
            run_tests(1);
        }
        if ( exists $h->{test} ) { setup_example_plots(); run_tests(0); }
        if ( exists $h->{version} ) {
            print "tridens $VERSION\n";
            iexit(0);
        }
        if ( exists $h->{man} ) {
            show_man_page();
        }
        if ( exists $h->{mandoc} ) {
            my $res = `pod2man --help 2>&1 `;
            if ( defined $res and $res =~ /Usage/ ) {
                verbosesys "pod2man  $ScriptName tridens.1";
                iexit(0);
            }
            else {
                print STDERR
		    "Can't find helper program pod2man (broken perl installation?)\n";
                iexit(0);
            }
        }
        if ( exists $h->{textdoc} ) {
            my $res = `pod2text --help 2>&1 `;
            if ( defined $res and $res =~ /Usage/ ) {
                verbosesys "pod2text $ScriptName ";
                iexit(0);
            }
            else {
                print STDERR
		    "Can't find helper program pod2man (broken perl installation?)\n";
                iexit(0);
            }
        }
        if ( exists $h->{htmldoc} ) {
            my $res = `pod2html --help 2>&1 `;
            if ( defined $res and $res =~ /Usage/ ) {
                verbosesys "pod2html --outfile=tridens.html  $ScriptName ";
                iexit(0);
            }
            else {
                print STDERR
		    "Can't find helper program pod2html (broken perl installation?)\n";
                iexit(0);
            }
        }
        if ( exists $h->{pdfdoc} ) {
            my $res = `pod2latex --help 2>&1 `;
            if ( defined $res and $res =~ /Usage/ ) {
                verbosesys "pod2latex -full  $ScriptName ";
                verbosesys "$PdfLatex -full  $ScriptName.tex ";
                iexit(0);
            }
            else {
                print STDERR
		    "Can't find helper program pod2latex (broken perl installation?)\n";
                iexit(0);
            }
        }
        if ( exists $h->{html} ) {
            show_html_page();
        }
        if ( exists $h->{paramfile} ) {
            verbose("Writing parameter file '$Initfilename'");
            open( OSTHAND, ">$Initfilename" )
              or die "Can't open '$Initfilename' for writing.";
            print OSTHAND parameter_prolog(), $ParameterList;
            iexit(0);
        }
        if ( exists $h->{listcolors} ) {
            setup_rgb_codes();
            my $n = 4;
            $n = $h->{listcolors}
              if $h->{listcolors} ne '' and $h->{listcolors} > 0;
            print_codes_columns( \@RgbNames, $n );
            iexit(0);
        }
        if ( exists $h->{listfonts} ) {
            print_codes_columns( [ keys %FontList ], 4 );
            iexit(0);
        }
        if ( exists $h->{listsymbols} ) {
            setup_symcodelist();
            my $n = 4;
            $n = $h->{listsymbols}
              if $h->{listsymbols} ne '' and $h->{listsymbols} > 0;
            print_codes_columns( \@Symcodelist, $n );
            print "\nAliases from Latex to some symbols:\n";
            print_codes_columns( \@Symaliaslist, $n );
            iexit(0);
        }
        if ( exists $h->{findcolors} ) {
            setup_rgb_codes();
            my $n   = 4;
            my $j   = 0;
            my $pat = $h->{findcolors};
            my $st  = '';
            for ( my $i = 0 ; $i < @RgbNames ; $i++ ) {
                my $name = $RgbNames[$i];
                if ( $name =~ /$pat/i ) {
                    $st .= $RgbNames[$i];
                    if   ( $j % $n == $n - 1 ) { $st .= "\n"; }
                    else                       { $st .= ", " }
                    $j++;
                }
            }
            $st =~ s/\,\s*$//;
            $st .= "\n";
            print $st;
            iexit(0);
        }
        if ( exists $h->{hex} ) {    # this is broken
            $NumberOfSides = 3;

            #	$LengthOfSide =   1/(sqrt(3)) unless exists $h->{sidelength};
            #	$LengthOfSide =   sqrt(3)/2 unless exists $h->{sidelength};
            $LengthOfSide = 1.7 unless exists $h->{sidelength};
            $Rotation     = '30';
            $Rotation2    = '210';
        }
        if ( exists $h->{ex} ) {
            $ExampleNumber = $h->{ex};
        }
        if ( exists $h->{demo} ) {
            $DoAllExamples = $h->{demo};
        }
        if ( exists $h->{nodisplay} ) {
            $Display = FALSE;
        }
        if ( exists $h->{i} ) {
            $RunShell = TRUE;
            $Display = TRUE unless exists $h->{nodisplay};
        }
        if ( exists $h->{batch} ) {
            if ($Tridens::SettingOpts == TRUE)  {
                $BatchFile = $h->{batch};
                $RunShell  = TRUE;
            }
        }
        if (
            ( not defined $Infile or $Infile eq '' )
            and not( exists $h->{ex}
                or exists $h->{i}
                or exists $h->{batch}
                or exists $h->{demo}
                or $RunShell == TRUE )
          )
        {
            $RunShell = TRUE;    # now go straight to interactive mode.
            $Display = TRUE;
        }
    }    # end  sub process_command_line_options {
}    # end initialization block

# options that are more complex than most; cannot be used from command line easily
#sub handle_interactive_only

# END Process Commandline Options
#============================================================================

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Routines to set things requested by command line options. Other stuff mixed in     #
#  here.                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#


# parameter_prolog() returns a string containing text to print
# at the head of the parameter file .tridens.
sub parameter_prolog {
    return << "EOPAR";
# Parameter file for tridens. Set parameters here to
# override the default values. If you copy this file to
# datafile.p, where datafile is the name of the input data file,
# and that file will be read and will overwrite values set here.

# typing a comment symbol '#' in front of a line (or deleting it)
# will disable it,  and the corresponding parameter will take its
# default value, or the value set in the parameter file datafile.p

EOPAR
}

# names of output files
our $Psfile;
our $Pdffile;
our $Epsfile;
our $Ipefile;

sub set_output_file_names {
    my $Infile = shift;    # Infile is global, but this is flexible
    $Psfile  = "$Infile.ps";
    $Pdffile = "$Infile.pdf";
    $Epsfile = "$Infile.eps";
    $Ipefile = "$Infile.ipe";
}

# use this if the output format has changed to change the suffix.
sub change_ps_suffix {
    $Outfile =~ s/\.(eps|ps|pdf)$/\.$PSFormat/ if defined $Outfile;
}


# string to redirect stderr to stdout.
# Apparantly perl always invokes a bourne shell, so this works.
our $Getstderr = ' 2>&1 1>/dev/null';

# $Xlo,$Xhi,$Ylo,$Yhi are limits of data set, computed
# on reading. $XBlo,$XBhi,$YBlo,$YBhi are the same with
# a buffers. See read_data() below.
our ( $Xlo,  $Xhi,  $Ylo,  $Yhi );     # 'window' units
our ( $DXlo, $DXhi, $DYlo, $DYhi );    # limits in  physical data units
our ( $XBlo, $XBhi, $YBlo, $YBhi );    # with padding

# a few things that are written at the top of the PostScript file.
our ( $DocTypeLine, $ShowPage, $PaperComments );

######################################

# ps command to switch colors; ps procedure to
# draw polygon; ps procedure for filling polygon
our ( $SetDensityColor, $Polypath, $WhichFill );

# will be computed by gs and then inserted into file on second pass.
our $BoundingBox = '';

our $WhiteBox = '';

# for postscript
our $PageSize      = '';
our $TranslatePlot = '';

sub strip_spaces {
    my ($s) = @_;
    $s =~ s/^\s+//;
    $s =~ s/\s+$//;
    $s;
}

sub show_short_help {

# The following uses a Pod parser to read this script and translate the Pod to
# text. Then blank lines are stripped and only the OPTIONS (between OPTIONS and REQUIREMENTS section
# are printed.
    print $ShortHelp;
    my $outst;
    my $parser = Pod::Simple::Text->new();
    $parser->output_string( \$outst );
    $parser->parse_file($ScriptName);
    my @lines = split( "\n", $outst );
    my $flag = FALSE;

    foreach (@lines) {
        if (/^OPTIONS/) { $flag = TRUE; next; }
        last if /^REQUIREMENT/;
        if ( $flag == TRUE && not /^\s*$/ ) {
            print $_, "\n";
        }
    }
    iexit(0);
}

sub show_man_page {
    my $res = `pod2man --help 2>&1 `;
    if ( defined $res and $res =~ /Usage/ ) {
        verbosesys "pod2man $ScriptName | man -l - ";
        iexit(0);
    }
    else {
        print STDERR
          "Can't find helper program pod2man (broken perl installation?)\n";
        iexit(0);
    }
}

sub show_html_page {
    my $res = `pod2html --help 2>&1 `;
    if ( defined $res and $res =~ /Usage/ ) {
        verbosesys "pod2html --outfile=tridens.html  $ScriptName ";
        verbosesys "$Browser tridens.html&";
        iexit(0);
    }
    else {
        print STDERR
          "Can't find helper program pod2html (broken perl installation?)\n";
        iexit(0);
    }
}

#  initialize()  Read parameters from the files .tridens
#    and infilename.p and eval the perl code therein.
sub initialize {
    if ( -e $Initfilename ) {
        verbose("Reading parameters from '$Initfilename'");
        do $Initfilename;
    }
    else { verbose("Can't find parameter file '$Initfilename'"); }
    if ( defined $Infile ) {
        my $pfile = $Infile . "." . "p";
        if ( -e $pfile ) {
            do $pfile;
            verbose "Reading parameters from '$pfile'";
        }
    }
    $Pi = 4 * atan(1);
    $E  = exp(1.0);
    setup_font_list();
    choose_font_names($Font) if defined $Font;
    check_if_software_is_installed();
    setup_command_completion();
    setup_interactive_help();
}

# don't need GD, its just an example
# Nothing usefule here now. Not a good way to check
# for readline
sub check_if_software_is_installed {
 eval 'require Term::ReadLine';
 if ($@) {

 } else {

 }
}

# set_polygon_params() Some parametes set by the user
# just select a postscript procedure. Do this here.
# The strings that are set here are poscript commands or procedures.
sub set_polygon_params {
    if ( $ColorMap eq 'hue' ) {
        $SetDensityColor = " $Saturation $Brightness sethsbcolor";
    }
    elsif ( $ColorMap eq 'gray' ) {
        $SetDensityColor = "setgray";
    }
    elsif ( $ColorMap eq 'saturation' ) {
        $SetDensityColor = " $Hue exch $Brightness sethsbcolor ";
    }
    elsif ( $ColorMap eq 'brightness' ) {
        $SetDensityColor = " $Hue exch $Saturation exch sethsbcolor ";
    }
    elsif ( $ColorMap eq 'satbright' ) {
        $SetDensityColor = " $Hue exch dup sethsbcolor ";
    }
    if ( $NumberOfSides == 6 ) {
        $Polypath = 'hexpoly';
    }
    elsif ( $NumberOfSides == 3 ) {
        $Polypath = 'trianglepoly';
    }
    elsif ( $NumberOfSides == 4 ) {
        $Polypath = 'squarepoly';

    }
    elsif ( $NumberOfSides == 0 ) {
        $Polypath = 'circlepoly';
    }
    else {
        die "Only polygons with 3,4, or 6 sides are supported.";
    }
    if ( $PolyBorder == TRUE ) {
        $WhichFill = 'polystfill';
    }
    elsif ( $PolyBorder == FALSE ) {
        $WhichFill = 'polyfill';
    }
    else {
        die "\$WhichFill must be set to '0' or '1', not '$WhichFill'";
    }
}    # end sub set_polygon_params {

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Reading data files and analyzing and manipulating data.                            #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#

# this block (context) is for scoping; 'my' variables defined in this block are
# only visible to routines inside.
# Data taking and manipulation context
#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=
{

    # max and min of raw input data
    my ( $max_v, $min_v );

    # arrays containing, x,y,v points from data file.
    # also @b contains data after normalizing and scaling with
    # powers and color functions, etc. @nlin is the data only
    # after the first linear mapping into [0,1].
    # These are all visible to a handful of routines in this block.
    my ( @Xs, @Ys, @V, @b, @nlin );

=begin comment

 read_data():
  input: $file  --  string containing data file name.
  output:  These are not returned, but are set in read_data.
        @Xs, @Ys @V -- arrays contianing triplets of numbers from each
                       line of data file.
        $max_v,$min_v,$Xlo,$Xhi,$Ylo,$Yhi -- max and mins of x,y,v calculate
                    as data file is read.
	$XBlo,$XBhi,$YBlo,$YBhi -- limits that are moved a bit farther apart
                     in order to provide a buffer for the plot frame.

=end comment

=cut

sub data_file_name_set {
    my ($filename) = @_;
    $DataFileInfo{NAME} = $filename;
}

sub data_file_type_set {
    my ($type) = @_;
    $DataFileInfo{TYPE} = $type;
}

sub data_file_nx_set {
    my ($nx) = @_;
    $DataFileInfo{NX} = $nx;
}

sub data_file_ny_set {
    my ($ny) = @_;
    $DataFileInfo{NY} = $ny;
}

sub data_file_nv_set {
    my ($nv) = @_;
    $DataFileInfo{NV} = $nv;
}

sub data_file_info_clear {
    %DataFileInfo = ();
}

sub data_file_info_print {
    my @info = (
	[ 'NAME', 'Input data file name'],
	[ 'TYPE', 'Data format' ],
	[ 'NX', 'Number of x coordinates' ],
	[ 'NY', 'Number of Y coordinates' ],
	[ 'NV', 'Number of z coordinate data values' ],
	);
    my $val;
    foreach my $item (@info) {
	$val = 'unset';
	$val = $DataFileInfo{$item->[0]} if exists $DataFileInfo{$item->[0]};
	print $item->[1] . ': ' . $val . "\n";
    }
}

sub process_data_file_line {
    my ($line) = @_;
    if ( $line =~ /^\s*[\#\;\%\!]/    # skip comments
	 or $line =~ /^\s*$/ ) { # blank lines
	return();
    }
    s/^\s*//;
    chomp($line);
    my @nums = split( /[^\.eE\d\+\-]+/, $line );
    return (undef)  if @nums == 0;
    return (@nums);
}

    # This does the actual reading
    sub read_data_inner {
        my ($file) = @_;    # data filename
        my $i = 0;
        my @nums;           # temp storage for line of numbers.
        @Xs = @Ys = @V = ();
        open INH, "<$file" or herror "Can't open '$file' for reading.";
        while (<INH>) {
            @nums = process_data_file_line($_);
            next unless @nums == 3;
            $Xs[$i] = $nums[0];
            $Ys[$i] = $nums[1];
            $V[$i]  = $nums[2];
            $i++;
        }
        close(INH);
        verbose "read " . ( $#Xs + 1 ) . " data points";
        return 1;
    }

    # This does the actual reading
    sub read_data_inner_grid {
        my ($file) = @_;    # data filename
        my ( $i, $j, $k ) = ( 0, 0, 0 );
        my @nums;           # temp storage for line of numbers.
        @Xs = @Ys = @V = ();

        #    my $lastn=0;
        open INH, "<$file" or herror "Can't open '$file' for reading.";
        while (<INH>) {
	    @nums = process_data_file_line($_);
	    next unless @nums > 0;
            for ( $i = 0 ; $i < @nums ; $i++ ) {
                $Xs[$k] = $i;
                $Ys[$k] = $j;
                $V[$k]  = $nums[$i];
                if ( not defined $V[$k] or $V[$k] eq '' ) {
                    die "$k: not defined";
                }
                $k++;
            }
            $j++;
        }
        close(INH);
        verbose(
            sprintf( "Read %d,%d,%d", scalar(@Xs), scalar(@Ys), scalar(@V) ) );
    }

    sub detect_file_type  {
	my ($file) = @_;    # data filename
	open my $fh, "<$file" or herror "Can't open '$file' for reading.";
	my $type = '';
	my (@nums);
        while (<$fh>) {
	    @nums = process_data_file_line($_);
	    next unless @nums > 0;
	    if ( @nums == 3 ) {
		$type = 'three_col_data';
		last;
	    }
	    if ( @nums > 3 ) {
		$type = 'grided_data';
		last;
	    }
	    $type = 'unknown';
	    last;
	}
	return $type;
    }

    # read data and find min max etc.
    sub read_data {
        my ($file) = @_;    # data filename
	my $file_type;
        if ( not defined $file ) { herror("No input file"); return undef; }
        if ( not -e $file ) {
            herror("Input data file '$file' does not exist.");
            return undef;
        }
        $Infile = $file; # this is assbackwards, but needed for interactive mode
        my $i   = 0;
        my $sum = 0;
        $max_v = undef;
        $min_v = undef;
        my $min_dist  = -1;
        my $xmin_dist = -1;
        my $ymin_dist = -1;
        my $dist;
        @Xs   = @Ys   = @V    = ();
        $XBlo = $XBhi = $YBlo = $YBhi = undef;
        $Xlo  = $Xhi  = $Ylo  = $Yhi = undef;
        $DXlo = $DXhi = $DYlo = $DYhi = undef;

	if ( $DetectDataFormat == TRUE) {
	    $file_type = detect_file_type($file);
#	    deb("got type $file_type");
	    if ($file_type eq 'unknown') {
		herror("Can't read data file '$file'.");
		return;
	    }
	}
        if ( $GridDataFile == TRUE or
	     ($DetectDataFormat == TRUE and $file_type eq 'grided_data'  ) ) {
            read_data_inner_grid($file);
	    $XLengthOfSide=1;
	    $YLengthOfSide=1;
        }
        else {
            if ( not defined read_data_inner($file) ) {
                return undef;
            }
        }
	data_file_info_clear();
	if (@Xs == 0 or @Ys == 0 or @V == 0 ) {
	    herror("Error reading data file. Check options 'autodata' and 'grided'");
	    return;
	}
	data_file_name_set($file);
	data_file_type_set($file_type) if $file_type ne '';
	data_file_nx_set(scalar(@Xs));
	data_file_ny_set(scalar(@Ys));
	data_file_nv_set(scalar(@V));
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            if ( $AutoLength == TRUE and $i != 0 ) {
                if ( $SameUnits == TRUE ) {
                    $dist =
                      ( $Xs[0] - $Xs[$i] ) * ( $Xs[0] - $Xs[$i] ) +
                      ( $Ys[0] - $Ys[$i] ) * ( $Ys[0] - $Ys[$i] );
                    if ( $dist < $min_dist or $min_dist == -1 ) {
                        $min_dist = $dist;
                    }
                }
                else {
                    $dist = abs( $Xs[0] - $Xs[$i] );
                    if ( $dist > 0
                        and ( $dist < $xmin_dist or $xmin_dist == -1 ) )
                    {
                        $xmin_dist = $dist;
                        verbose("setting xmin $dist ->  $xmin_dist at i=$i");
                    }
                    $dist = abs( $Ys[0] - $Ys[$i] );
                    if ( $dist > 0
                        and ( $dist < $ymin_dist or $ymin_dist == -1 ) )
                    {
                        $ymin_dist = $dist;
                    }
                }
            }
            $sum += $V[$i];
            $DXlo = $Xs[$i] if not defined $DXlo;
            $DXhi = $Xs[$i] if not defined $DXhi;
            $DYlo = $Ys[$i] if not defined $DYlo;
            $DYhi = $Ys[$i] if not defined $DYhi;

            $DXlo = $Xs[$i] if $Xs[$i] < $DXlo;
            $DYlo = $Ys[$i] if $Ys[$i] < $DYlo;
            $DXhi = $Xs[$i] if $Xs[$i] > $DXhi;
            $DYhi = $Ys[$i] if $Ys[$i] > $DYhi;

            $max_v = $V[$i] if not defined $max_v;
            $min_v = $V[$i] if not defined $min_v;
            $max_v = $V[$i] if $V[$i] > $max_v;
            $min_v = $V[$i] if $V[$i] < $min_v;
        }
        if ( $SameUnits == TRUE and $min_dist <= 0 ) {
            herror("Can't find distance between points automatically");
            iexit(0);
        }
        verbose("got Xlo=$DXlo, Xhi=$DXhi, Ylo=$DYlo, Yhi=$DYhi");
        if ( $AutoLength == TRUE ) {
            if ( $NumberOfSides == 4 ) {
                if ( $SameUnits == TRUE ) {
                    $LengthOfSide = sqrt($min_dist);
                }
                else {
                    $LengthOfSide  = $xmin_dist;
                    $XLengthOfSide = $xmin_dist;
                    $YLengthOfSide = $ymin_dist;
                    verbose "X Nearest neighbor distance is " . $xmin_dist;
                    verbose "Y Nearest neighbor distance is " . $ymin_dist;
                }
            }
            elsif ( $NumberOfSides == 6 ) {
                $LengthOfSide = sqrt($min_dist) * 1 / sqrt(3);
            }
            elsif ( $NumberOfSides == 0 ) {
                $LengthOfSide = sqrt($min_dist) / 2;
            }
            elsif ( $NumberOfSides == 3 ) {
                $LengthOfSide = sqrt($min_dist) * 1 / sqrt(3);
            }
        }
        if ( $SameUnits == TRUE ) {
            verbose "Nearest neighbor distance is " . sqrt($min_dist);
            $XLengthOfSide = $LengthOfSide;
            $YLengthOfSide = $LengthOfSide;
        }
        verbose "sum of data values $sum";

        # Allow for width of hexes on edge
	# sometimes want this, sometimes not ?
	$DXlo -= $XLengthOfSide/2;
	$DYlo -= $YLengthOfSide/2;
	$DXhi += $XLengthOfSide/2;
	$DYhi += $YLengthOfSide/2;

        # override with  user supplied values if defined.
        $DXlo = $Xmin if defined $Xmin;
        $DYlo = $Ymin if defined $Ymin;
        $DXhi = $Xmax if defined $Xmax;
        $DYhi = $Ymax if defined $Ymax;

        #    $Xlo = $DXlo; remove this stuff soon. just for testing
        #    $Xhi = $DXhi;
        #    $Ylo = $DYlo;
        #    $Yhi = $DYhi;

        set_window_coordinates();
        $HaveData = TRUE;
        verbose "Finished reading data";

        return 1;
    }    # end read_data()

    sub set_window_coordinates {
        $Xlo = 0;
        if ( $SameUnits == TRUE and $NumberOfSides == 6 ) {
            { $Xhi = 2 / sqrt(3); }
        }
        else { $Xhi = $AspectRatio; }
        $Ylo = 0;
        $Yhi = 1;
        compute_buffers_on_frame();
    }

    sub compute_buffers_on_frame {

        # add a bit of a buffer to data plotting area at
        # which frame will be drawn. So positions of text,
        # etc will be drawn relative this expanded rectangle
        if ( defined $Xlo and defined $Xhi ) {
            $XBlo = $Xlo - ( $Xhi - $Xlo ) * $Xbuf;
            $XBhi = $Xhi + ( $Xhi - $Xlo ) * $Xbuf;
        }
        if ( defined $Ylo and defined $Yhi ) {
            $YBlo = $Ylo - ( $Yhi - $Ylo ) * $Ybuf;
            $YBhi = $Yhi + ( $Yhi - $Ylo ) * $Ybuf;
        }
    }

    sub do_norming {
        if (   $DataNorming eq 'linear'
            or $DataTransformPower == TRUE )
        {
            verbose "doing linear norming";
            return norm_linear();
        }
        elsif ( $DataNorming eq 'power' ) {
            verbose "doing power norming";
            return norm_power($DataTransformPower);
        }
        else {
            die '$DataNorming must be set to "linear" or "power"';
        }
    }

    sub norm_linear {
        my ($i);

        #    print "max $max_v, min $min_v\n";
        if ( $max_v == $min_v ) {
            herror( "Zero range in data values!");
	    return FALSE;
        }
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            $b[$i] = ( $V[$i] - $min_v ) / ( $max_v - $min_v );
            $nlin[$i] = $b[$i];
            #	printf("%e\n", $nlin[$i]);
        }
	return TRUE;
    }

    sub inv_norm_linear {
        my $x = shift;
        return ( $max_v - $min_v ) * $x + $min_v;
    }

    sub norm_power {
        my $power = shift;
        my $i;
        norm_linear();
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            $b[$i] = $b[$i]**$power;
        }
	return TRUE;
    }

    sub inv_norm_power {
        my $x = shift;
        return $x**( 1 / $DataTransformPower );
    }

    # hue value goes from 0 to 1. Normalized data goes from
    # 0 to 1 . This is linear map of data into hue range
    # in case we only want some of the color range.
    sub all_scale_transform {
        my $i;
        verbose "Doing linear color transform";
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            $b[$i] = scale_transform( $b[$i] );
        }
    }

    sub scale_transform {
        my $x = shift;
        return $x * ( $ColorMapHi - $ColorMapLo ) + $ColorMapLo;
    }

    sub inv_scale_transform {
        my $x = shift;
        return ( $x - $ColorMapLo ) / ( $ColorMapHi - $ColorMapLo );
    }

    # apparantly not used
    sub norm_log {
        my ( $max_b, $i );
        verbose "norming and taking log of data";
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            $b[$i] = $V[$i] / $max_v;    # normalize
            $b[$i] = -log( $b[$i] );
            $max_b = $b[$i] if not defined $max_b;

            #	$min_b = $b[$i] if not defined $min_b;
            $max_b = $b[$i] if $b[$i] > $max_b;

            #	$min_b = $b[$i] if $b[$i] < $min_b;
        }
        for ( $i = 0 ; $i < @Xs ; $i++ ) {
            $b[$i] /= $max_b;
        }
    }

    #  limits for first space  x1,x2
    #  limits for primed space  xp1,xp2
    # This takes x to xp (x')
    sub coordinate_transform {
        my ( $x, $x1, $x2, $xp1, $xp2 ) = @_;
        return ( $xp1 * ( $x - $x2 ) - $xp2 * ( $x - $x1 ) ) / ( $x1 - $x2 );
    }

    sub data_to_window_transform_x {
        my ($x) = @_;
        return coordinate_transform( $x, $DXlo, $DXhi, $Xlo, $Xhi );
    }

    sub data_to_window_transform_y {
        my ($y) = @_;
        return coordinate_transform( $y, $DYlo, $DYhi, $Ylo, $Yhi );
    }


   # write the postscript commands to draw the polygons covering the plot
    sub make_data_postscript {
         my $i;
         my  $str = '';
         my  ( $x, $y );
        
      #    if ($NumberOfSides == 3) { broken now
      #         for ($i=0;$i<@Xs;$i++) { # plot the data
      #	   if ($i % 2 == 0){  $str .= pshex( $Xs[$i] ,  $Ys[$i], $b[$i]  );}
      #	   else {  $str .= pshex_rot_180( $Xs[$i] ,  $Ys[$i], $b[$i]  );}
      #       }
      #       return $str;
      #   }
      for ( $i = 0 ; $i < @Xs ; $i++ ) {    # plot the data
	  $x = $Xs[$i];
	  $y = $Ys[$i];
	  $x = data_to_window_transform_x($x);
	  $y = data_to_window_transform_y($y);
	  if ( $NumberPoly == TRUE ) {
	      if ( $ShowNormalized == TRUE ) {
		$str .= pshexn( $x, $y, $b[$i], $nlin[$i] );
	      }
	      else {
		  $str .= pshexn( $x, $y, $b[$i], $V[$i] );
	      }
	  }
	  else {
	      $str .= pshex( $x, $y, $b[$i] );
	  }
      }
      return $str;
   }

}    # end  Data taking and manipulation context

#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=


#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Code to generate example or demo plots.                                            #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#

#==========================================================================
# Example generation routines

#{  # begin context

our %example_data = (
    'sq1.dat' => {
        RANGE   => [ -2, 2, .1, -2, 2, .1 ],
        DATFUNC => \&make_print_square_data,
        FUNC    => \&ex_f1
    },
    'tr1.dat' => {
        RANGE   => [ -10, 10, -10, 10, .1 ],
        DATFUNC => \&make_print_triangular_data,
        FUNC    => \&ex_f1
    },
    'hx1.dat' => {
        RANGE   => [ -10, 10, -10, 10, .2 ],
        DATFUNC => \&make_print_hexagonal_data,
        FUNC    => \&ex_f1
    },
);

our @example_plots;

sub setup_example_plots {
    @example_plots = (
        { FILE => 'sq1.dat', ARGS => '' },
        {
            FILE => 'sq1.dat',
            ARGS =>
" -title 'A\\_ 0\\- sin(3xy)e\\^ -(x\\^2 2\\^ +y\\^2 2\\^ xx)' -xlabel 'x' -ylabel 'y' "
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -title \'Plot on \bf triangular \rm lattice\' '
        },
        {
            FILE => 'tr1.dat',
            ARGS =>
              '-cir -title \'Plot on \bf triangular \rm lattice with circles\' '
        },
        {
            FILE => 'tr1.dat',
            ARGS =>
'-tri -cmgray -title \'Grayscale. \xi  greek \arrowboth  symbols \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -cmbright .1  -title \'cmbright .1 \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -cmsatur .1 -title \'cmsaturation .1 \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -cmbright .4  -title \'cmbright .4 \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -cmsatur .4 -title \'cmsaturation .4  \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -cmsatbright 0.4 -title \'cmsatbright 0.4  \''
        },
        {
            FILE => 'sq1.dat',
            ARGS =>
'-nokey -ylabel \'Long unrotated \it y\rm  label\' -title \'No key, \^ super\^2 supersuper\_ sub\- normal \''
        },
        {
            FILE => 'sq1.dat',
            ARGS =>
'-nokey -rotylab -ylabel \'Long rotated \it y\rm  label\' -title \'No key, \^ super\^2 supersuper\_ sub\- normal \''
        },
        {
            FILE => 'tr1.dat',
            ARGS =>
'-tri -title \'\red \^2 \sym test\_ \green \rm test\- \bi \blue Test\''
        },
        { FILE => 'tr1.dat', ARGS => '-tri -axis -title \'Axes\'' },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -fontscale 2  -title \'Fontscale 2\''
        },
        {
            FILE => 'tr1.dat',
            ARGS =>
              '-tri -fontscale 2 -bbpad 30 -title \'Fontscale 2 and bbpad 30 \''
        },
        {
            FILE => 'tr1.dat',
            ARGS =>
'-tri -explim 10  -keydigits 4 -title \'No scientific notation in key\''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -xbuf .2 -ybuf .2  -title \'X and Y buffers big\''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -xbuf 0 -ybuf 0  -title \'X and Y buffers small\''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -polyborder  -title \' -polyborder\''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -lattice -latticegray .5  -title \' -lattice \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -saturation .5  -title \' -saturation .5 \''
        },
        {
            FILE => 'tr1.dat',
            ARGS => '-tri -brightness .5  -title \' -brightness .5 \''
        },
        {
            FILE => 'sq1.dat',
            ARGS =>
' -title \'Test\it  several\bi \green  text\bf \black  features\rm  X\^ 2\- x\^ 2\- \xi \^ 2\- \langle X\rangle \^ \h-3 3\- \IndianRed2 \otimes \' -xlabel \'x\' -ylabel \'y\' '
        },

    );
    for ( my $i = 0 ; $i < @example_plots ; $i++ ) {    # sequential filenames
        my $j = $i + 1;
        $example_plots[$i]->{OUT} = "ex$j";
    }
    $NumberOfExamplePlots = scalar(@example_plots);
}

# $view = 'view' if we launch viewer here. any other value does nothing
# $eoutfile is the name of the output file that overrides the filename specified
# by the example. This is to use the same filename for all examples so gv can 'watch'  it.
sub do_example {
    my ( $n, $view, $eoutfile ) = @_;
    if ( not defined $example_plots[ $n - 1 ] ) {
        herror "There are only " . scalar(@example_plots) . " examples.";
        return;
    }
    $n--;
    my $e       = $example_plots[$n];
    my $name    = $e->{FILE};
    my $outbase = $e->{OUT};
    my $args    = $e->{ARGS};
    if ( not -e $name ) {    # write the data file if it is not there
        verbose "Writing example data $name";
        my $exdat = $example_data{$name};
        &{ $exdat->{DATFUNC} }( $exdat->{RANGE}, $exdat->{FUNC}, $name );
    }
    if ( $PSFormat eq 'ps' )
    {    # copy the psformat given on the commandline that runs this example
        $args    .= ' -ps ';
        $outbase .= ".ps";
    }
    if ( $PSFormat eq 'eps' ) {
        $args    .= ' -eps ';
        $outbase .= ".eps";
    }
    elsif ( $PSFormat eq 'pdf' ) {
        $args    .= ' -pdf ';
        $outbase .= ".pdf";
    }

    # need to send viewer pid to new instance of tridens
    $outbase = $eoutfile if defined $eoutfile;
    $args .= " -viewerpid $ViewerPid " if defined $ViewerPid;
    my $dis = '';
    $dis = ' -dis ' if $Display == TRUE;
    my $com = "$ScriptName $dis $args -outfile $outbase $name";
    print "$com\n";
    verbosesys $com;
    $Outfile = $outbase;
    print "ex " . ( $n + 1 ) . ": plot file $Outfile\n";
    if ( defined $view and $view eq 'view' ) {
        check_viewer();
        $ViewerStarted = undef;
    }
}

sub make_square_data {
    my ( $range, $func ) = @_;
    my $v = [ [] ];
    my ( $x1, $x2, $xinc, $y1, $y2, $yinc ) = @$range;
    my ( $x, $y, $i, $j );
    $j = 0;
    for ( $y = $y1 ; $y <= $y2 ; $y += $yinc ) {
        $i = 0;
        for ( $x = $x1 ; $x <= $x2 ; $x += $xinc ) {
            $v->[$i]->[$j] = &$func( $x, $y );
            $i++;
        }
        $j++;
    }
    return $v;
}

sub make_triangular_data {
    my ( $range, $func ) = @_;
    my $v = [ [] ];
    my ( $i1, $i2, $j1, $j2, $s ) = @$range;    # s is length of side
    my ( $x,  $y,  $i,  $j );
    my ( $ii, $jj );
    my $xs = 0;
    my $ys = $s * sqrt(3) / 2;
    $jj = 0;

    for ( $j = $j1 ; $j <= $j2 ; $j++ ) {
        $xs = 1 - $xs;                          # flip 0, 1
        $ii = 0;
        for ( $i = $i1 ; $i <= $i2 ; $i++ ) {
            $v->[$ii]->[$jj] = &$func( $i * $s + $xs * $s / 2, $j * $ys );
            $ii++;
        }
        $jj++;
    }
    return $v;
}

sub make_hexagonal_data {
    my ( $range, $func ) = @_;
    my $v = [ [] ];
    my ( $i1, $i2, $j1, $j2, $s ) = @$range;    # s is length of side
    my ( $x,  $y,  $i,  $j );
    my ( $ii, $jj );
    my $xs  = 0;
    my $xs2 = 0;
    my $ys  = $s * sqrt(3) / 2;
    my $xpos;
    $jj = 0;

    for ( $j = $j1 ; $j <= $j2 ; $j++ ) {
        $xs   = 1 - $xs;                        # flip 0, 1
        $ii   = 0;
        $xpos = 0;
        for ( $i = $i1 ; $i <= $i2 ; $i++ ) {
            $xs2 = 1 - $xs2;                    # flip 0, 1
            $x = $xpos - $xs * (.5);
            $v->[$ii]->[$jj] =
              &$func( $i * $s * ( $xs + 1 ) + $xs * $s / 2, $j * $ys );
            $xpos += $s * ( $xs2 + 1 );
            $ii++;
        }
        $jj++;
    }
    return $v;
}

sub print_hexagonal_data {
    my ( $range, $v, $outfile ) = @_;
    my ( $i1, $i2, $j1, $j2, $s ) = @$range;    # s is length of side
    my ( $x,  $y,  $i,  $j );
    my ( $ii, $jj );
    my $xs  = 0;
    my $xs2 = 0;
    my $xpos;
    my $ys = $s * sqrt(3) / 2;
    $jj = 0;
    open EXH, ">$outfile"
      or die "Unable to open the file '$outfile' for writing";

    for ( $j = $j1 ; $j <= $j2 ; $j++ ) {
        $xs   = 1 - $xs;                        # flip 0, 1
        $ii   = 0;
        $xpos = 0;
        for ( $i = $i1 ; $i <= $i2 ; $i += 1 ) {
            $xs2 = 1 - $xs2;                    # flip 0, 1

            #	    $x = $xpos + ($ys*1/2);
            $x = $xpos - $xs * (.5);
            $y = $j * $ys;
            printf EXH "%e %e %e\n", $x, $y, $v->[$ii]->[$jj];
            $xpos += $s * ( $xs2 + 1 );
            $ii++;
        }
        $jj++;
    }
    close(EXH);
}

sub print_triangular_data {
    my ( $range, $v, $outfile ) = @_;
    my ( $i1, $i2, $j1, $j2, $s ) = @$range;    # s is length of side
    my ( $x,  $y,  $i,  $j );
    my ( $ii, $jj );
    my $xs = 0;
    my $ys = $s * sqrt(3) / 2;
    $jj = 0;
    open EXH, ">$outfile"
      or die "Unable to open the file '$outfile' for writing";

    for ( $j = $j1 ; $j <= $j2 ; $j++ ) {
        $xs = 1 - $xs;                          # flip 0, 1
        $ii = 0;
        for ( $i = $i1 ; $i <= $i2 ; $i++ ) {
            $x = $i * $s + $xs * $s / 2;
            $y = $j * $ys;
            printf EXH "%e %e %e\n", $x, $y, $v->[$ii]->[$jj];
            $ii++;
        }
        $jj++;
    }
    close(EXH);
}

sub print_square_data {
    my ( $range, $v, $outfile ) = @_;
    my ( $x1, $x2, $xinc, $y1, $y2, $yinc ) = @$range;
    my $j = 0;
    my $i;
    open EXH, ">$outfile"
      or die "Unable to open the file '$outfile' for writing";
    for ( my $y = $y1 ; $y <= $y2 ; $y += $yinc ) {
        $i = 0;
        for ( my $x = $x1 ; $x <= $x2 ; $x += $xinc ) {
            printf EXH "%e %e %e\n", $x, $y, $v->[$i]->[$j];
            $i++;
        }
        $j++;
    }
    close(EXH);
}

sub make_print_square_data {
    my ( $range, $func, $outfile ) = @_;
    my $v = make_square_data( $range, $func );
    print_square_data( $range, $v, $outfile );
}

sub make_print_triangular_data {
    my ( $range, $func, $outfile ) = @_;
    my $v = make_triangular_data( $range, $func );
    print_triangular_data( $range, $v, $outfile );
}

sub make_print_hexagonal_data {
    my ( $range, $func, $outfile ) = @_;
    my $v = make_hexagonal_data( $range, $func );
    print_hexagonal_data( $range, $v, $outfile );
}

sub ex_f1 {
    my ( $x, $y ) = @_;
    return .1 * sin( 3 * $x * $y ) * exp( -( $x * $x + $y * $y ) );
}

#}  #end context
# END example generation routines
#==========================================================================

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Code to generate tests.                                                            #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#

sub test_dosys {
    my $c = shift;
    print "  $c\n";
    return `$c 2>&1`;
}

sub passed {
    my ($good) = @_;
    print "passed\n";
    ${$good}++;
}

sub failed {
    print "***failed\n";
}

sub run_tests {
    my ($generate) = @_;
    my $td = "./tridens";
    my $good;
    my $total;
    $good  = 0;
    $total = 0;
    my $testdir = "tests";
    my $tt      = sub {
        my $f = shift;

        #	return $f;
        return "$testdir/$f";
    };

    my $batchfile1 = <<'EOBATCH1';
set -title "Hello"
show -title
set -title 'Hello'
show -title
set -title '\red Hello'
show -title
exit	
EOBATCH1

# old    { IN => { COM => "$td" }, OUT => { MATCH => "No input file specified; try option" }},
    my @tests = (
        {
            IN  => { COM   => "$td -version" },
            OUT => { MATCH => "tridens 0.017" }
        },
        { IN => { COM => "$td -h" }, OUT => { FILE => 'test_help_out' } },
        {
            IN  => { COM => "$td -batch batch1" },
            OUT => {
                BATCH     => $batchfile1,
                BATCHFILE => 'batch1',
                BATCHRES  => 'batchres1'
            }
        }
    );
    for ( my $i = 1 ; $i <= $NumberOfExamplePlots ; $i++ ) {
        push @tests,
          {
            IN  => { COM     => "$td -eps  -ex $i" },
            OUT => { EPSPLOT => "ex$i.eps", EXP => "oex$i.eps" }
          };
    }
    if ( $generate == TRUE ) {
        verbose "mkdir $testdir" unless -e "$testdir";
    }
    foreach my $t (@tests) {
        $total++;
        print "Test $total: ";
        my $in  = $t->{IN};
        my $out = $t->{OUT};
        my $res;
        if ( exists $in->{COM} ) {
            if ( $generate == FALSE or not exists $out->{BATCHFILE} ) {
                $res = test_dosys "cd $testdir && ../" . $in->{COM};
            }
        }
        if ( exists $out->{MATCH} ) {    # match stdout and stderr
            next if $generate == TRUE;
            if ( $res =~ $out->{MATCH} ) {
                passed( \$good );
            }
            else { failed(); }
        }
        elsif ( exists $out->{FILE} ) {

            #	    print $out->{FILE} . "\n";
            if ( $generate == TRUE ) {
                open OH, ">" . &$tt( $out->{FILE} );
                print OH $res;
                close(OH);
                next;
            }
            my $s        = "cat " . &$tt( $out->{FILE} );
            my $expected = `$s`;
            if ( $expected eq $res ) {
                passed( \$good );
            }
            else { failed(); }
        }
        elsif ( exists $out->{BATCH} ) {
            my $coms = $out->{BATCH};
            $coms = [$coms] if not ref($coms);
            if ( $generate == TRUE ) {
                open OH, ">" . &$tt( $out->{BATCHFILE} );
                print OH join( "\n", @$coms ) . "\n";
                close(OH);
                my $bres = test_dosys "cd $testdir; ../" . $in->{COM};
                open OH, ">" . &$tt( $out->{BATCHRES} );
                print OH $bres;
                close(OH);
                next;
            }
            my $s        = "cat " . &$tt( $out->{BATCHRES} );
            my $expected = `$s`;
            if ( $expected eq $res ) {
                passed( \$good );
            }
            else { failed(); }
        }
        elsif ( exists $out->{EPSPLOT} ) {
            if ( $generate == TRUE ) {
                verbosesys " cp -f \""
                  . &$tt( $out->{EPSPLOT} ) . "\"  \""
                  . &$tt( $out->{EXP} )
                  . "\" && rm -f \""
                  . &$tt( $out->{EPSPLOT} ) . "\"";
                next;
            }
            my $s    = "cat " . &$tt( $out->{EPSPLOT} );
            my $outf = `$s`;
            $s = "cat " . &$tt( $out->{EXP} );
            my $expected = `$s`;

            #  $outf = `$s`;
            if ( $expected eq $outf ) {
                passed( \$good );
            }
            else { failed(); }
        }
    }
    print "\n "
      . ( $total - $good )
      . " failed,  $good/$total tests sucessful\n"
      unless $generate == TRUE;
    exit(0);
}

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  PostScript plot generation. Computations for the plot are done here.               #
#    make_data_postscript() is in section 'Reading data...' because some data is      #
#    hidden there                                                                     #
#                                                                                     #
#=====================================================================================#


#==========================================================================
# PostScript writing routines. These routines write pieces of the PostScript code.

sub format_real {
    my ( $x, $dig, $scilim ) = @_;
    my $r;
    my $s1 = sprintf( "%.${dig}e", $x );
    $s1 =~ /e(.+)/;    # find exponent
    die "Can't find exponent in conversion"
      unless defined $1;
    my $n = $1;
    if ( abs($n) <= $scilim ) {
        $r = sprintf( "%.${dig}f", $x );
    }
    else {
        return ( $s1, 1 );
    }
    return ( $r, 0 );
}

sub make_landscape_com {
    return <<"EOLL";
%-90 rotate -792 0 translate
90 rotate 0 -612 translate
/pagewidth 11 in def
/pageheight 8.5 in def
EOLL
}

sub set_initial_top_matter {
    $DocTypeLine = "%!PS-Adobe-2.0";
    $ShowPage    = 'showpage';

    $PaperComments = <<'EOPAP';

%%DocumentPaperSizes: letter
%%BeginSetup
[{
%BeginFeature: *PageRegion Letter
<</PageSize [612 792]>> setpagedevice
%EndFeature
} stopped cleartomark
%%EndSetup
EOPAP

}    # emacs parser complains here, but it is wrong.

sub real_show {
    my $x = shift;
    my ( $s, $flag ) = format_real( $x, $KeyDigits, $ExponentLimit );
    if ( $flag == FALSE ) {
        return "($s) show";
    }
    else {
        if ( $LatexNumbers == TRUE ) {
            return sci_not_latex($s);
        }
        else {
            return sci_not_native($s);
        }
    }
}

# scientific notation with superscript
# native means we draw the scientific notation in PostScript
sub sci_not_native {
    my $n = shift;
    my ( $mant, $exp ) = split( 'e', $n );
    my $pe = sprintf( "%d", $exp );
    if ( $DotForTimes == TRUE ) {
        return "($mant) ($pe) drawscinotdot";
    }
    else {
        return "($mant) ($pe) drawscinot";
    }
}

# This one uses latex , used when working with ipe.
# But ipe has a bug that causes a crash when using this.
sub sci_not_latex {
    my $n = shift;
    my ( $mant, $exp ) = split( 'e', $n );
    my $pe = sprintf( "%d", $exp );
    return '($' . $mant . ' \\\\times  10^{' . $pe . '}$) show';
}

# This draws the polygon. square, triangle, hexagon
sub pshex {
    my ( $cx, $cy, $g ) = @_;
    my $string;
    $string = sprintf( "%f %.4e %.4e pd\n", $g, $cx, $cy );
    $string =~ s/([\.1-9]+)0+(\D)/$1$2/g;  # strip trailing zeros for efficiency
    return $string;
}

# This draws the polygon. square, triangle, hexagon
sub pshex_rot_180 {
    my ( $cx, $cy, $g ) = @_;
    my $string;
    $string = sprintf( "%f %.4e %.4e pdr\n", $g, $cx, $cy );
    return $string;
}

sub pshexn {
    my ( $cx, $cy, $g, $V ) = @_;
    my $n = $NumberPolyDig;
    my ( $str, $flag ) = format_real( $V, $NumberPolyDig, $NumberPolySciLim );

    #    if ( abs($V) < 1 and abs($V) > 0 ) {
    #	$s = sprintf("%.${n}f",$V);
    #	$s =~ s/0//;
    #	print "$s\n";
    #    }
    #    else { 	$s = sprintf("%.2f",$V); }
    $str =~ s/^0//g;
    $str =~ s/0$//g;
    $str =~ s/e0/e/g;
    $str =~ s/e\-0/e\-/g;
    $str =~ s/0e/e/g;
    $str = '' if $str == 0 and $NumberPolyZero == TRUE;
    my $string;

    if ( $str =~ /e/ ) {
        $string = sprintf( "($str) %f %.6e %.6e pdnflsm\n", $g, $cx, $cy );
    }
    else {
        $string = sprintf( "($str) %f %.6e %.6e pdnfl\n", $g, $cx, $cy );
    }
    return $string;
}


sub make_xticks {
    my ( $i, $x );
    my $s = '';
    return $s unless $BTickDraw == TRUE || $TTickDraw == TRUE;
    my ( $lbound, $hbound ) = ( $LBound, $HBound );
    $lbound = 'auto';
    $hbound = 'auto';
    my @sxticks = auto_ticks( $DXlo, $DXhi, $lbound, $hbound, $TickInterval,
        \@MagicIntervals, \@Divisions );
    my @xticks;

    for ( $i = 0 ; $i < @sxticks ; $i++ ) {
        $xticks[$i] = data_to_window_transform_x( $sxticks[$i] );
    }
    my $nticks = scalar(@xticks);
    while ( $xticks[0] < $XBlo ) {
        shift(@xticks);
        shift(@sxticks);
        $nticks--;
    }
    while ( $xticks[-1] > $XBhi ) {
        pop(@xticks);
        pop(@sxticks);
        $nticks--;
    }
    my ( $xpos, $xlpos, $xshow );
    for ( $i = 0 ; $i < $nticks ; $i++ ) {
        $xpos = $xlpos = $x = $xticks[$i];
        $xshow = $sxticks[$i];

        # adjust end ticks a bit
        if ( $TicksShiftOuter == TRUE ) {
            $xlpos = "$x rtickfontheight 2 div sub" if $i == $nticks - 1;
            $xlpos = "$x rtickfontheight 2 div add" if $i == 0;
        }
        $x = 0 if abs($x) < $ZeroAbs;
        $s .= "($xshow) $xlpos yblo $xpos yblo drawbtick\n" if $BTickDraw == TRUE;
        $s .= "($xshow) $xlpos ybhi $xpos ybhi drawttick\n" if $TTickDraw == TRUE;
    }
    return $s;

    # Looks Like following is not used !!
    $x = $XTickStart;
    for ( ; ; ) {
        $s .= "($x) $x yblo  drawbtick\n" if $BTickDraw == TRUE;
        $s .= "($x) $x ybhi  drawttick\n" if $TTickDraw == TRUE;
        $x -= $XTickInt;
        last if $x < $Xlo;
    }
    $x = $XTickStart + $XTickInt;
    for ( ; ; ) {
        last if $x > $Xhi;
        $s .= "($x) $x yblo  drawbtick\n" if $BTickDraw == TRUE;
        $s .= "($x) $x ybhi  drawttick\n" if $TTickDraw == TRUE;
        $x += $XTickInt;
    }
    return $s;
}

sub make_yticks {
    my ( $i, $y, $ypos, $ylpos );
    my $s = '';
    return $s unless $LTickDraw == TRUE || $RTickDraw == TRUE;
    my @syticks = auto_ticks( $DYlo, $DYhi, $LBound, $HBound, $TickInterval,
        \@MagicIntervals, \@Divisions );
    my @yticks;
    for ( $i = 0 ; $i < @syticks ; $i++ ) {
        $yticks[$i] = data_to_window_transform_y( $syticks[$i] );
    }
    my $nticks = scalar(@yticks);
    while ( $yticks[0] < $YBlo ) {

        #	print STDERR "popping tick mark\n";
        shift(@yticks);
        shift(@syticks);
        $nticks--;
    }
    while ( $yticks[-1] > $YBhi ) {
        pop(@yticks);
        pop(@syticks);
        $nticks--;
    }
    my $yshow;
    for ( $i = 0 ; $i < $nticks ; $i++ ) {
        $ypos = $ylpos = $y = $yticks[$i];
        $yshow = $syticks[$i];

        # adjust end ticks a bit
        if ( $TicksShiftOuter == TRUE ) {
            $ylpos = "$y rtickfontheight 2 div sub" if $i == $nticks - 1;
            $ylpos = "$y rtickfontheight 2 div add" if $i == 0;
        }
        $y = 0 if abs($y) < $ZeroAbs;
        $s .= "($yshow) xblo $ylpos xblo $ypos drawltick\n" if $LTickDraw == TRUE;
        $s .= "($yshow) xbhi $ylpos xbhi $ypos drawrtick\n" if $RTickDraw == TRUE;
    }
    return $s;

    # Looks Like following is not used !!
    $y = $YTickStart;
    for ( ; ; ) {
        $s .= "($y)  xblo $y drawltick\n" if $LTickDraw == TRUE;
        $s .= "($y) xbhi $y  drawrtick\n" if $RTickDraw == TRUE;
        $y -= $YTickInt;
        last if $y < $Ylo;
    }
    $y = $YTickStart + $YTickInt;
    for ( ; ; ) {
        last if $y > $Yhi;
        $s .= "($y) xblo $y  drawltick\n" if $LTickDraw == TRUE;
        $s .= "($y) xbhi $y  drawrtick\n" if $RTickDraw == TRUE;
        $y += $YTickInt;
    }
    return $s;
}

sub make_key_color_boxes {
    my $s = '';
    my ( $i, $val );
    my @kb = ( 0 .. $NumKeyBars );    # numerical value
    my @kc = ( 0 .. $NumKeyBars );    # color
    for ( $i = 0 ; $i < $NumKeyBars ; $i++ ) {
        $kc[$i] /= ( $NumKeyBars - 1 );
        $kc[$i] = scale_transform( $kc[$i] ) if $UseColTrans == TRUE;
        $kb[$i] /= $NumKeyBars - 1;

        #	$kb[$i] = inv_scale_transform($kb[$i]) if $UseColTrans == TRUE;
        $kb[$i] = inv_norm_power( $kb[$i] );
        $kb[$i] = inv_norm_linear( $kb[$i] ) if $ShowNormalized != 1;

        #	print "col $kc[$i], val $kb[$i]\n";
    }
    $s = "gsave\n";
    for ( $i = 0 ; $i < $NumKeyBars ; $i++ ) {
        $val = '';

        #        $val = sprintf("%.10e",$kb[$i]);
        #	$val = format_real($kb[$i]);
        $val = real_show( $kb[$i] ) if $i % $KeyLabelSkip == FALSE;

        # To move text left side of key, we need to know its width.
        # For this, we need a routine like drawscinot that computes the
        # text width and pushes it on the stack.
        $s .= <<"EOK"
 keyxpos keyypos $i keybarheight mul add moveto	
 0 keybarheight rlineto
 keywidth 0 rlineto
 0 keybarheight neg rlineto
 closepath
 $kc[$i]  $SetDensityColor
 gsave
 fill
 grestore
% $KeySepGray setgray stroke
 newpath
 keyxpos keywidth 1.2 mul add 
 keyypos $i .2 add keybarheight mul add moveto
 0 setgray
 $val
EOK
    }
    $s .= "grestore\n";
    return $s;
}

sub draw_axes {
    my $s = '';
    $s .= "drawxaxis\n" if $XAxis == TRUE;
    $s .= "drawyaxis\n" if $YAxis == TRUE;
    return $s;
}

sub make_title {
    my $st;
    my $sh = $TitleXOffset;
    $st = print_centeredx(
        $YBlo + ( 1 + $TitleYOffset * $FontScale ) * ( $YBhi - $YBlo ),
        ( ( 1 - $sh ) * $XBlo + ( 1 + $sh ) * $XBhi ) / 2, $Title );
    return $st;
}

sub draw_marks {
    my $st   = '';
    my @keys = keys %Marks;
    if ( @keys > 0 ) {
        $st = "gsave newpath\n";
        foreach my $m (@keys) {
            my $mh   = $Marks{$m};
            my $x    = $Xlo + ( $Xhi - $Xlo ) * $mh->{X};
            my $y    = $Ylo + ( $Yhi - $Ylo ) * $mh->{Y};
            my $size = $mh->{SIZE};
            $st .=
              "$x $y moveto\n" . "currentpoint $size 0 360 arc\n" . "fill\n";
        }
        $st .= "grestore\n";
    }
    return $st;
}

#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=
# Context for routines for showing text in mixed fonts
#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=
{

    # these fonts should be organized better. put in hashses with families
    my $topstring;
    my $mainfont           = "Mainfont";
    my $italicfont         = "Italicfont";
    my $boldfont           = "Boldfont";
    my $bolditalicfont     = "BoldItalicfont";
    my $symfont            = "MainSymbol";
    my $supfont            = "MainSup";
    my $italicsupfont      = "Italicsup";
    my $boldsupfont        = "Boldsup";
    my $bolditalicsupfont  = "BoldItalicsup";
    my $ssupfont           = "MainSSup";
    my $italicssupfont     = "Italicssup";
    my $boldssupfont       = "Boldssup";
    my $bolditalicssupfont = "BoldItalicssup";
    my $supsymfont         = "MainSupSym";
    my $ssupsymfont        = "MainSSupSym";
    my $subfont            = "MainSub";
    my $italicsubfont      = "Italicsub";
    my $boldsubfont        = "Boldsub";
    my $bolditalicsubfont  = "BoldItalicsub";
    my $subsymfont         = "MainSubSym";
    my @fontlist;    # not used ?!
    my %fontnums;

    my $fontsize;
    my $basefontname;

    my $rfontsize;
    my ( $supshift, $nsupshift );
    my $xsupshift;
    my ( $ssupshift, $nssupshift );
    my $xssupshift;
    my ( $subshift, $nsubshift, $xsubshift );

    my (
        %fontcodes,    %scriptcodes, %spacecodes,
        %RgbCodes,     %graycodes,   %hsbcodes,
        %scriptshifts, %fontnames,   %spaceshifts
    );

    sub setup_symcodelist {
        @Symcodelist = qw(
          space exclam universal numbersign existential percent ampersand suchthat parenleft parenright
          asteriskmath plus comma minus period slash zero one two three four five six seven eight nine
          colon semicolon less equal greater question congruent Alpha Beta Chi Delta Epsilon Phi Gamma
          Eta Iota theta1 Kappa Lambda Mu Nu Omicron Pi Theta Rho Sigma Tau Upsilon sigma1 Omega Xi Psi
          Zeta bracketleft therefore bracketright perpendicular underscore radicalex alpha beta chi delta
          epsilon phi gamma eta iota phi1 kappa lambda mu nu omicron pi theta rho sigma tau upsilon omega1
          omega xi psi zeta braceleft bar braceright similar Euro Upsilon1 minute lessequal fraction infinity
          florin club diamond heart spade arrowboth arrowleft arrowup arrowright arrowdown degree plusminus
          second greaterequal multiply proportional partialdiff bullet divide notequal equivalence approxequal
          ellipsis arrowvertex arrowhorizex carriagereturn aleph Ifraktur Rfraktur weierstrass circlemultiply
          circleplus emptyset intersection union propersuperset reflexsuperset notsubset propersubset
          reflexsubset element notelement angle gradient registerserif copyrightserif trademarkserif product
          radical dotmath logicalnot logicaland logicalor arrowdblboth arrowdblleft arrowdblup arrowdblright
          arrowdbldown lozenge angleleft registersans copyrightsans trademarksans summation parenlefttp parenleftex
          parenleftbt bracketlefttp bracketleftex bracketleftbt bracelefttp braceleftmid braceleftbt braceex angleright
          integral integraltp integralex integralbt parenrighttp parenrightex parenrightbt bracketrighttp bracketrightex
          bracketrightbt bracerighttp bracerightmid bracerightbt );

        # aliases from some latex symbol names to Adobe symbol font names
        @Symaliaslist = qw (otimes oplus leftarrow rightarrow leftrightarrow
          langle rangle cup cap pm mp ge le );

        %Symaliases = (
            times          => 'multiply',
            otimes         => 'circlemultiply',
            oplus          => 'circleplus',
            leftarrow      => 'arrowleft',
            rightarrow     => 'arrowright',
            leftrightarrow => 'arrowboth',
            langle         => 'angleleft',
            rangle         => 'angleright',
            cup            => 'union',
            cap            => 'intersection',
            pm             => 'plusminus',
            mp             => 'minusplus',
            ge             => 'greaterequal',
            le             => 'lessequal'
        );
    }

    %Symcodes = (
        space          => '040',
        exclam         => '041',
        universal      => '042',
        numbersign     => '043',
        existential    => '044',
        percent        => '045',
        ampersand      => '046',
        suchthat       => '047',
        parenleft      => '050',
        parenright     => '051',
        asteriskmath   => '052',
        plus           => '053',
        comma          => '054',
        minus          => '055',
        period         => '056',
        slash          => '057',
        zero           => '060',
        one            => '061',
        two            => '062',
        three          => '063',
        four           => '064',
        five           => '065',
        six            => '066',
        seven          => '067',
        eight          => '070',
        nine           => '071',
        colon          => '072',
        semicolon      => '073',
        less           => '074',
        equal          => '075',
        greater        => '076',
        question       => '077',
        congruent      => '100',
        Alpha          => '101',
        Beta           => '102',
        Chi            => '103',
        Delta          => '104',
        Epsilon        => '105',
        Phi            => '106',
        Gamma          => '107',
        Eta            => '110',
        Iota           => '111',
        theta1         => '112',
        Kappa          => '113',
        Lambda         => '114',
        Mu             => '115',
        Nu             => '116',
        Omicron        => '117',
        Pi             => '120',
        Theta          => '121',
        Rho            => '122',
        Sigma          => '123',
        Tau            => '124',
        Upsilon        => '125',
        sigma1         => '126',
        Omega          => '127',
        Xi             => '130',
        Psi            => '131',
        Zeta           => '132',
        bracketleft    => '133',
        therefore      => '134',
        bracketright   => '135',
        perpendicular  => '136',
        underscore     => '137',
        radicalex      => '140',
        alpha          => '141',
        beta           => '142',
        chi            => '143',
        delta          => '144',
        epsilon        => '145',
        phi            => '146',
        gamma          => '147',
        eta            => '150',
        iota           => '151',
        phi1           => '152',
        kappa          => '153',
        lambda         => '154',
        mu             => '155',
        nu             => '156',
        omicron        => '157',
        pi             => '160',
        theta          => '161',
        rho            => '162',
        sigma          => '163',
        tau            => '164',
        upsilon        => '165',
        omega1         => '166',
        omega          => '167',
        xi             => '170',
        psi            => '171',
        zeta           => '172',
        braceleft      => '173',
        bar            => '174',
        braceright     => '175',
        similar        => '176',
        Euro           => '240',
        Upsilon1       => '241',
        minute         => '242',
        lessequal      => '243',
        fraction       => '244',
        infinity       => '245',
        florin         => '246',
        club           => '247',
        diamond        => '250',
        heart          => '251',
        spade          => '252',
        arrowboth      => '253',
        arrowleft      => '254',
        arrowup        => '255',
        arrowright     => '256',
        arrowdown      => '257',
        degree         => '260',
        plusminus      => '261',
        second         => '262',
        greaterequal   => '263',
        multiply       => '264',
        proportional   => '265',
        partialdiff    => '266',
        bullet         => '267',
        divide         => '270',
        notequal       => '271',
        equivalence    => '272',
        approxequal    => '273',
        ellipsis       => '274',
        arrowvertex    => '275',
        arrowhorizex   => '276',
        carriagereturn => '277',
        aleph          => '300',
        Ifraktur       => '301',
        Rfraktur       => '302',
        weierstrass    => '303',
        circlemultiply => '304',
        circleplus     => '305',
        emptyset       => '306',
        intersection   => '307',
        union          => '310',
        propersuperset => '311',
        reflexsuperset => '312',
        notsubset      => '313',
        propersubset   => '314',
        reflexsubset   => '315',
        element        => '316',
        notelement     => '317',
        angle          => '320',
        gradient       => '321',
        registerserif  => '322',
        copyrightserif => '323',
        trademarkserif => '324',
        product        => '325',
        radical        => '326',
        dotmath        => '327',
        logicalnot     => '330',
        logicaland     => '331',
        logicalor      => '332',
        arrowdblboth   => '333',
        arrowdblleft   => '334',
        arrowdblup     => '335',
        arrowdblright  => '336',
        arrowdbldown   => '337',
        lozenge        => '340',
        angleleft      => '341',
        registersans   => '342',
        copyrightsans  => '343',
        trademarksans  => '344',
        summation      => '345',
        parenlefttp    => '346',
        parenleftex    => '347',
        parenleftbt    => '350',
        bracketlefttp  => '351',
        bracketleftex  => '352',
        bracketleftbt  => '353',
        bracelefttp    => '354',
        braceleftmid   => '355',
        braceleftbt    => '356',
        braceex        => '357',
        angleright     => '361',
        integral       => '362',
        integraltp     => '363',
        integralex     => '364',
        integralbt     => '365',
        parenrighttp   => '366',
        parenrightex   => '367',
        parenrightbt   => '370',
        bracketrighttp => '371',
        bracketrightex => '372',
        bracketrightbt => '373',
        bracerighttp   => '374',
        bracerightmid  => '375',
        bracerightbt   => '376',
    );

    # probably others should be added here.
    sub setup_font_list {
        %FontList = (
            'bookman' => [
                qw( Bookman-Light
                  Bookman-LightItalic
                  Bookman-Demi
                  Bookman-DemiItalic)
            ],
            'courier' => [
                qw(
                  Courier
                  Courier-Oblique
                  Courier-Bold
                  Courier-BoldOblique)
            ],
            'helvetica' => [
                qw(
                  Helvetica
                  Helvetica-Oblique
                  Helvetica-Bold
                  Helvetica-BoldOblique)
            ],
            'helvetica-narrow' => [
                qw(
                  Helvetica-Narrow
                  Helvetica-Narrow-Oblique
                  Helvetica-Narrow-Bold
                  Helvetica-Narrow-BoldOblique)
            ],
            'palatino' => [
                qw(
                  Palatino-Roman
                  Palatino-Italic
                  Palatino-Bold
                  Palatino-BoldItalic)
            ],
            'newcenturyschlbk' => [
                qw(
                  NewCenturySchlbk-Roman
                  NewCenturySchlbk-Italic
                  NewCenturySchlbk-Bold
                  NewCenturySchlbk-BoldItalic)
            ],
            'times' => [
                qw(
                  Times-Roman
                  Times-Italic
                  Times-Bold
                  Times-BoldItalic )
            ],
            'charter' => [
                qw(
                  Charter-Roman Charter-Italic  Charter-Bold Charter-BoldItalic
                  )
            ],
            'utopia' =>
              [qw( Utopia-Regular Utopia-Italic Utopia-Bold Utopia-BoldItalic)],
            'arial' =>
              [ 'Arial', 'Arial,Italic', 'Arial,Bold', 'Arial,BoldItalic' ],
            'timesnewroman' => [
                'TimesNewRoman',      'TimesNewRoman,Italic',
                'TimesNewRoman,Bold', 'TimesNewRoman,BoldItalic'
              ]

              #         '' => [qw(
              #
              #               )],
        );
    }

    # should be a data structure that sends things here.
    # same data should be used for completion
    #
    # font => [ qw(list of font names)]
    # viewer => [ viewer names ...]
    # eg check_string_args( $v, [ 'gv', 'xpdf' ], 'viewer program' );
    sub check_string_args {
        my ( $s, $strs, $msg ) = @_;
        $s = strip_spaces($s);
        my $outst = '';
        foreach (@$strs) {
            if (/^$s/) {
                $outst = $_;
                last;
            }
        }
        if ( $outst eq '' ) {
            herror("Unknown $msg '$s'");
            return undef;
        }
        return $outst;
    }

    # set the four standard fonts from the list above.
    # Ths OptionArg thing is useless. The args are acutally passed
    sub choose_font_names {
        my ($name) = @_;
        my @names = sort keys %FontList;
        my $outname = check_string_args( $name, \@names, 'font name' );
        return undef unless defined $outname;
        $Font = $outname;
        my $f = $FontList{$outname};
        ( $PlainFontname, $ItalicFontname, $BoldFontname, $BoldItalicFontname )
          = @$f;
        return $Font;
    }

# obsolete. not used remove this soon
    sub choose_viewer {
        my ($v) = @_;
        my $outv = check_string_args( $v, [ 'gv', 'xpdf' ], 'viewer program' );
        return undef unless defined $outv;
        $Viewer = $outv;
    }

    sub setup_mixed_fonts {
        my $boxwidth = $XBhi - $XBlo;

        $basefontname = $PlainFontname;
        $fontsize     = $FontScale * .04 * $boxwidth;    # main font size

        # fontcodes and scriptcodes only mark that they exist. RgbCodes gives
        # data as well
        %fontcodes = ( 'it' => 1, 'rm' => 1, 'sym' => 1, 'bf' => 1, 'bi' => 1 );
        %scriptcodes = ( '^' => 1, '_' => 1, '^2' => 1, '-' => 1 );
        setup_rgb_codes();
        setup_symcodelist();
        my $i = 1;
        for ( my $g = 0.01 ; $g < 1.00001 ; $g += .01 ) {    # setup graycodes
            my $key = "gray$i";
            $graycodes{$key} = $g;
            $i++;
        }
        %hsbcodes = ( 'placeholdercode' => [ .5, .5, .5 ] );

        # Following is current method. These names are constructed from
        # a combination of a script and font code.
        %fontnames = (
            'rm-'   => $mainfont,
            'it-'   => $italicfont,
            'bf-'   => $boldfont,
            'bi-'   => $bolditalicfont,
            'sym-'  => $symfont,
            'rm^'   => $supfont,
            'sym^'  => $supsymfont,
            'it^'   => $italicsupfont,
            'bf^'   => $boldsupfont,
            'bi^'   => $bolditalicsupfont,
            'it^2'  => $italicssupfont,
            'bf^2'  => $boldssupfont,
            'bi^2'  => $bolditalicssupfont,
            'rm^2'  => $ssupfont,
            'sym^2' => $ssupsymfont,
            'rm_'   => $subfont,
            'sym_'  => $subsymfont,
            'it_'   => $italicsubfont,
            'bf_'   => $boldsubfont,
            'bi_'   => $bolditalicsubfont
        );

        sub get_font_name {
            my ( $type, $script ) = @_;
            my $name = $type . $script;
            if ( not exists $fontnames{$name} ) {
                herror("Don't know font '$type' with sub/sup script '$script'");
            }
            return $fontnames{$name};
        }

        my $xnsubshift;
        my $xnsupshift;
        my $xnssupshift;

   # Set the distance that the super and subscripts will be shifted by.
   # rfontsize appears to be an overall scale factor for just the super and subs
        $rfontsize = 1.5;
        $supshift  = $fontsize / $rfontsize * .65;
        $nsupshift = -$supshift;
        $xsupshift = -$fontsize / $rfontsize * .06;

        $ssupshift   = $fontsize / $rfontsize * 1.05;
        $nssupshift  = -$ssupshift;
        $xnssupshift = $fontsize / $rfontsize * .05;
        $xssupshift  = -$fontsize / $rfontsize * .02;
        $subshift    = -$fontsize / $rfontsize * .17;
        $nsubshift   = -$subshift;
        $xsubshift   = -$fontsize / $rfontsize * .01;

        %scriptshifts = (
            '^'  => { IN => "$xsupshift supshift ", OUT => "0 supshift neg " },
            '^2' => {
                IN  => "$xssupshift ssupshift ",
                OUT => "$xnssupshift ssupshift neg "
            },
            '_' => { IN => "$xsubshift $subshift", OUT => "0 $nsubshift" }
        );

        %spaceshifts = (
            'h+'  => { X => 1,      Y => 0 },
            'h-'  => { X => -1,     Y => 0 },
            'h+2' => { X => .5,     Y => 0 },
            'h-2' => { X => -.5,    Y => 0 },
            'h+3' => { X => .25,    Y => 0 },
            'h-3' => { X => -.25,   Y => 0 },
            'h+4' => { X => .125,   Y => 0 },
            'h-4' => { X => -.125,  Y => 0 },
            'h+5' => { X => .0625,  Y => 0 },
            'h-5' => { X => -.0625, Y => 0 },
            'v+'  => { X => 0,      Y => 1 },
            'v-'  => { X => 0,      Y => -1 },
            'v+2' => { X => 0,      Y => .5 },
            'v-2' => { X => 0,      Y => -.5 },
            'v+3' => { X => 0,      Y => .25 },
            'v-3' => { X => 0,      Y => -.25 },
            'v+4' => { X => 0,      Y => .125 },
            'v-4' => { X => 0,      Y => -.125 },
            'v+5' => { X => 0,      Y => .0625 },
            'v-5' => { X => 0,      Y => -.0625 },
        );

        $topstring = <<"EOL";

/$mainfont /$basefontname findfont $fontsize scalefont def
/$italicfont /$ItalicFontname findfont $fontsize scalefont def
/$boldfont /$BoldFontname findfont $fontsize scalefont def
/$bolditalicfont /$BoldItalicFontname findfont $fontsize scalefont def
/$symfont /Symbol findfont $fontsize scalefont  def
/$supsymfont /Symbol findfont $fontsize $Supscale mul  scalefont  def
/$ssupsymfont /Symbol findfont $fontsize $SSupscale mul  scalefont  def
/$supfont /$basefontname findfont $fontsize $Supscale mul scalefont  def
/$italicsupfont /$ItalicFontname findfont $fontsize $Supscale mul scalefont  def
/$boldsupfont /$BoldFontname findfont $fontsize $Supscale mul scalefont  def
/$bolditalicsupfont /$BoldItalicFontname findfont $fontsize $Supscale mul scalefont  def
/$ssupfont /$basefontname findfont $fontsize $SSupscale mul scalefont  def
/$italicssupfont /$ItalicFontname findfont $fontsize $SSupscale mul scalefont  def
/$boldssupfont /$BoldFontname findfont $fontsize $SSupscale mul scalefont  def
/$bolditalicssupfont /$BoldItalicFontname findfont $fontsize $SSupscale mul scalefont  def
/$subfont /$basefontname findfont $fontsize $Subscale mul scalefont  def
/$italicsubfont /$ItalicFontname findfont $fontsize $Subscale mul scalefont  def
/$boldsubfont /$BoldFontname findfont $fontsize $Subscale mul scalefont  def
/$bolditalicsubfont /$BoldItalicFontname findfont $fontsize $Subscale mul scalefont  def
/$subsymfont /Symbol findfont $fontsize $Subscale mul  scalefont  def


EOL

    }    # end of setup_mixed_fonts

    sub setup_rgb_codes {
        return if @RgbNames > 0;
        my $colors = <<"EOCOLORS";
255 250 250 snow
248 248 255 GhostWhite
245 245 245 WhiteSmoke
220 220 220 gainsboro
255 250 240 FloralWhite
253 245 230 OldLace
250 240 230 linen
250 235 215 AntiqueWhite
255 239 213 PapayaWhip
255 235 205 BlanchedAlmond
255 228 196 bisque
255 218 185 PeachPuff
255 222 173 NavajoWhite
255 228 181 moccasin
255 248 220 cornsilk
255 255 240 ivory
255 250 205 LemonChiffon
255 245 238 seashell
240 255 240 honeydew
245 255 250 MintCream
240 255 255 azure
240 248 255 AliceBlue
230 230 250 lavender
255 240 245 LavenderBlush
255 228 225 MistyRose
255 255 255 white
  0   0   0 black
 47  79  79 DarkSlateGray
 47  79  79 DarkSlateGrey
105 105 105 DimGray
105 105 105 DimGrey
112 128 144 SlateGray
112 128 144 SlateGrey
119 136 153 LightSlateGray
119 136 153 LightSlateGrey
190 190 190 gray
190 190 190 grey
211 211 211 LightGrey
211 211 211 LightGray
 25  25 112 MidnightBlue
  0   0 128 navy
  0   0 128 NavyBlue
100 149 237 CornflowerBlue
 72  61 139 DarkSlateBlue
106  90 205 SlateBlue
123 104 238 MediumSlateBlue
132 112 255 LightSlateBlue
  0   0 205 MediumBlue
 65 105 225 RoyalBlue
  0   0 255 blue
 30 144 255 DodgerBlue
  0 191 255 DeepSkyBlue
135 206 235 SkyBlue
135 206 250 LightSkyBlue
 70 130 180 SteelBlue
176 196 222 LightSteelBlue
173 216 230 LightBlue
176 224 230 PowderBlue
175 238 238 PaleTurquoise
  0 206 209 DarkTurquoise
 72 209 204 MediumTurquoise
 64 224 208 turquoise
  0 255 255 cyan
224 255 255 LightCyan
 95 158 160 CadetBlue
102 205 170 MediumAquamarine
127 255 212 aquamarine
  0 100   0 DarkGreen
 85 107  47 DarkOliveGreen
143 188 143 DarkSeaGreen
 46 139  87 SeaGreen
 60 179 113 MediumSeaGreen
 32 178 170 LightSeaGreen
152 251 152 PaleGreen
  0 255 127 SpringGreen
124 252   0 LawnGreen
  0 255   0 green
127 255   0 chartreuse
  0 250 154 MediumSpringGreen
173 255  47 GreenYellow
 50 205  50 LimeGreen
154 205  50 YellowGreen
 34 139  34 ForestGreen
107 142  35 OliveDrab
189 183 107 DarkKhaki
240 230 140 khaki
238 232 170 PaleGoldenrod
250 250 210 LightGoldenrodYellow
255 255 224 LightYellow
255 255   0 yellow
255 215   0  gold
238 221 130 LightGoldenrod
218 165  32 goldenrod
184 134  11 DarkGoldenrod
188 143 143 RosyBrown
205  92  92 IndianRed
139  69  19 SaddleBrown
160  82  45 sienna
205 133  63 peru
222 184 135 burlywood
245 245 220 beige
245 222 179 wheat
244 164  96 SandyBrown
210 180 140 tan
210 105  30 chocolate
178  34  34 firebrick
165  42  42 brown
233 150 122 DarkSalmon
250 128 114 salmon
255 160 122 LightSalmon
255 165   0 orange
255 140   0 DarkOrange
255 127  80 coral
240 128 128 LightCoral
255  99  71 tomato
255  69   0 OrangeRed
255   0   0 red
255 105 180 HotPink
255  20 147 DeepPink
255 192 203 pink
255 182 193 LightPink
219 112 147 PaleVioletRed
176  48  96 maroon
199  21 133 MediumVioletRed
208  32 144 VioletRed
255   0 255 magenta
238 130 238 violet
221 160 221 plum
218 112 214 orchid
186  85 211 MediumOrchid
153  50 204 DarkOrchid
148   0 211 DarkViolet
138  43 226 BlueViolet
160  32 240 purple
147 112 219 MediumPurple
216 191 216 thistle
255 250 250 snow1
238 233 233 snow2
205 201 201 snow3
139 137 137 snow4
255 245 238 seashell1
238 229 222 seashell2
205 197 191 seashell3
139 134 130 seashell4
255 239 219 AntiqueWhite1
238 223 204 AntiqueWhite2
205 192 176 AntiqueWhite3
139 131 120 AntiqueWhite4
255 228 196 bisque1
238 213 183 bisque2
205 183 158 bisque3
139 125 107 bisque4
255 218 185 PeachPuff1
238 203 173 PeachPuff2
205 175 149 PeachPuff3
139 119 101 PeachPuff4
255 222 173 NavajoWhite1
238 207 161 NavajoWhite2
205 179 139 NavajoWhite3
139 121	 94 NavajoWhite4
255 250 205 LemonChiffon1
238 233 191 LemonChiffon2
205 201 165 LemonChiffon3
139 137 112 LemonChiffon4
255 248 220 cornsilk1
238 232 205 cornsilk2
205 200 177 cornsilk3
139 136 120 cornsilk4
255 255 240 ivory1
238 238 224 ivory2
205 205 193 ivory3
139 139 131 ivory4
240 255 240 honeydew1
224 238 224 honeydew2
193 205 193 honeydew3
131 139 131 honeydew4
255 240 245 LavenderBlush1
238 224 229 LavenderBlush2
205 193 197 LavenderBlush3
139 131 134 LavenderBlush4
255 228 225 MistyRose1
238 213 210 MistyRose2
205 183 181 MistyRose3
139 125 123 MistyRose4
240 255 255 azure1
224 238 238 azure2
193 205 205 azure3
131 139 139 azure4
131 111 255 SlateBlue1
122 103 238 SlateBlue2
105  89 205 SlateBlue3
 71  60 139 SlateBlue4
 72 118 255 RoyalBlue1
 67 110 238 RoyalBlue2
 58  95 205 RoyalBlue3
 39  64 139 RoyalBlue4
  0   0 255 blue1
  0   0 238 blue2
  0   0 205 blue3
  0   0 139 blue4
 30 144 255 DodgerBlue1
 28 134 238 DodgerBlue2
 24 116 205 DodgerBlue3
 16  78 139 DodgerBlue4
 99 184 255 SteelBlue1
 92 172 238 SteelBlue2
 79 148 205 SteelBlue3
 54 100 139 SteelBlue4
  0 191 255 DeepSkyBlue1
  0 178 238 DeepSkyBlue2
  0 154 205 DeepSkyBlue3
  0 104 139 DeepSkyBlue4
135 206 255 SkyBlue1
126 192 238 SkyBlue2
108 166 205 SkyBlue3
 74 112 139 SkyBlue4
176 226 255 LightSkyBlue1
164 211 238 LightSkyBlue2
141 182 205 LightSkyBlue3
 96 123 139 LightSkyBlue4
198 226 255 SlateGray1
185 211 238 SlateGray2
159 182 205 SlateGray3
108 123 139 SlateGray4
202 225 255 LightSteelBlue1
188 210 238 LightSteelBlue2
162 181 205 LightSteelBlue3
110 123 139 LightSteelBlue4
191 239 255 LightBlue1
178 223 238 LightBlue2
154 192 205 LightBlue3
104 131 139 LightBlue4
224 255 255 LightCyan1
209 238 238 LightCyan2
180 205 205 LightCyan3
122 139 139 LightCyan4
187 255 255 PaleTurquoise1
174 238 238 PaleTurquoise2
150 205 205 PaleTurquoise3
102 139 139 PaleTurquoise4
152 245 255 CadetBlue1
142 229 238 CadetBlue2
122 197 205 CadetBlue3
 83 134 139 CadetBlue4
  0 245 255 turquoise1
  0 229 238 turquoise2
  0 197 205 turquoise3
  0 134 139 turquoise4
  0 255 255 cyan1
  0 238 238 cyan2
  0 205 205 cyan3
  0 139 139 cyan4
151 255 255 DarkSlateGray1
141 238 238 DarkSlateGray2
121 205 205 DarkSlateGray3
 82 139 139 DarkSlateGray4
127 255 212 aquamarine1
118 238 198 aquamarine2
102 205 170 aquamarine3
 69 139 116 aquamarine4
193 255 193 DarkSeaGreen1
180 238 180 DarkSeaGreen2
155 205 155 DarkSeaGreen3
105 139 105 DarkSeaGreen4
 84 255 159 SeaGreen1
 78 238 148 SeaGreen2
 67 205 128 SeaGreen3
 46 139	 87 SeaGreen4
154 255 154 PaleGreen1
144 238 144 PaleGreen2
124 205 124 PaleGreen3
 84 139	 84 PaleGreen4
  0 255 127 SpringGreen1
  0 238 118 SpringGreen2
  0 205 102 SpringGreen3
  0 139	 69 SpringGreen4
  0 255	  0 green1
  0 238	  0 green2
  0 205	  0 green3
  0 139	  0 green4
127 255	  0 chartreuse1
118 238	  0 chartreuse2
102 205	  0 chartreuse3
 69 139	  0 chartreuse4
192 255	 62 OliveDrab1
179 238	 58 OliveDrab2
154 205	 50 OliveDrab3
105 139	 34 OliveDrab4
202 255 112 DarkOliveGreen1
188 238 104 DarkOliveGreen2
162 205	 90 DarkOliveGreen3
110 139	 61 DarkOliveGreen4
255 246 143 khaki1
238 230 133 khaki2
205 198 115 khaki3
139 134	 78 khaki4
255 236 139 LightGoldenrod1
238 220 130 LightGoldenrod2
205 190 112 LightGoldenrod3
139 129	 76 LightGoldenrod4
255 255 224 LightYellow1
238 238 209 LightYellow2
205 205 180 LightYellow3
139 139 122 LightYellow4
255 255	  0 yellow1
238 238	  0 yellow2
205 205	  0 yellow3
139 139	  0 yellow4
255 215	  0 gold1
238 201	  0 gold2
205 173	  0 gold3
139 117	  0 gold4
255 193	 37 goldenrod1
238 180	 34 goldenrod2
205 155	 29 goldenrod3
139 105	 20 goldenrod4
255 185	 15 DarkGoldenrod1
238 173	 14 DarkGoldenrod2
205 149	 12 DarkGoldenrod3
139 101	  8 DarkGoldenrod4
255 193 193 RosyBrown1
238 180 180 RosyBrown2
205 155 155 RosyBrown3
139 105 105 RosyBrown4
255 106 106 IndianRed1
238  99	 99 IndianRed2
205  85	 85 IndianRed3
139  58	 58 IndianRed4
255 130	 71 sienna1
238 121	 66 sienna2
205 104	 57 sienna3
139  71	 38 sienna4
255 211 155 burlywood1
238 197 145 burlywood2
205 170 125 burlywood3
139 115	 85 burlywood4
255 231 186 wheat1
238 216 174 wheat2
205 186 150 wheat3
139 126 102 wheat4
255 165	 79 tan1
238 154	 73 tan2
205 133	 63 tan3
139  90	 43 tan4
255 127	 36 chocolate1
238 118	 33 chocolate2
205 102	 29 chocolate3
139  69	 19 chocolate4
255  48	 48 firebrick1
238  44	 44 firebrick2
205  38	 38 firebrick3
139  26	 26 firebrick4
255  64	 64 brown1
238  59	 59 brown2
205  51	 51 brown3
139  35	 35 brown4
255 140 105 salmon1
238 130	 98 salmon2
205 112	 84 salmon3
139  76	 57 salmon4
255 160 122 LightSalmon1
238 149 114 LightSalmon2
205 129	 98 LightSalmon3
139  87	 66 LightSalmon4
255 165	  0 orange1
238 154	  0 orange2
205 133	  0 orange3
139  90	  0 orange4
255 127	  0 DarkOrange1
238 118	  0 DarkOrange2
205 102	  0 DarkOrange3
139  69	  0 DarkOrange4
255 114	 86 coral1
238 106	 80 coral2
205  91	 69 coral3
139  62	 47 coral4
255  99	 71 tomato1
238  92	 66 tomato2
205  79	 57 tomato3
139  54	 38 tomato4
255  69	  0 OrangeRed1
238  64	  0 OrangeRed2
205  55	  0 OrangeRed3
139  37	  0 OrangeRed4
255   0	  0 red1
238   0	  0 red2
205   0	  0 red3
139   0	  0 red4
215   7  81 DebianRed
255  20 147 DeepPink1
238  18 137 DeepPink2
205  16 118 DeepPink3
139  10	 80 DeepPink4
255 110 180 HotPink1
238 106 167 HotPink2
205  96 144 HotPink3
139  58  98 HotPink4
255 181 197 pink1
238 169 184 pink2
205 145 158 pink3
139  99 108 pink4
255 174 185 LightPink1
238 162 173 LightPink2
205 140 149 LightPink3
139  95 101 LightPink4
255 130 171 PaleVioletRed1
238 121 159 PaleVioletRed2
205 104 137 PaleVioletRed3
139  71	 93 PaleVioletRed4
255  52 179 maroon1
238  48 167 maroon2
205  41 144 maroon3
139  28	 98 maroon4
255  62 150 VioletRed1
238  58 140 VioletRed2
205  50 120 VioletRed3
139  34	 82 VioletRed4
255   0 255 magenta1
238   0 238 magenta2
205   0 205 magenta3
139   0 139 magenta4
255 131 250 orchid1
238 122 233 orchid2
205 105 201 orchid3
139  71 137 orchid4
255 187 255 plum1
238 174 238 plum2
205 150 205 plum3
139 102 139 plum4
224 102 255 MediumOrchid1
209  95 238 MediumOrchid2
180  82 205 MediumOrchid3
122  55 139 MediumOrchid4
191  62 255 DarkOrchid1
178  58 238 DarkOrchid2
154  50 205 DarkOrchid3
104  34 139 DarkOrchid4
155  48 255 purple1
145  44 238 purple2
125  38 205 purple3
 85  26 139 purple4
171 130 255 MediumPurple1
159 121 238 MediumPurple2
137 104 205 MediumPurple3
 93  71 139 MediumPurple4
255 225 255 thistle1
238 210 238 thistle2
205 181 205 thistle3
139 123 139 thistle4
169 169 169 DarkGrey
169 169 169 DarkGray
0     0 139 DarkBlue
0   139 139 DarkCyan
139   0 139 DarkMagenta
139   0   0 DarkRed
144 238 144 LightGreen
EOCOLORS

        my @cols = split( "\n", $colors );
        my ( $r, $g, $b, $name );
        foreach (@cols) {
            /(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/;
            $r    = $1;
            $g    = $2;
            $b    = $3;
            $name = $4;
            $name =~ s/\s/\_/g;    # cant have space in name
            $RgbCodes{$name} = [ $r / 255, $g / 255, $b / 255 ];
            push @RgbNames, $name;    # want to keep them in order
        }
    }  #end sub setup_rgb_codes {

sub hextorgb_decimal {
    my ($hcode) = @_;
    chomp($hcode);
    $hcode =~ /\#(..)(..)(..)/;
    my @cols = ($1,$2,$3);
    foreach (@cols) {
	$_ =  hex($_);
	$_ /= 255;
    }
    return (@cols);
}

sub get_kdialog_color {
    my $hex_color = `kdialog --getcolor`;
    return undef unless defined $hex_color and $hex_color ne '';
    my @cols = hextorgb_decimal($hex_color);
    my $res =  join(' ',@cols);
    return $res;
}

# bashism !!
sub get_kdialog_openfilename {
    my $file = `kdialog --getopenfilename . 2> /dev/null`;
    chomp($file);
    return $file;
}



####################
    1;

   # use this at some point to set $Hue,$Saturation, $Brightness from
   # Xll color names. but hsv and hsb are not the sme thing. might be a problem.
    sub rgbToHsv {

       # The procedure below converts an RGB value to HSB.  It takes red, green,
       # and blue components (0-65535) as arguments, and returns a list
       # containing HSB components (floating-point, 0-1) as result.  The code
       # here is a copy of the code on page 615 of "Fundamentals of Interactive
       # Computer Graphics" by Foley and Van Dam.

        my $size = 255;
        my ( $red, $green, $blue ) = @_;
        my ( $max, $min, $sat, $range, $hue, $rc, $gc, $bc );

        $max =
            ( $red > $green )
          ? ( ( $blue > $red ) ? $blue : $red )
          : ( ( $blue > $green ) ? $blue : $green );
        $min =
            ( $red < $green )
          ? ( ( $blue < $red ) ? $blue : $red )
          : ( ( $blue < $green ) ? $blue : $green );
        $range = $max - $min;
        if ( $max == 0 ) {
            $sat = 0;
        }
        else {
            $sat = $range / $max;
        }
        if ( $sat == 0 ) {
            $hue = 0;
        }
        else {
            $rc = ( $max - $red ) / $range;
            $gc = ( $max - $green ) / $range;
            $bc = ( $max - $blue ) / $range;
            $hue =
              ( $max == $red ) ? ( 0.166667 * ( $bc - $gc ) )
              : (
                  ( $max == $green ) ? ( 0.166667 * ( 2 + $rc - $bc ) )
                : ( 0.166667 * ( 4 + $gc - $rc ) )
              );
        }
        return ( $hue, $sat, $max / $size );

    }    # end rgbToHsv

    sub make_font_declarations {
        return $topstring;
    }

    # apparantly take a string with escape codes and return  a list
    # of text with hash keys representing the escape codes.
    sub parse_text_string {
        my $string     = shift;
        my @textpieces = ();
        $string =~ s/\\(\d\d\d)/TRIDENSESCAPEDOCTALCODE$1/g;
        $string =~ s/\\\\/TRIDENSESCAPEDBACKSLASH/g;
        while ( $string ne '' ) {
            if ( $string =~ s/^\\([^\s]+)(\s|$)// )
            {    # read a code; escaped, ends w space
                if ( exists $fontcodes{$1} ) {
                    push @textpieces, { FONT => $1 };
                }
                elsif ( exists $spaceshifts{$1} ) {
                    push @textpieces, { SPACE => $1 };
                }
                elsif ( exists $scriptcodes{$1} ) {
                    push @textpieces, { SCRIPT => $1 };
                }
                elsif ( exists $RgbCodes{$1} ) {
                    push @textpieces, { RGB => $1 };
                }
                elsif ( exists $graycodes{$1} ) {
                    push @textpieces, { GRAY => $1 };
                }
                elsif ( exists $hsbcodes{$1} ) {    # not used
                    push @textpieces, { HSB => $1 };
                }
                elsif ( exists $Symcodes{$1} ) {
                    push @textpieces, { SYM => $1 };
                }
                elsif ( exists $Symaliases{$1} )
                {    # put the Adobe code in place of the alias
                    push @textpieces, { SYM => $Symaliases{$1} };
                }
                else {
                    herror "Unknown code '$1' in string";
                }
            }
            if ( $string =~ s/^([^\\]+)// ) {
                my $s = $1;
                $s =~ s/TRIDENSESCAPEDBACKSLASH/\\\\/g;
                $s =~ s/TRIDENSESCAPEDOCTALCODE(\d\d\d)/\\$1/g;
                $s =~ s/\)/\\\)/g;    # PS needs these escaped
                $s =~ s/\(/\\\(/g;
                push @textpieces, { TEXT => $s };
            }
        }
        return @textpieces;
        exit(0);
    }

    sub set_total_string_width {
        my @textpieces = @_;
        my $outst      = '';
        my ($i);
        my $scriptstate = '-';    # normal level
        my $sc          = 0;
        for ( $i = 0 ; $i < @textpieces ; $i++ ) {
            if ( exists $textpieces[$i]->{FONT} ) {
                $outst .=
                  get_font_name( $textpieces[$i]->{FONT}, $scriptstate )
                  . " setfont\n";
            }
            elsif ( exists $textpieces[$i]->{TEXT} ) {
                $outst .= "(" . $textpieces[$i]->{TEXT} . ") stringwidth pop\n";
                $sc++;

            }
        }
        for ( $i = 0 ; $i < $sc - 1 ; $i++ ) { $outst .= ' add '; }
        $outst .= " /totalstringwidth exch def\n";
        return $outst;
    }

    sub print_centeredx {
        my ( $y, $x, $text ) = @_;
        print_mult_font_text( $y, $x,
            "$x totalstringwidth -2 div add $y moveto\n", $text );
    }

    # not currently used
    # use paper coordinates (inches)
    sub print_centeredx_new {
        my ( $y, $x, $text ) = @_;
        print_mult_font_text( $y, $x,
            "$x totalstringwidth -2 div add $y moveto\n", $text );
    }

    # print such that text is all to the left of current point
    sub print_to_left {
        my ( $y, $x, $text ) = @_;
        print_mult_font_text( $y, $x,
            "$x totalstringwidth -1 mul add $y moveto\n", $text );
    }

    # print to the left of point and rotated 90 degrees.
    sub print_to_left_rot {
        my ( $y, $x, $text ) = @_;
        print_mult_font_text( $y, $x,
            "$x $y moveto\n90 rotate\n totalstringwidth -2 div 0 rmoveto\n",
            $text );
    }

    # PS code to get height of character $char and
    # store result in PS variable $psvar
    # the name in the source code of $psvar was 'baseline'
    # This character height is only for superscripts. So we correct a few
    # of the grossest errors, s.a. substituting 'n' for 'h' because the
    # riser on the h is tall and makes the sscript too high.
    sub get_character_height {
        my ( $char, $psvar ) = @_;
        $SScriptScale = .95 unless defined $SScriptScale;
        my %charmap = ( h => 'n' );
        $char = $charmap{$char} if exists $charmap{$char};
        return "gsave 0 0 moveto ($char) false charpath flattenpath pathbbox\n"
          . "dup /$psvar exch $SScriptScale mul def exch pop exch sub /charheight exch def pop grestore\n";
    }

    # This is really a mess and needs to be cleaned up!
    sub print_mult_font_text {
        my ( $y, $x, $posn, $text ) = @_;
        my %lastchar = ( '^' => 'a', '^2' => 'a', '_' => 'a' );
        my %lastfont;
        my @text;
        if ( $LatexRun == TRUE ) {
            @text = parse_text_string($text) 
#            $text =~ s/\\/\\\\/g;    # double the backslash
#            @text = ( { TEXT => $text } );
        }
        else {
            @text = parse_text_string($text) 
        }
        unshift( @text, { FONT => 'rm' } );
        my $scriptstate = '-';
        my $curfont     = 'rm';
        my $i;
        my $sc    = 0;
        my $outst = "gsave\n";
        $outst .= set_total_string_width(@text) . $posn;
        $outst .= "Mainfont setfont\n";
        $outst .= get_character_height( 'a', 'supshift' )
          ;    # to prevent error when user uses ^2 first

        for ( $i = 0 ; $i < @text ; $i++ ) {
            if ( exists $text[$i]->{FONT} ) {
                my $fullfont = get_font_name( $text[$i]->{FONT}, $scriptstate );
                $outst .= "$fullfont setfont\n";
                $curfont = $text[$i]->{FONT};
                $lastfont{$scriptstate} = $fullfont;
            }
            elsif ( exists $text[$i]->{SCRIPT} ) {
                my $scr = $text[$i]->{SCRIPT};

                #	    $scr = '' if $scr eq '-';
                if ( $scriptstate ne '-' ) {    # move back
                    $outst .= $scriptshifts{$scriptstate}->{OUT} . " rmoveto\n";
                }
                $scriptstate = $scr;
                if ( $scr eq '^' ) {    # get last normal character height
                    if ( exists $lastfont{'-'} ) {
                        $outst .=
                          $lastfont{'-'} . " setfont % use prev norm char\n";
                    }
                    $outst .=
                      get_character_height( $lastchar{'-'}, 'supshift' );
                }
                elsif ( $scr eq '^2' ) {
                    if ( exists $lastfont{'^'} ) {
                        $outst .=
                          $lastfont{'^'} . " setfont % use prev norm char\n";
                    }
                    $outst .=
                      get_character_height( $lastchar{'^'}, 'ssupshift' );
                    $outst .= get_character_height( 'a', 'supshift' )
                      unless exists $lastchar{'-'};
                    $outst .= "/ssupshift ssupshift supshift add def\n"
                      ;    # add the shifts
                }
                $outst .= $scriptshifts{$scriptstate}->{IN} . " rmoveto\n"
                  unless $scriptstate eq '-';

               #	    $outst .= "0 supshift rmoveto\n" unless $scriptstate eq '';
                my $fullfont = get_font_name( $curfont, $scriptstate );
                $outst .= "$fullfont setfont\n";
                $lastfont{$scriptstate} = $fullfont;
            }
            elsif ( exists $text[$i]->{SPACE} ) {
                my $xs = $spaceshifts{ $text[$i]->{SPACE} }->{X};
                my $ys = $spaceshifts{ $text[$i]->{SPACE} }->{Y};
                $outst .= "(a) stringwidth pop dup\n";
                $outst .= "$xs mul exch $ys mul rmoveto\n";
            }
            elsif ( exists $text[$i]->{RGB} ) {
                $outst .=
                  join( " ", @{ $RgbCodes{ $text[$i]->{RGB} } } )
                  . " setrgbcolor\n";
            }
            elsif ( exists $text[$i]->{HSB} ) {
                $outst .=
                  join( " ", @{ $hsbcodes{ $text[$i]->{RGB} } } )
                  . " sethsbcolor\n";
            }
            elsif ( exists $text[$i]->{GRAY} ) {
                $outst .= $graycodes{ $text[$i]->{GRAY} } . " setgray\n";
            }
            elsif ( exists $text[$i]->{SYM} ) {
                my $fullfont = get_font_name( 'sym', $scriptstate );
                $outst .= "$fullfont setfont\n";
                $lastfont{$scriptstate} = $fullfont;
                $outst .= "(\\" . $Symcodes{ $text[$i]->{SYM} } . ") show\n";
                $lastchar{$scriptstate} = "\\" . $Symcodes{ $text[$i]->{SYM} };
                $outst .=
                  get_font_name( $curfont, $scriptstate ) . " setfont\n";
            }
            elsif ( exists $text[$i]->{TEXT} ) {
                $lastchar{$scriptstate} =
                  substr( $text[$i]->{TEXT}, -1 )
                  ;    # save last char of each script level
                $outst .= "(" . $text[$i]->{TEXT} . ") show\n";
                $sc++;
            }
        }
        $outst .= "grestore\n";
        return $outst;
    }

    # not used
    sub print_underline {
        my ( $y, $Xlo, $Xhi ) = @_;
        return
" gsave .2 1 1 sethsbcolor $Xlo $y moveto $Xhi $y lineto stroke grestore\n";
    }

}    # end context for routines for showing text in mixed fonts

#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  PostScript plot writing. Data and text and so forth generated above is used        #
#  here.                                                                               #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#


# context for routines that generate the PostScript code.
#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=
{

    # These strings contain PostScript code to
    my (
        $keycolorboxes_com,    # create bars in key to plot
        $drawkey_com,          # draw the key
        $trihex_com,           # draw triangular lattice in hexes
        $alltrihex_com,        # draw triangular lattices in entire plot
        $landscape_com,        # render entire plot in landscape mode
        $font_declarations_com
    ) = ( '', '', '', '', '' );

    my (
        $prolog, $data,  $yticks, $xticks, $title,
        $axes,   $marks, $xlabel, $ylabel
    ) = ( '', '', '', '', '', '', '', '', '', '' );

    # These postscript commands are interspersed in the prolog.
    sub create_interspersed_postscript {
        $keycolorboxes_com = $drawkey_com = '';
        $keycolorboxes_com = make_key_color_boxes() if $DrawKey == TRUE;
        $drawkey_com = 'drawkey' if $DrawKey == TRUE;
        $trihex_com = $alltrihex_com = '';
        if ( $TriHexDraw == 1 or $TriHexDraw == 2 ) {
            $trihex_com = 'pcx pcy trihex';
        }
        if ( $TriHexDraw == 2 ) {
            $alltrihex_com = 'alltrihex';
        }
        if ( $LandScape == TRUE ) {
            $landscape_com = make_landscape_com();
        }
        else {
            $landscape_com = '';
        }
        $font_declarations_com = make_font_declarations();
    }

    # must call create_interspersed_postscript above first.
    sub set_prolog_string {
        $prolog = make_prolog( $keycolorboxes_com, $drawkey_com, $trihex_com,
            $alltrihex_com, $landscape_com, $font_declarations_com );
    }

    sub create_post_prolog_strings {
        my $boxwidth = $XBhi - $XBlo;
        $data   = make_data_postscript();
        $yticks = make_yticks();
        $xticks = make_xticks();
        $title  = '';                       # in case it has been set once
        $title  = make_title() if defined $Title and $Title ne '';
        $axes   = draw_axes();
        $marks  = draw_marks();
        $xlabel = '';
        my $sh = $XLabelXOffset;
        $xlabel =
          print_centeredx( $YBlo - ( $boxwidth * $XLabelYOffset * $FontScale ),
            ( ( 1 - $sh ) * $XBlo + ( 1 + $sh ) * $XBhi ) / 2, $XLabel )
          if $XLabel ne '';
        $ylabel = '';
        $sh     = $YLabelYOffset;

        if ( $YLabel ne '' ) {
            if ( $RotateYLabel == TRUE ) {
                $ylabel = print_to_left_rot(
                    ( ( 1 - $sh ) * $YBlo + ( 1 + $sh ) * $Yhi ) / 2,
                    $XBlo - ( $boxwidth * $YLabelXOffset * $FontScale ),
                    $YLabel );
            }
            else {
                $ylabel = print_to_left(
                    ( ( 1 - $sh ) * $YBlo + ( 1 + $sh ) * $Yhi ) / 2,
                    $XBlo - ( $boxwidth * $YLabelXOffset * $FontScale ),
                    $YLabel );
            }
        }

    }

    sub make_entire_postscript_file {
	my $drawframe = '';
	$drawframe = 'drawframe' if $FrameDraw == TRUE;
        my $string = <<"EPS";
$prolog
$alltrihex_com
$data
grestore  % pops clip path
$drawframe
$axes
ticklabelfont setfont
$xticks
$yticks
$title
$xlabel
$ylabel
$marks
$drawkey_com
$ShowPage
%%EOF
EPS

        return $string;

    }

    #
    sub print_ps_file {
        my $outfile = shift;
        open PSH, ">$outfile"
          or die "Unable to open the file '$outfile' for writing";
        print PSH make_entire_postscript_file();
        close(PSH);
    }    # end print_ps_file(...

}    # end context for routines that generate the PostScript code.

#*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

# Create nearly all the postscript code.
sub prepare_ps_file {
    set_polygon_params();
    setup_mixed_fonts();
    set_initial_top_matter();
    create_interspersed_postscript();
    set_prolog_string();
    create_post_prolog_strings();
}

=begin comment

The eps file is altered in the same way that epstopdf alters it:
The bounding box info is used to translate the plot so that one
corner is at 0,0. The bounding box is then rewrittend accordingly
and
   <</PageSize [x y]>> setpagedevice line
is added to be exactly the size of the bounding box. But this line doesnt
seem to be useful. In converting the eps to pdf, the gs arguments -dDEVICEWIDTHPOINTS
(and height) are essential.

=end comment

=cut

=begin comment


    gsave
    1 setlinewidth
    newpath
    100.173997 200.43399 moveto
    100.173997 590.989982  lineto
    609.493982 590.989982 lineto
    609.493982 200.433994 lineto

=end comment


=cut

sub write_output {
    verbose "Writing output...";
    $BoundingBox = '';
    if ( $WriteBBox == TRUE or $PSFormat eq 'eps' or $PSFormat eq 'pdf' ) {
        if ( not defined $PostScriptInterpreter
            or $PostScriptInterpreter eq '' )
        {
            herror("Can't create eps,pdf, and bounding box. No ghostscript");
        }
        verbose "PostScript Pass 1";
        print_ps_file( $Psfile . ".tmp" );
        my $bboxcom = "$BBoxCommand \"$Psfile.tmp\" $Getstderr";
        verbose $bboxcom;
        $BoundingBox = `$bboxcom`;
        chomp($BoundingBox);
        my @lines = split( '\n', $BoundingBox );

        foreach (@lines) {
            if ( not /^\%\%/ ) {
                herror "gs is failing to return bounding box";
                return;
            }
        }
        my ( $i, @outline );
        my ( $xwidth, $ywidth, $ox1, $oy1 );

        # loop over two items: bounding box and hires bounding box
        for ( $i = 0 ; $i < 2 ; $i++ ) {  # add some padding to the bounding box
            my (@bnums) = split( /\s+/, $lines[$i] ); # bnums[0] is not a number
            $bnums[3] += $BoundingBoxPad;
            $bnums[4] += $BoundingBoxPad;
            $bnums[1] -= $BoundingBoxPad;
            $bnums[2] -= $BoundingBoxPad;
            if ( $i == 0 ) {
                $xwidth = $bnums[3] - $bnums[1];
                $ywidth = $bnums[4] - $bnums[2];
                $ox1    = $bnums[1];
                $oy1    = $bnums[2];
                if ( $ox1 < 0 or $oy1 < 0 ) {
                    verbose(
                        "Plot too big, rescaling PlotWidth from $PlotWidth");
                    $PlotWidth *= 0.9;
                    prepare_ps_file();
                    write_output();
                    check_viewer();
                    return undef;
                }
                $bnums[1] = 0;
                $bnums[2] = 0;
                $bnums[3] = $xwidth;
                $bnums[4] = $ywidth;
            }
            $outline[$i] = join( " ", @bnums );

            $WhiteBox = '';
            if ( $WhiteBoxDraw == TRUE ) {
                $WhiteBox = <<"WHITEEOL";
                       % draw white box to keep foreign bbox from clobbering margins
		       gsave
                       1 setlinewidth
                       newpath
                       $bnums[1] $bnums[2] moveto
                       $bnums[1] $bnums[4] lineto
                       $bnums[3] $bnums[4] lineto
                       $bnums[3] $bnums[2] lineto
                       closepath
                       1 setgray
                       stroke
                       grestore

WHITEEOL
            }    # end  if ($WhiteBoxDraw == TRUE)
        }
        $BoundingBox   = $outline[0] . "\n" . $outline[1];
        $BoundingBox   = "\n" . $BoundingBox;
        $PageSize      = "\n";
        $TranslatePlot = '';

        verbose "PSFormat is $PSFormat";
        if ( $PSFormat eq 'ps' ) {
            set_prolog_string();
            $Outfile = $Psfile unless defined $Outfile;
            print_ps_file($Outfile);
        }
        if ( $PSFormat eq 'eps' or $PSFormat eq 'pdf' ) {
            verbose "PostScript Pass 2, writing eps";
            $DocTypeLine = "%!PS-Adobe-3.0 EPSF-3.0";

#  this PageSize seem not useful and screw up epstopdf probably because they are wrong
#	    $PageSize = "\n<< /PageSize [$xwidth $ywidth] >> setpagedevice\n";
            $TranslatePlot = " -$ox1 -$oy1 translate";
            $ShowPage      = '';
            $PaperComments = '';
            set_prolog_string();
            if ( $PSFormat eq 'eps' ) {
                $Outfile = $Epsfile unless defined $Outfile;
                print_ps_file($Outfile);
            }
            else {    # for pdf file
                print_ps_file("$Psfile.tmp");
            }
        }
        if ( $PSFormat eq 'pdf' ) {
            verbose "PostScript Pass 3, writing pdf";
            verbose "Plot translation for pdf: $TranslatePlot";
            $Outfile = $Pdffile unless defined $Outfile;
            my $com =
"$PostScriptInterpreter -q -dBATCH -dNOPAUSE -sFONTPATH='$FontPath' $PostScriptInterpreterOptions "
              . "-sOutputFile=\"$Outfile\" -sDEVICE=pdfwrite -dDEVICEWIDTHPOINTS=$xwidth "
              . "-dDEVICEHEIGHTPOINTS=$ywidth \"$Psfile.tmp\"";
            verbosesys $com;
            if ( $LatexRun == TRUE ) {
                $com = "$PdfToIpe \"$Pdffile\" &> /dev/null";
                verbosesys $com;
                $com = "$IpeToIpe -pdf \"$Ipefile\" &> /dev/null";
                verbosesys $com;
            }
        }
    } # end   if ( $WriteBBox == TRUE or $PSFormat eq  'eps' or $PSFormat eq  'pdf' )
    else {
        $Outfile = $Psfile unless defined $Outfile;
        verbose "Writing plain PostScript file $Outfile";
        print_ps_file($Outfile);
    }
    verbosesys "rm -f \"$Psfile" . ".tmp\"";
    signal_viewer($Outfile);

    # end of program
}

#========================================================
# Print the PostScript Prolog and topmatter. This is the
# bulk of the generated PostScript code.
# I include perl style comments (beginning with #) within the string.
# These are stripped out at the end of this routine. The could have been
# PS comments with %, but why write them into the output file?
sub make_prolog {

    my ( $keycolorboxes_com, $drawkey_com, $trihex_com, $alltrihex_com,
        $landscape_com, $font_declarations_com )
      = @_;

    my $lengthofside =
      $LengthOfSide * ( $Xhi - $Xlo ) / ( $DXhi - $DXlo );   # correct scaling ?
    my $xlengthofside = $XLengthOfSide * ( $Xhi - $Xlo ) / ( $DXhi - $DXlo );
    my $ylengthofside = $YLengthOfSide * ( $Yhi - $Ylo ) / ( $DYhi - $DYlo );
    my $string;
    my $square_root_of_three = sprintf( "%.6f", sqrt(3) / 2 );
#    my $xlo_in_window_coords = data_to_window_transform_x($XBlo);
#    my $xhi_in_window_coords = data_to_window_transform_x($XBhi);
#    my $ylo_in_window_coords = data_to_window_transform_y($YBlo);
#    my $yhi_in_window_coords = data_to_window_transform_y($YBhi);
    my $x_eq_0_in_window_coords = data_to_window_transform_x(0);
    my $y_eq_0_in_window_coords = data_to_window_transform_y(0);

### A very long string follows
    $string = <<"TOPEOL";
$DocTypeLine$BoundingBox$PageSize$TranslatePlot
%%Title: (Density plot of $Infile)
%%Creator: tridens
%%Orientation: Portrait
%%Pages: 1$PaperComments
%%Magnification: 1.0000
%%EndComments

% why do I need a namespace ?
%/PolyDensDict 200 dict def
%PolyDensDict begin

$WhiteBox

/in {72 mul} def  %  convert points to inches
/cm {28 mul} def  %  convert points to cm

%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% assume letter size
/pagewidth 8.5 in def
/pageheight 11 in def

$landscape_com

% going to scale poly up from one point sides, so start with
% desired width of plot in points ( ie  points times cm)
/plotwidth $PlotWidth cm def
% limits of data points  in poly units, ie physical units
/xlo $Xlo def
/xhi $Xhi def
/ylo $Ylo def
/yhi $Yhi def
% buffer around plot in polygon units
/ybuf $Ybuf def
/xbuf $Xbuf def

% length in plot units of poly side
/polysidelength $lengthofside def
/xpolysidelength $xlengthofside def
/ypolysidelength $ylengthofside def
% how much to rotate polygons
/polyrotation $Rotation def
/polyrotationtwo $Rotation2 def
% choose which polygon to draw
/whichpoly {
     $Polypath
} bind def


% factor to scale default polygon and plot boundary linewidths
% and fonts
/polylinescale $PolyLineWScale def
/framelinescale $FrameLineWScale def
/keylinescale $KeyLineWScale def
/ticklinescale $TickLineWScale def
/ticklengthscale $TickLengthScale def
/tickfontscale $TickFontScale $FontScale mul def
/keyfontscale $KeyFontScale  $FontScale mul def
/axisfontscale $AxisFontScale  $FontScale mul def

% choose painting method
% fill or fill-and-stroke
/polypaint {
    $WhichFill
}  def


% plot limits with buffers around data
/xblo $XBlo def
/yblo $YBlo def
/xbhi $XBhi def
/ybhi $YBhi def

%/xblo xhi xlo sub xbuf mul xlo exch sub  def
%/xbhi xhi xlo sub xbuf mul xhi add  def
%/yblo yhi ylo sub ybuf mul ylo exch sub  def
%/ybhi yhi ylo sub ybuf mul yhi add  def

% dimensions of frame in poly  units
/frameheight ybhi yblo sub def
/framewidth  xbhi xblo sub def

% units of framewidth
/bw { framewidth mul } def
%/bh { frameheight mul } def % not used

% plotwidth and framewidth both measure the same
% length, but in different units. plotwidth is in
% points (natural ps units), and framewidth is in physical (data)
% units. We will rescale so that ps units are physical units
/polyscale plotwidth framewidth div  def

% looks like plotheight is not used
/plotheight ybhi yblo  sub  xbhi xblo sub div
           plotwidth mul  def
% center of frame around plot in cm, relative
% to the origin for plotting data.
/ycent ybhi yblo add 2 div polyscale mul def
/xcent xbhi xblo add 2 div polyscale mul def
% center of US letter
% graphics origin is origin of data. Given this, we
% center plot. Except that labels and key are not included in computation
pagewidth 2 div  xcent sub pageheight 2 div  ycent sub translate

/polylinewidth 1 20 div polylinescale mul def
/framelinewidth .001 bw framelinescale mul def
/keylinewidth .0025 bw keylinescale mul def
/axislinewidth .002 bw $AxisLineWScale mul def
/ticklinewidth .002 bw ticklinescale mul def
/ticklength .01 bw  ticklengthscale mul def
/tickfontheight  .025 bw  tickfontscale mul def
/keyfontheight  .025 bw  keyfontscale mul def
/axislabelfontheight  .04 bw  axisfontscale mul def
/numberpolyfontheight .5 $NumberPolyFontScale mul def


$font_declarations_com
/ticklabelfont /$PlainFontname  findfont tickfontheight scalefont def 
/keyfont /$PlainFontname  findfont keyfontheight scalefont def 
/keysymfont /Symbol  findfont keyfontheight scalefont def 
/axislabelfont /$PlainFontname findfont axislabelfontheight scalefont def
/numberpolyfont /$PlainFontname  findfont numberpolyfontheight scalefont def 

% x point font is actually shorter than x points.
% dividing by this gives approximate height
/rfontheight 1.333 def

% 
/rtickfontheight tickfontheight rfontheight div def
/rkeyfontheight keyfontheight rfontheight div def
/rnumberpolyfontheight numberpolyfontheight rfontheight div def

%/ticklabeloffset framewidth 60 div def
/ticklabeloffset $TickLabelOffset $FontScale mul  bw  def

/sst 3 sqrt 2 div def
/st  3 sqrt def

% choose one of setgray or sethsbcolor
/polyfill {
    $SetDensityColor
    fill
} bind def


/Spolystfill {
    gsave
    currentpoint translate
    $SetDensityColor
    hexpoly ufill
    0 setgray 
    hexpoly ustroke
    grestore
} bind  def

/polystfill {
    gsave
    polyfill
    grestore
    0 setgray 
    stroke
} bind  def


% This draws the polygon
% not used apparantly
/Spd {
    /pcy exch def
    /pcx exch def    
    gsave
    newpath
    pcx pcy moveto % move to center of poly
    polysidelength polysidelength  scale
    polyrotation rotate	
    polypaint
    grestore
    $trihex_com
} def

% This draws the polygon
% This is the favored routine.
/pd {
    /pcy exch def
    /pcx exch def    
    gsave
    newpath
    pcx pcy moveto % move to center of poly
    xpolysidelength ypolysidelength  scale
    polyrotation rotate	
    whichpoly  % add poly sides to path
    closepath
    polypaint
    grestore
    $trihex_com
} def

/pdr {
    /pcy exch def
    /pcx exch def    
    gsave
    newpath
    pcx pcy moveto % move to center of poly
    polysidelength polysidelength  scale
    polyrotationtwo rotate	
    whichpoly  % add poly sides to path
    closepath
    polypaint
    grestore
    $trihex_com
} def

/pdnsci {
  /polycy exch def
  /polycx exch def
  polycx polycy pd
  polycx polycy numberpolysci % pop 2
} def

/pdnfl {
  /polycy exch def
  /polycx exch def
  polycx polycy pd
  polycx polycy  numberpoly  % pop 1
} def

/numberpoly {
 gsave
 numberpolyfont setfont
 moveto
 dup
 stringwidth pop
 2 div  neg  rnumberpolyfontheight 2 div  neg  rmoveto
 $NumberPolyGray setgray
 show
 grestore
}def

% smaller version
/pdnflsm {
  /polycy exch def
  /polycx exch def
  polycx polycy pd
  polycx polycy  numberpolysm  % pop 1
} def

%
/numberpolysm {
 gsave
 numberpolyfont setfont
 moveto
 $NumberPolySciScale  $NumberPolySciScale  scale
 dup
 stringwidth pop
 2 div  neg  rnumberpolyfontheight 2 div  neg  rmoveto
 $NumberPolyGray setgray
 show
 grestore
}def

/numberpolysci {
 gsave
 moveto
 exch
 dup
 stringwidth pop
 div 2 neg 0 rmoveto
 0 setgray
 exch
 drawscinot
 grestore
}def

/Shexpoly {
    ucache
    -1 -$square_root_of_three 1 $square_root_of_three setbbox
    0 0 moveto
    .5 $square_root_of_three rmoveto
    .5 -$square_root_of_three  rlineto
    -.5 -$square_root_of_three  rlineto
    -1  0  rlineto
    -.5 $square_root_of_three rlineto
    .5  $square_root_of_three rlineto
} cvlit def


/hexpoly {
    .5 //sst rmoveto
    .5 //sst neg rlineto
    -.5 //sst neg rlineto
    -1  0  rlineto
    -.5 //sst rlineto
    .5  //sst rlineto
} bind def

% draw triangular lattice lines on top of
% hexagons.
/trihex {
   gsave
   newpath
   moveto
   currentpoint translate
   polysidelength polysidelength  scale
   polyrotation rotate	    

   0 //sst moveto
   0 //sst neg lineto
   0 0 moveto
   60 rotate
   0 //sst moveto
   0 //sst neg lineto
   60 rotate
   0 //sst moveto
   0 //sst neg lineto

   closepath
   currentlinewidth .3 mul setlinewidth
   $LatticeGray setgray stroke
   grestore
} bind def

% draw triangular lattice over entire plot
% clipping path is set, however.
/bwidth xbhi xblo sub def
/bheight ybhi yblo sub def

/alltrihex {
   gsave
   newpath
   0 0 moveto
   30 rotate
   3 { % repeat
    0 1.5  $lengthofside mul  //xbhi //bwidth add    {
       dup
       0 moveto
       0 //ybhi //bheight add rmoveto
       0 //ybhi //bheight add 2 mul neg rlineto
       neg
       0 moveto
       0 //ybhi //bheight add rmoveto
       0  //ybhi //bheight add 2 mul neg rlineto
    } for
    60 rotate  
   } repeat
   closepath
   currentlinewidth .3 mul setlinewidth
   $LatticeGray setgray stroke
   grestore
} def


/trianglepoly {
    0 1 st div rmoveto
    .5 //sst neg  rlineto
    -1 0 rlineto
} bind def

/squarepoly { % stack empty i guess
    .5 .5 rmoveto
    0 -1  rlineto
    -1 0 rlineto
    0  1 rlineto
} bind def 


/circlepoly {  % stack empty
  currentpoint 1 0 360 arc
} bind def 


/drawframe {
    gsave
    framelinewidth setlinewidth
    newpath
    xblo yblo moveto
    xblo ybhi lineto
    xbhi ybhi lineto
    xbhi yblo lineto
    closepath
    0 setgray
    stroke
    grestore
} def

/drawxaxis {
   gsave
   axislinewidth setlinewidth
   newpath
   xblo  $y_eq_0_in_window_coords  moveto
   xbhi  $y_eq_0_in_window_coords  lineto
   [ .02 bw .01 bw  ] 0 setdash
   stroke
   grestore
} def

/drawyaxis {
   gsave
   axislinewidth setlinewidth
   newpath
   $x_eq_0_in_window_coords yblo  moveto
   $x_eq_0_in_window_coords ybhi  lineto
   [ .02 bw .01 bw  ] 0 setdash
   stroke
   grestore
} def

% draw tick at bottom
/drawbtick {
    gsave
    ticklinewidth setlinewidth
    /ytick exch def
    /xtick exch def
    /labytick exch def
    /labxtick exch def
    newpath
    xtick ytick moveto
    0 ticklength rlineto
    closepath
    0 setgray
    stroke
    labxtick labytick moveto
    dup   % label
    stringwidth pop
    neg 2 div   rtickfontheight neg 
    ticklabeloffset sub  rmoveto
%    neg 2 div   0  rmoveto
    show  % pop label
    grestore
} def

% draw tick at bottom
/drawttick {
    gsave
    ticklinewidth setlinewidth
    /ytick exch def
    /xtick exch def
    /labytick exch def
    /labxtick exch def
    newpath
    xtick ytick moveto
    0 ticklength neg rlineto
    closepath
    0 setgray
    stroke
    labxtick labytick moveto
    dup   % label
    stringwidth pop
%    neg 2 div   tickfontheight 1.2 div  rmoveto
    neg 2 div   ticklabeloffset  rmoveto
    show  % pop label
    grestore
} def

% draw tick at left
/drawltick {
    gsave
    ticklinewidth setlinewidth
    /ytick exch def
    /xtick exch def
    /labytick exch def
    /labxtick exch def
    newpath
    xtick ytick moveto
    ticklength 0 rlineto
    closepath
    0 setgray
    stroke
    labxtick labytick moveto
    dup   % label
    stringwidth pop
    neg  ticklabeloffset sub tickfontheight neg 3 div  rmoveto
%    neg  0   rmoveto
    show  % pop label
    grestore
} def

% draw tick at right
/drawrtick {
    gsave
    ticklinewidth setlinewidth
    /ytick exch def
    /xtick exch def
    /labytick exch def
    /labxtick exch def
%    /ticklabel exch def
    newpath
    xtick ytick moveto
    ticklength neg 0 rlineto
    closepath
    0 setgray
    stroke
    labxtick labytick moveto
    ticklabeloffset tickfontheight neg 3 div  rmoveto
    show
%    ticklabel show  % pop label
    grestore
} def

% draw some text centered and paraellel to x-axis
/XCenterText {
  /Text exch def
  /Position exch def
  /TextScale exch def
  gsave
  0 setgray
  /$PlainFontname findfont .04 bw TextScale mul  scalefont setfont
  newpath
  xbhi xblo add  2 div
  yblo Position bh add
  moveto
  Text stringwidth  pop neg 2 div 0 rmoveto
  Text show  
  grestore
} def

# Draw a number in scientific notation.
# Uses a multiplication symbol from the symbol font
/drawscinot {
  /exponent exch def
  /mantissa exch def
  (A) stringwidth pop
  /charsh exch 0 mul def
  mantissa show 
  ( ) show
  keysymfont setfont
  (\264) show
  keyfont setfont
  ( ) show
  charsh  .4 rkeyfontheight mul rmoveto 
  gsave 1.5 1.5 scale 
  grestore
  0  -.4 rkeyfontheight mul rmoveto 
  charsh 2 div 0 rmoveto (10) show
%  mantissa stringwidth pop
%  .8 rfontheight mul rmoveto
  0  $KeyExpRaise rkeyfontheight mul rmoveto
  gsave   
  $ExponentScale $ExponentScale scale
  exponent show
  grestore
} def

# This draws the same but with a dot for multiplication.
# This should be an optional alternate, but is simply not
# used right now.
/drawscinotdot {
  /exponent exch def
  /mantissa exch def
  (A) stringwidth pop dup
  /charsh exch .4 mul def
  /dotrad exch .1 mul def
  mantissa show 
  charsh  .4 rkeyfontheight mul rmoveto 
  gsave 1.5 1.5 scale 
  currentpoint dotrad 0 360 arc fill
%  (.) show 
  grestore
  0  -.4 rkeyfontheight mul rmoveto 
  charsh 2 div 0 rmoveto (10) show
%  mantissa stringwidth pop
%  .8 rfontheight mul rmoveto
  0  $KeyExpRaise rkeyfontheight mul rmoveto
  gsave   
  $ExponentScale $ExponentScale scale
  exponent show
  grestore
} def

/keywidth $KeyWidth bw  def
/keyheight frameheight $KeyHeight mul def
/numkeybars $NumKeyBars def

/keybarheight keyheight numkeybars div def
/keyxpos $KeyXOffset $FontScale mul bw  xbhi add  def
%/keyypos ybhi yblo add 2 div def
/keyypos  yblo $KeyYOffset bw add  def

/drawkey {
  gsave
  keyfont setfont
  keylinewidth setlinewidth
  keyxpos keyypos moveto
  0 setgray
  0 keyheight rlineto
  keywidth 0  rlineto
  0 keyheight neg rlineto
  closepath
  stroke
  $keycolorboxes_com
  grestore
} def

%%EndProlog

% set scale so ps units = input data units
polyscale polyscale scale
polylinewidth setlinewidth

# clip off data that lies outside our range
# does not seem to have an effect on efficiency when not clipping
gsave
newpath
xlo ylo moveto xlo yhi lineto xhi yhi lineto
xhi ylo lineto closepath clip
ticklabelfont setfont


TOPEOL

    # strip perl comments
    $string =~ s/\n(#[^\n]*\n)+/\n/g;

    return $string;
}    # end sub make_prolog

# END  Print the PostScript Prolog and topmatter. This is the
#========================================================

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Tick mark generating routines.                                                     #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#



#============================================================================

=begin comment

 Routines for computing ticks; These routines are independent of the
 rest of the program. These routines are a perl translation 
 (and modification) of  Numeric Python routines. The python routines carry
 the following copyright notice.

#--------------------------------------------------------------------------------
#
#  Helper functions for calculating axis tick related values (i.e. bounds and
#  intervals)
#  Written by: David C. Morrill (based on similar routines written by Eric Jones)
#
#  Date: 07/10/2002
#
#  (c) Copyright 2002 by Enthought, Inc.
#
#--------------------------------------------------------------------------------

=end comment

=cut

=begin comment

Find locations for axis tick marks.

Calculate the location for tick marks on an axis. data_low and data_high
specify the maximum and minimum values of the data along this axis.
bounds_low, bound_high and tick_intervalspecify how the axis end points
and tick interval are calculated. An array of tick mark locations is
returned from the function.  The first and last tick entries are the
axis end points.

        data_low,   The maximum and minimum values of the data long this axis.
        data_high:  If any of the bound settings are 'auto' or 'fit', the axis
                    traits are calculated automatically from these values.
        bound_low:  Can be 'auto', 'fit' or a number.
        bound_high: If a number,the axis trait is set to that value.  If the
                    value is 'auto', the trait is calculated automatically.
                    The value can also be 'fit' in which case the axis end
                    point is set equal to the corresponding data_low/data_high
                    value.
        tick_interval: Can be 'auto' or a positve number specifying the length
                    of the tick interval, or a negative integer specifying the
                    number of tick intervals.

        $magic_arr, $division_arr.  References to arrays. magic_arr is the list of
                    numbers that can be the basic tick interval. Only the mantissa is
		    given in this list. division_arr is a list of possible numbers of
		    ticks. (I think the max+1 and min-1 are also possible.) auto_interval
		    routine picks the mantissa and number of ticks pair that most nearly
		    fills the data window with ticks.

=end comment

=cut

sub auto_ticks {
    my (
        $data_low,      $data_high, $bound_low, $bound_high,
        $tick_interval, $magic_arr, $division_arr
    ) = @_;

    # check whether TRUE and FALSE mean the same here as in the rest of the code
    my (
        $rng,        $intervals,   $atFALSE,      $delta,
        $auto_lower, $auto_upper,  $start,        $end,
        @ticks,      $is_auto_low, $is_auto_high, $lower,
        $upper
    );

    my ($i);

    $atFALSE = ( 1 == 0 );

    $is_auto_low  = ( $bound_low  eq 'auto' );
    $is_auto_high = ( $bound_high eq 'auto' );

    if ( $bound_low ne 'auto' and $bound_low ne 'fit' ) {
        $lower = $bound_low;
    }
    else {
        $lower = $data_low;
    }

    if ( $bound_high ne 'auto' and $bound_high ne 'fit' ) {
        $upper = $bound_high;
    }
    else {
        $upper = $data_high;
    }

    #    print STDERR "chose one '$tick_interval'\n";
    if ( ( $tick_interval eq 'auto' ) or ( $tick_interval == 0.0 ) ) {
        $rng = abs( $upper - $lower );
        if ( $rng == 0.0 ) {
            $tick_interval = 0.5;
            $lower         = $data_low - 0.5;
            $upper         = $data_high + 0.5;
        }
        if ( is_power_2($rng) and is_power_2($upper) and $rng > 4 ) {
            if ( $rng == 2 ) {
                $tick_interval = 1;
            }
            elsif ( $rng == 4 ) {
                $tick_interval = 4;
            }
            else {
                $tick_interval = $rng / 4;    # maybe we want it 8?
            }
        }
        else {
            $tick_interval =
              auto_interval( $lower, $upper, $magic_arr, $division_arr );
        }
    }
    elsif ( $tick_interval < 0 ) {
        $intervals = -$tick_interval;
        $tick_interval = tick_intervals( $lower, $upper, $intervals );

        #	print STDERR "chose $tick_interval\n";
        if ( $is_auto_low and $is_auto_high ) {
            $is_auto_low = $is_auto_high = $atFALSE;
            $lower = $tick_interval * floor( $lower / $tick_interval );
            while (
                (
                    ( abs($lower) >= $tick_interval )
                    and ( ( $lower + $tick_interval * ( $intervals - 1 ) ) >=
                        $upper )
                )
              )
            {
                $lower -= $tick_interval;
            }
            $upper = $lower + $tick_interval * $intervals;

        }
    }

    # If the lower or upper bound are set to 'auto',
    # calculate them based on the newly chosen $tick_interval:
    if ( $is_auto_low or $is_auto_high ) {
        $delta = 0.01 * $tick_interval * ( $data_low == $data_high );

        #	deb "delta $delta";
        #	deb "1. tick interval $tick_interval, $data_low, $data_high";
        ( $auto_lower, $auto_upper ) =
          auto_bounds( $data_low - $delta, $data_high + $delta,
            $tick_interval );
        if ($is_auto_low) {
            $lower = $auto_lower;
        }
        if ($is_auto_high) {
            $upper = $auto_upper;
        }

        #	deb "got autlower $auto_lower";
    }

    #    deb "got lower $lower";

    # Compute the range of ticks values:
    $start = floor( $lower / $tick_interval ) * $tick_interval;
    $end   = floor( $upper / $tick_interval ) * $tick_interval;
    if ( $upper > $end ) {
        $end += $tick_interval;
    }

    #    print "start $start, end: " , $end + ($tick_interval / 2.0),
    #     " interval: $tick_interval" ."\n";
    #  use < end or <= end ?
    for (
        $i = $start ;
        $i < $end + ( $tick_interval / 2.0 ) ;
        $i += $tick_interval
      )
    {
        push @ticks, $i;
    }

  #    deb "after bounds2";
  #    @ticks = arange( $start, $end + ($tick_interval / 2.0), $tick_interval );

    if ( scalar(@ticks) < 2 ) {
        @ticks = array( ( ( $lower - $lower * 1.0e-7 ), $lower ) );
    }
    if ( $bound_low eq 'fit' ) {
        $ticks[0] = $lower;
    }
    if ( $bound_high eq 'fit' ) {
        $ticks[-1] = $upper;
    }

    #    print "data_low $data_low, data_high $data_high: ";
    #    for($i=0;$i<@ticks;$i++) {
    #	print $ticks[$i], ", ";
    #    }
    #    print "\n";

    return @ticks;
}

# return true if $n is a power of two
sub is_power_2_test {
    my $n = shift;
    deb "Testing $n for power of two";
    if ( ( ($n) & ( $n - 1 ) ) == 0 ) {
        deb " Yes";
        return 1;
    }
    deb " No";
    return 0;
}

# Lapeyre added the attempt to see if we have an integer
sub is_power_2 {
    my $n    = shift;
    my $nint = abs( int( $n + .5 ) );
    if ( abs( $nint - $n ) > $Pow2Eps ) {
        return 0;
    }
    if ( ( ($nint) & ( $nint - 1 ) ) == 0 ) {
        return 1;
    }
    return 0;
}

#--------------------------------------------------------------------------------
#  Compute the best tick interval for a specified data range:
#--------------------------------------------------------------------------------

=begin comment

       Calculate the tick intervals for a graph axis.

        Description:        
        The boundaries for the data to be plotted on the axis are:
            data_bounds = (lower,upper)

        A choice is made between 3 to 9 ticks marks (including end points)
        and tick intervals at 1, 2, 2.5, 5, 10, 20, ...

        Returns:
        interval -- float. tick mark interval for axis            

=end comment

=cut

sub auto_interval {
    my ( $data_low, $data_high, $magic_intervals, $divisions ) = @_;

    my ( $i, $j );
    my (
        $range,       @candidate_intervals, @magnitudes,
        @mantissas,   $min_difference,      $min_index,
        $differences, $magnitude,           $interval,
        $result,      $min_mag_index,       $min_man_index
    );
    $range = $data_high - $data_low;

    #    divisions = arange( 8.0, 2.0, -1.0 ) # ( 7, 6, ..., 3 )

    # Calculate the intervals for the divisions:
    @candidate_intervals = @$divisions;
    foreach (@candidate_intervals) { $_ = $range / $_; }

    #    candidate_intervals = $range / divisions

    # Get magnitudes and mantissas for each candidate:
    @magnitudes = @candidate_intervals;

    foreach (@magnitudes) { $_ = 10.0**floor( log10($_) ) }
    for ( $i = 0 ; $i < @magnitudes ; $i++ ) {
        $mantissas[$i] = $candidate_intervals[$i] / $magnitudes[$i];
    }

    #    magnitudes = 10.0 ** floor( log10( candidate_intervals ) )
    #    mantissas  = candidate_intervals / magnitudes

    # Calculate the absolute differences between the candidates
    # (with magnitude removed) and the magic intervals:
    #    differences = abs( Magic_intervals[:,NewAxis] - mantissas )

    # Find the division and magic interval pair that produces the
    # smallest differences:
    $min_difference = 1e6;    # mantissas are less than a million
    my $tmpdiff;
    for ( $i = 0 ; $i < @mantissas ; $i++ ) {
        for ( $j = 0 ; $j < @$magic_intervals ; $j++ ) {
            $tmpdiff = abs( $$magic_intervals[$j] - $mantissas[$i] );

            #	    print "$tmpdiff\n";
            if ( $tmpdiff < $min_difference ) {
                $min_difference = $tmpdiff;
                $min_mag_index  = $j;
                $min_man_index  = $i;
            }
        }
    }

    # The best interval is the magic_interval multiplied by the magnitude
    # of the best mantissa:
    $interval  = $$magic_intervals[$min_mag_index];
    $magnitude = $magnitudes[$min_man_index];
    $result    = $interval * $magnitude;

    #    deb "int and mag '$interval', $magnitude";
    #    deb "got result: interval $result";

    if ( $result == 0.0 ) {
        $result = 1e-12;
    }

    return $result;
}

#--------------------------------------------------------------------------------
#  Compute the best tick interval length to achieve a specified number of tick
#  intervals:
#--------------------------------------------------------------------------------

sub tick_intervals {
    my ( $data_low, $data_high, $intervals ) = @_;

    my ( $range, $interval, $factor, $index, @tmparray, $result );
    $range = $data_high - $data_low;

    if ( $range == 0.0 ) {
        $range = 1.0;
    }
    $interval = $range / $intervals;
    $factor   = 10.0**floor( log($interval) / log(10) );
    $interval /= $factor;
    if ( $interval < 2.0 ) {
        $interval = 2.0;
        $index    = 0;
    }
    elsif ( $interval < 2.5 ) {
        $interval = 2.5;
        $index    = 1;
    }
    elsif ( $interval < 5.0 ) {
        $interval = 5.0;
        $index    = 2;
    }
    else {
        $interval = 10.0;
        $index    = 3;
    }
    @tmparray = ( 2.0, 1.25, 2.0, 2.0 );
    for ( ; ; ) {
        $result = $interval * $factor;
        if (
            (
                ( floor( $data_low / $result ) * $result ) +
                ( $intervals * $result ) >= $data_high
            )
          )
        {
            return $result;
        }
        $index = ( $index + 1 ) % 4;
        $interval *= $tmparray[$index];
    }
}

#--------------------------------------------------------------------------------
#  Compute the best lower and upper axis bounds for a range of data:
#--------------------------------------------------------------------------------

sub auto_bounds {
    my ( $data_low, $data_high, $tick_interval ) = @_;

=begin comment

    Calculate an appropriate upper and lower bounds for the axis from
    the the data_bounds (lower, upper) and the given axis interval.  The
    boundaries will either hit exactly on the lower and upper values
    or on the tick mark just beyond the lower and upper values.

=end comment

=cut

    return (
        calc_bound( $data_low,  $tick_interval, FALSE ),
        calc_bound( $data_high, $tick_interval, TRUE )
    );
}

#--------------------------------------------------------------------------------
#  Compute the best axis endpoint for a specified data value:
#--------------------------------------------------------------------------------

sub calc_bound {
    my ( $end_point, $tick_interval, $is_upper ) = @_;

=begin comment

        Find an axis end point that includes the value 'end_point'.  If the
        tick mark interval results in a tick mark hitting directly on the 
        end_point, end_point is returned.  Otherwise, the location of the tick
        mark just past the end_point is returned. end is 'lower' or 'upper' to
        specify whether end_point is at the lower or upper end of the axis.

=end comment

=cut

    my ( $quotient, $remainder, $c1, $c2 );
    $quotient = floor( $end_point / $tick_interval );

    #    print STDERR "$end_point, $tick_interval\n";
    $remainder = $end_point - $quotient * $tick_interval;

    #    print STDERR "end $end_point, q $quotient, r $remainder\n";
    if (
        (
               ( $remainder == 0.0 )
            or
            ( ( ( $tick_interval - $remainder ) / $tick_interval ) < 0.00001 )
        )
      )
    {
        return $end_point;
    }
    $c1 = ( $quotient + 1.0 ) * $tick_interval;
    $c2 = $quotient * $tick_interval;

    #    deb "c1 $c1, c2 $c2";
    if ($is_upper) {
        return $c1 if $c1 > $c2;
        return $c2;

        #	return max( $c1, $c2 );
    }
    return $c1 if $c1 < $c2;
    return $c2;

    #    return min( $c1, $c2 );
}

# End routines to compute tick marks
#============================================================================

#=====================================================================================#
#  SECTION                                                                            #
#                                                                                     #
#                                                                                     #
#  Top level routines, mostly. Some of this should probably be moved above.           #
#      .                                                                              #
#                                                                                     #
#                                                                                     #
#=====================================================================================#



###########################################
# Call the routines to do all the work.

=begin comment

gv can be set to 'watch' for a file to change and reload it. The watch interval is
1 s by default and can be set as low as 500ms with a resource file. yuck. Also
it can be sent the signal SIGUP (or 1) to reload, but this only works if the file
has changed (hmm maybe if the date is newer).
Signaling seems to be working now. It is much faster than waiting. The display updates
quickly.

=end  comment

=cut

sub make_viewer_opts {
    if ( $ViewerScale == TRUE or $Viewer eq 'xpdf' ) {
        return '';
    }
    my $opts = $ViewerScaleOpt;
    $opts =~ s/\%n/$ViewerScale/;
    return $opts;
}

sub launch_viewer {
    my ($args) = @_;
    return if $Viewer eq 'xpdf';
    if ( not defined $args ) {
        herror("No output file to view.");
        return ();
    }
    use POSIX 'WNOHANG';

# Using SIG{CHLD}= IGNORE
# causes pdf files to be rendered incorrectly with an error message (but not eps or ps)
# Using the waitpid does not cause this problem. No idea why
    $SIG{CHLD} = sub {
        while ( waitpid( -1, WNOHANG ) > 0 ) { }
    };

   #    $SIG{CHLD} = 'IGNORE'; # prevent killed viewer proc from being 'defunct'
    my $pid = fork();
    die "unable to fork: $!" unless defined($pid);
    my $opts = make_viewer_opts();
    if ( !$pid ) {    # child

        #	setsid or die "Can't start a new session: $!"; # does nothing.
        exec("$ViewerGvCmd $opts \"$args\"");    # no &, else we get pid of shell
        die "unable to exec: $!";
    }
    $ViewerPid = $pid;
    verbose "launched viewer: got pid $ViewerPid";
}

sub signal_viewer {
    my ($args) = @_;
    return unless defined $Display and $Display == TRUE;
    if ( $Viewer eq 'xpdf' ) {
        my $opts = make_viewer_opts();
        verbosesys("$ViewerXpdfCmd $opts \"$args\" &");
        #	verbosesys($ViewerXpdfCmd, $opts, $args);
        return;
    }
    else {
        if ( defined $ViewerPid ) {
            my $exists =
              kill( 0, $ViewerPid );    # check if viewer killed somehow.
            return unless $exists;
            verbose "signaling viewer: kill -1 $ViewerPid";
            verbosesys "kill -1 $ViewerPid";
        }
    }
}

sub do_examples {
    setup_example_plots();
    do_example( $ExampleNumber, 'noview' );
    if ( defined $Display and $Display == TRUE ) {
        verbose "$ViewerGvCmd $Outfile";
        launch_viewer($Outfile);
    }
}

sub do_all_examples {
    my $i;
    setup_example_plots();
    my $n = @example_plots;
    verbose "Doing all example plots.";
    for ( $i = 1 ; $i < $n + 1 ; $i++ ) {
        do_example( $i, 0, 'allexampleout' );
	verbose "wrote example $i.";
        #	verbosesys "cp $Outfile allexampleout";
        if ( $i == 1 ) { launch_viewer('allexampleout'); }
        if ( $DoAllExamples == FALSE ) {
            print "example $i: hit enter (or q to quit)\n";
            #	    if ( $InterruptSent == 1) {
            #		$InterruptSent = 0;
            #		return;
            #	    }
            my $line = <STDIN>; # using <> alone breaks things
            return if $line =~ /q/;
        }
        else { sleep $DoAllExamples; }
    }
    $Outfile = undef;    # so subsequent plots recompute Outfile
}

sub check_viewer {

    #    print  "CHECKING VIEWWER!!\n";
    #    print "pid $ViewerPid\n";
    #    print "viewerstarted $ViewerStarted\n";
    return if $Viewer eq 'xpdf';    # this should be checked in a func.
    if ( defined $Display and $Display == TRUE ) {
        if (
            defined $ViewerPid
            and ( defined $ViewerStarted
                or ( defined $ViewerStarted and $ViewerStarted == FALSE ) )
          )
        {
            my $exists =
              kill( 0, $ViewerPid );    # check if viewer killed somehow.

            #	    print "exists pid : $exists\n";
            return if $exists;
        }
        launch_viewer($Outfile);
        $ViewerStarted = TRUE;
    }
}

# This is just a sort of test. only used here.
sub arg_check {
    my ( $name, $test_result ) = @_;
    croak "wrong number of arguments to $name" unless $test_result;
}

sub plot_or_replot {
    arg_check( "plot_or_replot", @_ == 1 );
    my ($input_filename) = @_;
    if ( $input_filename =~ /\w/ ) {
        $Infile   = $input_filename;
        $HaveData = FALSE;
        $Outfile  = undef;          # not sure if this will break something else
    }
    my $res = 1;
    if ( defined $HaveData and $HaveData == TRUE ) {
        set_window_coordinates();
    }
    else {
        $res = read_data($Infile);
        return undef unless defined $res;
    }
    return unless do_norming();
    all_scale_transform() if $UseColTrans == TRUE;
    set_output_file_names($Infile);
    prepare_ps_file();
    write_output();
    check_viewer();
    return undef;
}

sub process_command_line_files {
    foreach $Infile (@ARGV) {
        $HaveData = FALSE;
        read_data($Infile);
        plot_or_replot($Infile);
    }
}

if ( $RunShell == TRUE ) {
    Shell::run_shell();
}
elsif ( defined $ExampleNumber ) { do_examples(); }
elsif ( defined $DoAllExamples and $DoAllExamples >= 0 ) { do_all_examples(); }
else { process_command_line_files(); }