FAQ

This is a rather old FAQ, but start looking for your questions here, anyway.

PLplot FAQ (Frequently Asked Questions)
---------------------------------------

This note contains answers to some Frequently Asked Questions (FAQ)
regarding PLplot.  

Disclaimer:

The questions & answers that follow typically have been posed (and answered)
in email, and seem to me to be worthy of inclusion in a FAQ.  They may be
out of date with respect to the current revision, or be otherwise suspect
(misleading, incomplete, etc.), and the original authors of both the
question and answer have not been retained (most of the answers come from
Maurice, some from Geoff, and the rest from various people on the mailing
list).  Personal opinions may be contained within: this document is not to
be considered the official opinion of the IFS or University of Texas or any
other funding agency supporting this work.  Feel free to send comments or
corrections to mjl@dino.ph.utexas.edu (Maurice LeBrun) or
furnish@dino.ph.utexas.edu (Geoff Furnish).

The conventions of the CVS FAQ are adopted here.  Each question in the
table of contents will be given a change marker (for non-trivial changes)
in the first column:

	'-'	for a Question that has changed.
	'='	for an Answer that has changed.
	'#'	for an entry with changes to both Question and Answer.
	'+'	for a newly added Question and Answer.

==============================================================================
Contents
--------

 1. Building/installing PLplot
 2. Philosophy, future directions, broad capabilities, etc.
 3. Specific features/capabilities
 4. X-based drivers (includes Tcl/TK, Tcl-DP)
 5. All other drivers & supported platforms

==============================================================================
Section 1: Building/installing PLplot

 1.1  How do I build & install PLplot?
 1.2  Where do I install PLplot?
 1.3  (moved)
 1.4  I don't have an ANSI compiliant C compiler.  How do I compile PLplot?
 1.5  I don't have a fortran compiler; how do I compile PLplot?
 1.6  The linker complains of unresolved functions atexit(), fsetpos(),
      fgetpos(), and so on.
 1.7  The compiler complains about the use of "malloc" or "size_t".
=1.8  The compiler complains about "caddr_t" in one of the X support files.
 1.9  configure script doesn't run correctly
 1.10 (removed)
 1.11 The linker complains that it can't resolve Tcl_AppInit. 
+1.12 Can the library place be changed *after* compilation, say, by an
      environment variable ?
+1.13 tcpip.c won't compile.

==============================================================================
Section 2: Philosophy, future directions, broad capabilities, etc.

 2.1  Why should I use PLplot?
+2.2  Could you comment on the pros and cons of plplot and gnuplot? 
+2.3  How do I use PLplot to do interactive plotting?
+2.4  What is RLaB?
+2.5  Why should I use Tcl?
+2.6  What are some of the planned enhancements to the PLplot interactive
      capabilities? 
+2.7  Is there a PLplot newsgroup?

==============================================================================
Section 3: Specific features/capabilities

 3.1  The manual doesn't mention capability...
=3.2  How do I change the default background color?
 3.3  I'm getting core dumps when calling a contour function from C.
 3.4  Changing the default line width doesn't have any affect.
 3.5  How can I generate more than 16 line colors?
 3.6  What 2-d array organization am I supposed to use from C?
 3.7  On stretched windows, the string characters look bad..
 3.8  I would like to capture key sequences..
-3.9  How to get more information about a function or capability.
+3.10 What are the keyboard controls in the graphics window?
+3.11 How do I get the value of a PLplot internal variable?
+3.12 I'm getting "Unable to delete command .dx.gq1" when I use a matrix.
+3.13 My matrix'es are being deleted while in use from itcl.
+3.14 I'm getting a "already exists" message when creating a tclMatrix.

==============================================================================
Section 4: X-based drivers (includes Tcl/TK, Tcl-DP)

=4.1  Where do I get Tcl/TK or Tcl-DP?
 4.2  How do I use "xauth"?
 4.3  How do I use the Tcl/TK driver?
 4.4  I've been having trouble getting the TK/TCL and PLplot working on...
 4.5  I would like to issue a plot command, have the window appear,...
 4.6  The X driver seems to run slower than on older versions of PLplot.
 4.7  How do I change the title on the TK window menu bar, i.e...
-4.8  How do I run plserver as a daemon?
 4.9  Problems printing from the Tk driver..
 4.10 Problems compiling xwin.c...
 4.11 Problems saving files from the Tk driver.
+4.12 Why does the Tcl/TK driver use a separate process for rendering but
      not the X driver?
+4.13 How do I create an interactive, widget-based application using PLplot?
+4.14 How do I shade between a 4 color range with the Tk driver?

==============================================================================
Section 5: All other drivers & supported platforms

 5.1  What about support for platform..
=5.2  What about PLplot support for VMS?
 5.3  PLplot is aborting with: Error opening plot data storage file.
 5.4  Is there a Windows port of PLplot?
+5.5  I'd like to develop a windowed interface to PLplot for..
+5.6  What about PLplot support for the Mac?
+5.7  What about PLplot support for OS/2?

==============================================================================
Section 1: Installing PLplot
==============================================================================

 1.1  How do I build & install PLplot?

For a Unix-based system, it is usually as easy as typing 'configure', then
'make', then 'make install'.  However I strongly recommend that you first
read the file INSTALL in the distribution directory.  For non-Unix systems,
look at the system-dependent notes under sys/<system name>.


 1.2  Where should I install PLplot?

The configure script and Makefile are set up so that you can put the
various components of PLplot virtually anywhere.  By default, it installs
into a directory with the following subdirectories:

bin       doc       examples  include   info      lib       tcl

On Unix systems I recommend using a directory just for PLplot.  Somewhere
under /usr/local is a good place.  For one, it's not too difficult to get
a system administrator to give you ownership of a directory somewhere in
the public hierarchy.  On a smaller system, giving the package its own
directory helps maintain system integrity.  The practice of dropping
everything into /usr/local/bin, /usr/local/lib and so on (or even worse,
/usr/bin, /usr/lib, etc) makes everything simple to install initially but
leads to a system that's difficult to organize and maintain.  There's the
possibility for file name collisions -- stuff that isn't in your search
path but needed anyway (readme, doc, and config files).  There's no way to
cleanly & robustly back out the revision.  There's no way to tell where
each file in /usr/local/bin (lib, etc) came from.

Any sufficiently large/complicated package has this problem.  Dedicating a
directory tree is a good way to preserve the package's integrity.  The only
good reason I've heard so far for NOT doing this (apart from laziness when
installing) is that people then have to modify their search paths and other
settings to use the new package.  Therefore, I've written a script that
takes care of that.  Run doc/mklinks from the install directory, to create
softlinks from the install directory into ../bin, ../lib, ../include, and
../man as appropriate.  Just as important, you can run it again TO
COMPLETELY REMOVE THEM.  Thus it becomes trivial to install and back down a
revision.  All software should work this way.

Note, I've written a similar script for Tcl/TK and extensions, called
"installtk".  A copy is on harbor, but the current version of "mklinks"
distributed with PLplot works with BOTH.  With this I've brought up and
backed out a TK rev on several occasions, and found it immensely useful at
the time, which is why I wrote it :-).  I think it is the most handy in
two cases: 1) when developing using new betas, or 2) in a production
environment, where you want to bring up a new package but still have the
old one available in case programs break.  In the latter case, the only
sensible scheme is to have the package in its own directory.

Now, if after all that you STILL want to break the package up, just set
the appropriate shell variables for the install directories before running
configure, in ~/config/cf_plplot.in (see configure notes).  That way you
can put the docs, examples, and tcl files under e.g. $prefix/plplot, and
everything else under $prefix/bin, $prefix/lib, $prefix/include,
$prefix/man (imagine $prefix=/usr or $prefix=/usr/local and this will make
perfect sense).  OK, there are no man pages yet, but there will be one of
these days.


 1.3  (moved)


 1.4  I don't have an ANSI compiliant C compiler.  How do I compile PLplot?

Get an ANSI C compiler.  The cheap solution is to get gcc up if it has
been ported to your machine.  This is not unreasonable IMHO -- the C
standard was approved in 1989.  Isn't it about time you upgraded?


 1.5  I don't have a fortran compiler; how do I compile PLplot?

The Fortran files are only part of the interface layer for Fortran codes
that use PLplot.  If you don't need this capability the layer can be
omitted by running configure with the --disable-f77 flag under Unix.

Alternately, you can use 'f2c' (freeware fortran-to-C translator) to
compile the layer, assuming it (f2c) has been ported to your system.


 1.6  The linker complains of unresolved functions atexit(), fsetpos(),
      fgetpos(), and so on.

This is caused by a non-ANSI libc.  It /is/ possible to run PLplot on such
a system, but at slightly reduced functionality -- I rely on ANSI libc
functions both for seeking (fsetpos, fgetpos) and for cleanup (atexit),
but neither is absolutely essential.  Currently the configure script
should detect this condition automatically and make the necessary defines
to avoid any problem.  If not, let me know and I will fix it.


 1.7  The compiler complains about the use of "malloc" or "size_t".

Once upon a time, the source code went to some lengths to make sure
these were properly prototyped/typedef'ed even on systems that weren't
completely ANSI-compliant.  Now the code assumes they are in the usual
places:

	malloc	should be declared in stdlib.h
	size_t	should be typedef'ed in stdio.h (sometimes is in stdlib.h
		also, and sometimes only in stdlib.h.  The latter is a
		violation of the standard but I look for it there too.)

Since most of the PLplot source files need something from either stdio.h
or stdlib.h, I include them both.  If this does not work on your system,
there are two things to try.  First: fix the headers.  You can leave the
current definition in place as long as you "wrap" it, e.g.:

#  ifndef _SIZE_T
#    define _SIZE_T
     typedef unsigned int size_t;
#  endif /* _SIZE_T */

Then add an identical declaration where it is *supposed* to be.  The
second way is to hack plplot.h to explicitly prototype/typedef it.


=1.8  The compiler complains about "caddr_t" in one of the X support files.

This is sometimes seen on systems that have X11R4 and claim POSIX
conformance but that don't quite have their act together.  Typically on old
versions of Unicos, Ultrix, and DGUX for example.  Currently the configure
script determines whether caddr_t is typedef'ed, and if not, typedefs
caddr_t appropriately.  Note that under POSIX.1, caddr_t is NOT supposed to
be set.  But because of the various broken headers out there I compensate by
typedef'ing it except when it is (illegally) already typedef'ed (note: at
least some versions of gcc perform the same "fix").  In any case, it should
always work, and if not let me know.


 1.9  configure script doesn't run correctly

The current configure script should work under even some very old versions
of "sh".  But in the event of problems, look around for a different shell
to run it under (posix shell, ksh, /bin/sh5, etc).

Be sure to check that the system name is being set correctly.  Your system
must have the "uname" program.  If not, you can roll your own easily
enough -- here's one for HPUX:

--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here-
#!/bin/sh
#
#       File: uname
#       Usage: uname
#
#       Minimal implementation of the uname command -- no arguments
#       supported.
#
echo "HP-UX"
--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here-

Alternately, you can explicitly set "system" either as a shell variable or
in the defaults file.


 1.10  (removed)


 1.11 The linker complains that it can't resolve Tcl_AppInit. 

The Tcl7.0/TK3.3 and later libraries contain a function called "main".
As a result, when linking you don't always get the correct main program.

This was done to make it easier to build custom versions of wish, so
all you had to do is to create your own version of Tcl_AppInit, link
with the library, and POOF! there is your modified wish.  Unfortunately
it sometimes sends the fortran compiler / linker into spasms, because
it gets the wrong main!  I have had exactly this problem under a 2-year
old version of SunOS (but not under a more recent one), and couldn't
get it to work despite varied link invocations.  BTW, I hear a similar
problem exists under Linux from a C++ main.

My solution on these platforms was to recompile the tcl and tk libraries
without the file including the main program (I think it was tclMain.o and
tkMain.o).  I installed the new libraries as well as the separately compiled
*Main.o's in case someone needed them.  No more problem with the Fortran
compiler.

Another case where this may come up is using f2c to compile a Fortran
main, in which case the true main is in libf2c.a.  In this case, putting
-lf2c BEFORE -ltk -ltcl on the link line will usually do the trick.


+1.12 Can the library place be changed *after* compilation, say, by an
      environment variable ?

The environment variable "PLPLOT_HOME" may be used to override the
default installation place such that

${PLPLOT_HOME}/bin	is the binaries' location
${PLPLOT_HOME}/lib	is the library/fonts location

if you only need to override a single value, the environment variables
"PLPLOT_BIN" and "PLPLOT_LIB" may be used to individually specify the
locations of the binaries and of the library/fonts, respectively.

So that in your case, setting PLPLPOT_LIB might be enough.

Below is a "cutting" from plctrl.c

/*----------------------------------------------------------------------*\
 * char *plFindCommand
 *
 * Looks for the specified executable file.  Search path:
 *	current directory
 *	PLPLOT_HOME_ENV/bin = $(PLPLOT_HOME)/bin
 *	BIN_DIR
 *
 * The caller must free the returned pointer (points to malloc'ed memory)
 * when finished with it.
\*----------------------------------------------------------------------*/

/*----------------------------------------------------------------------*\
 * FILE *plLibOpen(fn)
 *
 * Return file pointer to lib file.
 * Locations checked:
 *	PLPLOT_LIB_ENV = $(PLPLOT_LIB)
 *	current directory
 *	PLPLOT_HOME_ENV/lib = $(PLPLOT_HOME)/lib
 *	LIB_DIR
 *	PLLIBDEV
\*----------------------------------------------------------------------*/


+1.13 tcpip.c won't compile.

Probably a header file problem.  For example, under some versions of Linux,
the compile fails with optimization on.  The header file stdlib.h is busted.
Either fix the header file, turn off optimization, or put -U__OPTIMIZE__ on
the compile line (best).


==============================================================================
Section 2: Philosophy, future directions, broad capabilities, etc.
==============================================================================

 2.1  Why should I use PLplot?

This is probably the first question I was ever asked, and it continues
to come up often enough to dwell on it a bit.

First off, my involvement with PLplot came from a very simple need: a
portable, free, reasonable quality scientific graphics package.  At the
time I had a 1 year fellowship in Japan, to continue my work on numerical
simulation of plasmas.  Previous to this, I and my colleagues had
laboriously translated the simulation code graphics to use two other
libraries (one quasi-commercial and one PD), only to find both packages
lacking in some important respects (most notably the PD one) and unable to
easily (or cheaply) obtain the commercial one where I was working in
Japan.  This was an extremely frustrating situation, which had always been
apparent to me but only then came to a head.  Scientific graphics is an
utter necessity to anyone doing numerical modelling, and I decided that
being at the mercy of vendors and computer centers on this issue was
unacceptable.  

I have no objection to commercial software, but let's face it.. sometimes
commercial solutions suck.  This is one of those times.  You don't have
access to the source code, so you can't improve it to suit your needs
better, and you certainly can't freely carry it to different machines.
Software environments on high-performance Unix systems, especially as
regards commercial software, are VERY variable from machine to machine.
Regardless of why this situation exists, I decided I could no longer
depend on commercial software to provide a basic graphics capability.  I
was somewhat familiar with PLplot for the Amiga, and seeing that it was
fairly capable and portable I decided this would be the "last" graphics
package I would use and support (for a long while at least).

It turned out that PLplot required some substantial investment of my time
before it satisfied all of my (then) needs, but has nonetheless performed
quite well.  In the interim I took over development for it from Tony
Richardson.  The package has become almost trivially portable -- we can
now get our codes running on a new machine in record time.  We can fix
bugs in record time, although it doesn't always happen that way :-).
Still, it takes less than a month or two for me to get around to fixing
most bugs, which is better turnaround time than you typically get from
vendors.  New features can be added with astonishing speed if the need
(ours) is great enough.

So those are some of the reasons /I/ got involved, which may differ from
those of the casual user.  Most people won't be digging into the source
code to fix bugs, although it's very reassuring to know that you can if
you need to.  I can't promise quick bug fixes or specific enhancements as
my responsibilities (i.e. funding) lie elsewhere.  But I am always
interested to hear what people want, since if it's a good idea I will
benefit too.  User-contributed code is always welcomed (there has been
quite a bit).  And backward incompatibilities will be introduced into the
package sparingly if at all.

The features supported by PLplot are necessarily fewer in number than a
big commercial package.  PLplot has a fairly complete set of basic
graphical capabilities, and a few very strong capabilities (e.g.  the
Tcl/TK "plframe" plotting widget, and the GUI drivers built around it).
This has its good and bad points.  The good part is that the library is
relatively small, and can be modified without too much difficulty.  The
disk space required is reasonable (especially if shared libraries are
used), and the learning curve mild.  The effort I might expend adhering to
some large set of capabilities (many of which may be only rarely used;
e.g. look at the GKS standard) can be focused instead on portability, user
interface, and certain select capabilities that I and my colleagues find
important.

On the other hand, there are many nice capabilities missing from PLplot at
present, such as support for solid 3d modelling or postscript fonts, just
to name two.  New features are continually being added, but the fact
remains that other more special purpose (and/or high priced) products will
always have things that PLplot lacks (or do them better).  One way I see
to fit PLplot in the overall software environment is to add more output
drivers, both for generic file formats (e.g. GIF, CGM) as well as for
specific high-end graphics packages (e.g. AVS).  That way you could
produce your graphics and view them using PLplot, dumping to disk those
pages or plots you want to process using a separate package.  This can
already be done using the XFig driver, for example.  For maximum
effectiveness of this scheme, PLplot should have internal knowlege of more
varied objects than "line" (currently the fundamental unit), and I have
some plans in this area.

I'm always interested in gaining new collaborators and contributors for
PLplot, so feel free to send me email (mjl@dino.ph.utexas.edu) so we can
discuss additions you'd like to make.  Want to help support PLplot but
need suggestions?  I hesitate to recommend anything that will require
broad changes to the package, but any of the following would be great:

	volunteers for target platform support (I have HPUX covered)
	output drivers: GIF, CGM, others?
	PLplot demos?  (especially using Tcl/TK)
	an improved contour plotter
	any interesting ideas/code for TK widgets for use with PLplot
	anything from the ToDo list you'd like to tackle?
	help rewriting the manual?  (OK, so I'm really reaching here)


+2.2  Could you comment on the pros and cons of plplot and gnuplot? 

They came from a different set of objectives initially.  PLplot started
out primarily as a library and gnuplot as an interactive tool.  At one
time gnuplot acquired some library-like capabilities but these were never
merged back into the master sources, and are quite out of date by now (I
hear).  PLplot is becoming more interactive.  Eventually I think PLplot
will surpass gnuplot even for interactive plots for the following reasons:

(a) it will have full access to the underlying plot library, which is more
    varied than gnuplot (with good support for contour, surface, 3d plots,
    etc).

(b) the scripting language I use for it is Tcl (note: there are others
    too, see questions 2.3, 2.4).  Tcl has a large following and is fairly
    well thought out, rather than a home-grown language.

(c) the most advanced driver is based on Tk, an X-windows tool kit, and
    both (Tk and the PLplot capabilities based on it) are very powerful.

Unfortunately as it stands, (a) is not true yet, and the documentation
that describes all the current features is not done either.  This will be
rectified by the time I release 5.0.


+2.3  How do I use PLplot to do interactive plotting?

> I am planning to use PLPLOT to plot some 2D pictures about software bug
> generation rate, bug correction rate, and etc. Using gnuplot I could put
> the X-Y data pairs in a file then use the 'plot' function. Is there a
> similar idiom in PLPLOT?

Such a thing is easily constructed in Tcl.  I never bothered cooking up a
demo because it was too easy :-).  But now I have one (~30 minutes of work,
modelled after elements of x01.tcl) -- it is included in the distribution
as examples/tcl/plot.tcl.  To test it, type:

% pltcl
pltcl> source plot.tcl
pltcl> plot foo.dat

from the examples/tcl directory.  As you can see, it is quite easy to use
Tcl for things like this and it's almost not worth it to construct huge
mega-commands like GNUPLOT's "plot" command, since the user can now write
Tcl procs to do exactly what is needed (i.e. without inventing a new API).
Therefore, I doubt I'll improve plot.tcl to be more like the GNUPLOT call,
although if someone does write such a beast and wants to share it, that's
great.

The main disadvantage of using pltcl for such things is that I don't often
use it, and am therefore slow to improve it.  It needs more work on the 2-d
API (for contour, surface, and shade plots), better access to internal
variables, and so on.

Also, there are alternatives.  Currently Ian Searle's RLaB and my pltcl are
the two best supported interpreter front-ends to PLplot.  Radey Shouman
wrote a Scheme (SCM) interface which may appear publicly before long.  John
Interrante wrote a python interface which I am integrating with the main
sources.  And at one time there was a PLplot-based interpreter on the Amiga
that used Rexx as its script language (maybe OS/2 users would be interested
in this too, but unfortunately it's way out of date now).


+2.4  What is RLaB?

RLaB is an interpreted/interactive  matrix programming language which
uses Plplot. RLaB has implemented most of the Plplot API so that users
can interactively visualize data. Additionally there is a higher level
abstraction of the Plplot capabilities that allows users to do things
like:

	x = readm("mydata");
	plot(x);

or

	x = readm("mydata");
	X = fft(x);
	plaxis("log", "log");
	plot(abs(X));

RLaB is geared towards scientific/engineering usage, but could also be
quite useful for other types of data. 

RLaB is a "High Level Language" with matrices (2-d arrays) as a
fundamental object. Thus:

	b = A*x;

where b is (Mx1), A is (MxN), x is (Nx1) works as expected. RLaB
includes a host of builtin linear-algebra, an spectral functions,
taking advantage of LAPACK, BLAS, and FFTPACK. Although RLaB may be
more than the original poster wants, I think it is at least worth a
mention. 


+2.5  Why should I use Tcl?

> I've recently seen an article on the net (comp.lang.tcl:19017)
> 
> 	Title:		Why you should not use Tcl
> 	Author:		Richard Stallman, GNU Project.
> 
> In which a case was made to avoid a "scripting language" such as Tcl in
> favour of a language that is more easily extended.
> ...
> If indeed Richard Stallman knows what he is talking about, then is Tcl
> really the best way to extend PLplot?

(here I break from my usual convention and attribute responses)

Geoff's response:

Since you saw this post by RMS on c.l.t, I'm sure you also saw the
extremely severe flame fest which ensued.  I think it would be good to
avoid repeating that on this channel, so let me refer interested
parties to the newsgroup for all the gory details.  But since you are
clearly trying to probe what our thinking on these issues is, I will
provide at least a restrained response.  Perhaps Maurice can do the same:

I have to say first that I have a great deal of personal respect for
the FSF and it's accomplishments, though I am less impressed by it's
stated aims.  Nevertheless, I use GNU tools daily, especially but not
limited to GCC, and have even hacked GCC some myself.  PLplot is now
distributed under the LGPL.  etc.

However, in this case, the informed mind has to conclude, that Richard
Stallman spoke out of turn.  It is most unfortunate that he used his
position of influence in the free software community to cast such a
spectre of FUD and inanity on Tcl/Tk.  Certainly on technical merit,
his post was vacuous.

> Opinions on how PLplot should proceed?

I think Maurice and I are both squarely in the camp of:

	"Let each man choose his own tools"

and we have chosen ours :-).  If others want to go with Scheme (or
Python, or WINTERP, or whatever), that's fine by us, and we are
willing to help integrate and incorporate such user-contributed
modifications into the distribution.  In point of fact, there already
is a Scheme port of PLplot, done by another fellow in Austin, and we
are working with him to increase the visibility of his work.

As for PLplot and Tcl/Tk.  I do think there is an issue with Tcl
regarding the construction of large script systems.  Tcl provides very
poor support for "large" software, whatever that means to a given
person.  That is precisely why I recommend ALWAYS using the [incr Tcl]
extension, which provides to Tcl exactly the same sorts of things that
C++ provides to C.  Not everyone is sold on object oriented
programming of course.  Maurice, for instance, is still basically
comfortable with developing the PLplot library in C and writing the
Tcl parts of the Tcl/Tk and DP drivers in plain Tcl.  I on the other
hand, write new code in C++ if at all possible rather than C, and in
[incr Tcl] rather than plain Tcl.  Although it is not so easy for
all C users to switch to C++ (cost and availability of compilers being
the main issue here), it is clearly no big deal for people who use Tcl
to also use [incr Tcl] (since it is free, and just as portable as Tcl
itself).  Maurice and I have been having a long standing dialogue
about whether to make [incr Tcl] a required addition to Tcl for
PLplot.  Many parts of the PLplot Tk interaction could be provided in
a more robust, more customizeable, and most importantly more
extensible fashion if they were done in [incr Tcl].  Certainly all the
contributions I am making are being done in itcl, Maurice is still
making up his mind on that one.

In any event, there is certainly no reason why PLplot cannot be bound
to other scripting environments, and Maurice and I do not wish to
in any way discourage others from doing exactly that.  The PLplot Tcl
bindings can serve as a point of reference for interested parties, and
so can the Scheme port.

The motto in our office is:

	"Go wild!"

So if you've got an idea that involves something radically different
from Tcl/Tk/[incr Tcl], we say, "great, go wild!"  Send us the diffs.

Maurice's response:

This post of RMS's inspired a truly awesome flamefest on the newsgroups
specified on the Followup-to: line, which were comp.lang.tcl,
gnu.misc.discuss, and comp.lang.scheme.

This whole thing would have been avoided if RMS had more net experience.
Those of us who have spent considerable time on the net know better than
to get on some language group and essentially say "your language sucks",
or to get on a computer group and say "your computer sucks".  Usually,
there are many fine points involved which the poster, no matter how well
educated, simply doesn't have a clue.  This is one of those cases.

Tcl is not the perfect extension language.  I'm not sure that Scheme is
either.  Does it matter?  And Tcl *can* be improved further.  E.g. Geoff
mentioned [incr tcl], an OO Tcl extension.  I am currently flirting with
the idea of requiring it for the PLplot Tcl-TK part in some future
revision, after some reasonable period of supporting the old code.  Since
[incr tcl] supports vanilla Tcl as well, the only real drawback is that
yet another package is required to be present, but this isn't that big a
deal.

Tcl is very popular and getting more so.  It's easy to use and easily
embeddable in a C or C++ application.  There is one book out on Tcl/TK
programming (JO's) and at least one more in the works.  Plus it has
copious online documentation.

Finally, Tcl *has* been ported to non-Unix systems.  Although it would
help if JO directly supported this effort.  Looking at the new contrib
site (ftp.aud.alcatel.com) I see ports to MSDOS, the Mac, and VMS, and
I know of an old port to the Amiga as well.

This note just scratches the surface.  Basically, I predict a bright
future for Tcl, and plan to use/support it with PLplot for a long time to
come.


+2.6  What are some of the planned enhancements to the PLplot interactive
      capabilities? 

By mirroring the C api in Tcl, it is becoming possible to rapidly
prototype data interaction programs, coded entirely as Tcl scripts,
generating PLplot output through Tcl commands.  There are some demos of
this, but much much more can be done.

It would be really nice to have someone contribute Tcl code which went
farther in this direction.  With a small amount of Tcl programming, it
is easy to imagine very powerful interactive data analysis
capabilities.  Especially if these were provided as itcl classes, it
would then be possible to provide data analysis modules in Tcl/Plplot
which could then be "popped" into a code as easily as using the Tcl
autoload on demand mechanism.

Example itcl classes could be things like:
	1-d histogram utility
		reads data from specified file, puts up some 
		buttons to allow generation of histograms with
		various different options
	Financial analyst
		reads data from a file, produces various sorts of bar
		and pie charts.
	Linear regression analyzer
		reads data from a file, performs least square and
		other forms of regression, calls histogram utility
		(above) to generate graphs.
	FFT analysis package
		reaads 1 or 2 d data from a file, performs transforms,
		plots spectral data in 1 or 2 d.
	Volumetric data slicer
		reads 2 or 3 d data from file, presents plshaded
		contours with scale widgets for selection of cut
		planes, isosurfaces, etc.
	Functional calculator/explorer
		provides entries for a mathematical expression, min
		and max domain values, and plots the equation.
		Provides buttons for performing integration,
		(numerical) differentiation, fourier analysis (coupled
		to the above mentioned package), spline fitting, 
		root finding, etc.

Some of these ideas will require the 2-d Tcl api, which is still being
worked on, but which is definitely coming.  We (Maurice and I) cannot
hope to address all these issues ourselves, as we have other work to
do.  We would very much like to see user contributed code in these
areas.  I can provide direction to anyone who is interested enough to
seriously explore these issues.  Basically I would recommend getting
itcl, and working through the "tkdemos", making sure you understand
the "embedded plframe" concept (discussed in the new chapter of the
manual), etc, as a great start.  From there, the plan would be to
construct families of itcl classes embodying packages of widgets
(megawidgets in Tk parlance) which perform the above sorts of tasks,
or any others of your invention.

The potential is great, and the current demos only hint at what is
possible.  We long to make PLplot the premiere scientific plotting and
data analysis package, but there is only so much work we can do in so
much time.  There are tremendous opportunites for enterprising souls
to make great contributions in these areas.  This would be fabulous
material for undergraduate semester projects in CS/math/engineering
computer-lab type classes, if there are any professors on this list
:-).  Anyone who is interested in working in this sort of area is
welcome to contact me for further elaboration.


+2.7  Is there a PLplot newsgroup?

> I think one way to achieve better support/development of the PLPlot 
> package would be to create a newsgroup to give such requests as the above 
> a wider audience. Maybe something like comp.grahpics.PLPLOT?
> 
> This could also be the place to ask questions like "How do I do this..." 
> or "I have a problem doing this, can anyone help me?".
> Apart from that it could alleviate the pressure of supporting PLPlot by 
> the primary developers (GF & MJL) so that they can spend more time 
> actually doing new development.

A newsgroup comp.graphics.plplot would be fine with me.  In fact, I've
long expected that one day it would happen.  Unfortunately I know nothing
about starting a newsgroup, and also I'd want to relay it with the mailing
list, which again I know nothing about.  I sort of wanted to get the 5.0
release off before that step, with the implied finishing of the
documentation :-).  But sooner would be OK.  If anyone wants to start the
ball rolling on this, let me know.

A positive note: as of May 1995 the mailing list has been converted to use
Majordomo, which is a significant enhancement.  Users can now subscribe or
unsubscribe themselves (leaving me with more time for real work), see who
else is on the list, and retrieve the README, FAQ, and mailing list archive
by email.  Just send the message 'help' (in the body of the message, not
the subject) to plplot-request@dino.ph.utexas.edu for a full list of the
things you can do.


==============================================================================
Section 3: Specific features/capabilities
==============================================================================

 3.1  The manual doesn't mention capability..

The manual is waaay out of date.  Consult the last few update files to
keep tabs of what's going on.  Take a look if there are are any
substantial new capabilities in the example programs.  We went wild on the
manual a while back, rewriting it in LaTeXinfo so that we could publish it
in info file form.  That info file is available in the doc directory, but
unfortunately (a) it still needs some polish and (b) it is still waaay out
of date.  The next big push will see the end of it.


=3.2  How do I change the default background color?

Use the -bg option, or set by the plscolbg() API call.

In general it is safest to make all settings that may affect the driver (pen
width, color, etc) directly before the driver is initialized, i.e. before
calling plinit.  It turns out that the Xwin driver has a firm concept of the
background color, and changing it on the fly isn't hard.  Postscript (level
1), however, does not have the concept of background color.  So to get a
specific background color, a rectangle covering the background must be drawn
and then filled using the appropriate color.  Anything previously drawn is
obliterated.  So clearly, changing the background color should at least have
no effect until the next bop, and in the 4.99i (and before) ps driver, only
the initial setting is honored.  From 4.99j and later, the driver can get
the background color right on the next bop.  Still, to get the correct color
starting from page 1 you need to set it before calling plinit, because
plinit does a bop.

Note that in 4.99i and before, the background color fill in the ps driver
was always done, independent of the color.  This is unnecessary and even bad
in some cases, if the background is just white.  E.g. when generating color
ps output as EPSF input to a document, a background fill causes the figure
to overwrite parts of the page that you probably want to keep.


 3.3  I'm getting core dumps when calling a contour function from C.

Aha.  Did you specify the minimum index as 1, not 0?  This is a leftover
from when the package was written in Fortran, sigh.  I'm not sure why this
isn't explained in the manual -- I just looked and there is no mention of
it.  When I first got involved I mainly learned how to use the package
from the demo programs and so didn't really notice the inconsistency.
I've added some more explanatory error messages and will improve the
document in this area.  Unfortunately it may be too late I think to change
the minimum index to 0, since by now many people are used to this way.
Maybe add some new function calls to fix up the API..


 3.4  Changing the default line width doesn't have any effect.

Not all drivers support multiple line widths, in particular,
pixel-oriented ones such as all the Tek drivers.  Further, it may not even
mean the same thing from driver to driver.  If this ever becomes a serious
enough inconvenience I may take a harder look at it.  One problem is that
display devices typically don't have the resolution for resolving the
difference between different line widths.  For example, you can output
a plot using different line widths to a postscript file, and the lines
don't appear any visibly thicker until you hit 5 or so (so 1-4 look the
same, same for 5-8, and 9-10, or something like that).  The only real
way to see the difference is to print it.  Another problem is that there
may be no device support for multiple line widths.  In this case you
can mock it up by drawing lines multiple times (very close together),
but this is a real pain.

The driver does initialize the width to something reasonable, but only
if the user hasn't already set it (i.e. it is zero).  The postscript
driver uses a line width of 3 as a default, since this produces pretty
good results.  


=3.5  How can I generate more than 16 line colors?

Two ways.  1. You can increase the number of colors in cmap0 with the -ncol0
option.  2. You can use cmap1 to do it, via plcol1().  Each color will be
interpolated along a piecewise linear curve in HLS space.  This gives an
arbitrarily smooth color variation (for some drivers) with cmap1 index (in
range 0. to 1.).


 3.6  What 2-d array organization am I supposed to use from C?

The 2d array organization has an interesting history.  Back in plplot 2.6b
all the C API functions that took 2d arrays used column dominant
contiguous storage, while the corresponding Fortran API functions used row
dominant contiguous storage (naturally).  The latter allocated temporary
arrays and performed a transpose before calling the C API.  With plplot
3.0 Tony Richardson changed the C API to use arrays-of-arrays of pointers
to increase performance on some platforms.  Unfortunately on high end
platforms (vector machines or superscalar RISC workstations) performance
can actually be worse as a result -- slowdowns due to memory access can be
much worse than doing extra computation.  

As a result the situation re: 2d array organization in C became somewhat
confusing -- now there was a /third/ type of array organization, or /four/
if you want to count "normal" C array-of-pointers organization.  So I
decided, years ago, that I wanted to have a general way of specifying
array organization to be used by the 2d function API, with front-end
routines used for converting from popular techniques.  But as it isn't so
glamorous a pursuit, I've been slow to get it finished. :-\

The key idea is that for each major capability, there should exist a core
function that takes the array in a totally arbitrary way -- as a function
evaluator and its data.  This can be used directly if desired -- for
example by a C++ user with his own matrix class.  However I also will
provide front-end C API calls to handle the various popular 2d array
organizations.  These front-ends merely pass in the appropriate function
evaluator to the core routine, passing the user's array as data.  This
results in calls like plfcont(), which is the core routine, and plcont1(),
plcont2(), etc, which are the front-end routines.  

The core routine can do one of two things: it can either use function
evaluations in place of the 2d array lookups in its computations, or
create a temporary array in some standard internal format for its
computations.  Both have their merits.  On low-end machines, the function
evaluator approach is better (since there is little loss of pipelining and
no temporary memory hit), while on high-end machines the reverse is true.
On the other hand, on high-end machines the odds are better that you are
spending most of the CPU time on things other than graphics, and
efficiency is less important.  So I tend toward using the function
evaluator where it is convenient.  In the contour plotter the function
acceses are clear and it was easy to substitute a function evaluator.  In
plshade, however, the code is a bit too involved for this to be done
easily so instead I've gone the temporary array route.  Either way, as
long as the API is put in place and documented, I can always go back and
change things around internally later on.

My intentions right now is to give this a good look very soon, so that
if I need to break the C API to make it more consistent, it happens
before I release 5.0.


 3.7  On stretched windows, the string characters look bad..

> - If I make a window of say y=100 and x=1000 the character are rather
>   stretched. Is there a way to avoid this.

I haven't had the need for it and am barely familiar with how to do it.
The best way to fix it won't happen until I support actual text by the
driver, which is a long ways off yet.  But I think you can specify
physical dimensions of your output device using plspage().  In fact,
plspage() is called by the argument parser for the -geometry flag, but the
options specifying physical dimensions -- xpmm and ypmm -- aren't filled
in.  I can put changing this on my todo list.  But if it works, it will
only work as long as the window isn't resized.

Eventually, the driver and internal page representation will be
intelligent enough to support page resizing without changing the aspect
ratios of certain objects such as characters, strings, fixed aspect
viewports, etc.  But like I said, it's a way off.


=3.8  I would like to capture key sequences..

>   Also, I would like to be able to capture the PF2 and PF4 keys. My
>   application consistently uses these keys for particular responses. If
>   I can catch them, the application can take appropriate action.

You can catch these now from C by installing a keyboard event handler,
via the function:

/* Set the function pointer for the keyboard event handler */

void
plsKeyEH(void (*KeyEH) (PLGraphicsIn *, void *, int *), void *KeyEH_data);

You can look at the code in plrender as an example.  It uses a keyboard
event handler in order to detect & act on page seeking commands.  It would
be possible to mock something up for Fortran too if needed.  There is no
problem with doing this from X since only a single key code is
transmitted, but an xterm sends an escape sequence.  Your event handler
would be called for each key code which makes recognition a bit harder but
still doable (if in an xterm).  


-3.9  How to get more information about a function or capability.

> I would like to be able to take advantage of the new routines that came
> with 4.99g, but to do this I need to know the argument list that is
> supplied to each one - the additional docs that came with 4.99g are very
> sketchy on this.
> 
> I would particularly like to use plscmap1l, which I have had trouble
> with,  also the following which are not explained:
> 
>  *      plwarn plexit plcol0 plcol1 plrgb plrgb1 plscolbg plscol0 plgcol0
>  *      plscmap1 plscmap1f1 plscolor
> 
> Any details would be gratefully received.

Well for me to really explain would be basically the same as finishing the
docs, which I don't have time for right now.  I suggest looking at the
example programs and especially the source.  Now, I know that might not
sound like fun, but some of the source code is a fairly easy read.  Look
in "plplot.h" -- each function has a prototype that lists arguments and
has a one-line description.  The description is usually an abbreviated
version of the comments written with the function itself.  

If you are an emacs user, browsing the source code is very easy with
'tags'.  From the tmp directory, type 'etags *.c'.  Then edit plplot.h,
move the cursor to the name of the function you are interested in, and
type ESC-.  <poof>, you are there.  Happy hunting.

p.s. Some of the new capabilities are illustrated in C example programs
but not Fortran, e.g. see x15c and x16c.  x17c isn't working yet.


+3.10 What are the keyboard controls in the graphics window?

> Can you give me a pointer as to the other keyboard controls that are
> in effect in such a window? Is it in the docs/sources?
> I've noticed that Q quits the window(?)

It depends on the driver to some extent.  Here are the recognized keys
for the xwin and tk/dp drivers (tek is similar):

    case PLK_Return:
    case PLK_Linefeed:
    case PLK_Next:
    /* Advance to next page (i.e. terminate event loop) on a <eol> */
    /* Check for both <CR> and <LF> for portability, also a <Page Down> */

    case 'Q':
    /* Terminate on a 'Q' (not 'q', since it's too easy to hit by mistake) */

    case 'L':
    /* Begin locate mode */

You can intercept these by writing a keyboard event handler, if you want to
do various user-related things with it.  Using plfill() to do erasures, one
could even imagine writing an editing capability.  A graphical vi clone,
anyone? :-)

"plrender" installs its own keyboard event handler to add some more
keystrokes:

 * Keyboard event handler.  For mapping keyboard sequences to commands
 * not usually supported by PLplot, such as seeking around in the
 * metafile.  Recognized commands:
 *
 * <Backspace>	|
 * <Delete>	| Back page
 * <Page up>	|
 *
 * +<num><CR>	Seek forward <num> pages.
 * -<num><CR>	Seek backward <num> pages.
 *
 * <num><CR>	Seek to page <num>.
 * --<num><CR>	Seek to <num> pages before EOF.
 *
 * Both <BS> and <DEL> are recognized for a back-page since the target
 * system may use either as its erase key.  <Page Up> is present on some
 * keyboards (different from keypad key).
 *
 * No user data is passed in this case, although a test case is
 * illustrated. 
 *
 * Illegal input is ignored.

> How do you make your user aware of this? Does anyone have an example
> of a userinterface that tells the user about this?

I've thought about having the driver spit out a list of recognized
keystrokes to stdout if the user types "?" but never felt strongly enough
about doing so.  The Tk driver has a help entry that mentions most of
the recognized keystrokes.  And you can always look at the source.
Eventually this stuff will be covered in the manual.

Also note, the Tk driver has some more sophisticated keyboard controls, some
of which are activated depending on mode.  In normal operation, 'z' causes a
zoom, 'r' causes a zoom reset, 'P' causes a print, and 's' causes a 'save
again'.  These are set in pldefaults.tcl and can be customized on a per user
basis (read the instructions in pldefaults.tcl on how to do it).  When in
locate mode, the cursor keys move the graphics cursor.  When in zoom mode
(and not locate), the cursor keys cause the view to scroll.  Adding modifier
keys (CTRL, ALT, SHIFT, etc) causes a 5x speedup for each modifier added.


+3.11 How do I get the value of a PLplot internal variable?

> 	Can anyone tell me if there is a yet-to-be-documented PLPLOT
> function which returns the name or code of the output device associated
> with the current output stream (for PLPLOT-generated graphics)?

If there's no API call to do it, it's still easy to do from C or C++.  You
just include plstrm.h and get the stream pointer using either:

extern PLStream       *plsc;

or

PLStream *plsc;
plgpls(&plsc);

Then the device name is accessed by plsc->DevName.

If you are using fortran or Tcl or whatever then you are stuck.  Consider
writing a small C function to do the job.

Note: an API call is always safest.  If you feel strongly that it's
something that should be in the API, let me know.


+3.12 I'm getting "Unable to delete command .dx.gq1" when I use a tclMatrix.

> Whenever I use the tcl matrix facility you wrote from itcl, I always
> get these annoying 
> 
> Unable to delete command .dx.gq1

Yeah.  I continued to look into this after you left.  

> Seems you set a local variable when the matrix is created.  Then
> when the local variable goes out of scope, it is unset, which trigger
> a trace, so you try to delete the command, but can't, so the message
> is printed.

Right.  It turns out that a /different/ interpreter is trying to do the
unset.  Really strange, eh?  I don't know what magic itcl is doing here,
and don't really care to dig any further, because I can fix it so that
the variable and matrix is deleted according to the original plan by
just storing the original interpreter pointer in the tcl Matrix struct.
(done in 4.99j)


+3.13 My tclMatrix'es are being deleted while in use from itcl.

There's a lot of places in Tcl/Tk where a proc puts up some combination
of widgets with action bindings and then returns.  The parent may then
return or wait for the window to be deleted.  My 'Form2d' proc for example
does this, but I wait for it to be destroyed before proceeding so I can be
sure the input is available and act on it.  I.e.:

    Form2d .e "Enter window coordinates for zoom.  Each coordinate should range from 0 to 1, with (0,0) corresponding to the lower left hand corner."
    tkwait window .e

I communicate with the Form2d using global variables, which may be the only
way, since the proc goes out of scope before any user input is made!  Not to
mention that the parent may go out of scope as well.

So in 4.99j I added a way to make global, i.e. persistent tcl Matrices.
Just add the -persist flag on its creation, remembering to explicitly delete
the tclMatrix (using "<matrix> delete") when you're done.  I may add 'use'
and 'free' matrix commands to handle reference counting and deletion in the
next rev.


+3.14 I'm getting a "already exists" message when creating a tclMatrix.

A "matrix" declaration creates a command that processes all matrix commands.
Commands are always at global scope, unfortunately.  The local variable
that is set is only for GC purposes.  So there is no local scope for a
Tcl Matrix, just automatic GC (unless you use -persist).


==============================================================================
Section 4: X-based drivers (includes Tcl/TK, Tcl-DP)
==============================================================================

=4.1  Where do I get Tcl/TK or Tcl-DP?

The best way is by anonymous ftp.  The main distribution site for Tcl/TK
is ftp.cs.berkeley.edu in /ucb/tcl, and the main archive site (home of all
user-contributed extensions as well as a mirror of the main site) is
ftp.aud.alcatel.com in /tcl.  Also consult with the comp.lang.tcl
newsgroup on Usenet.  Tcl-DP can be obtained by anonymous ftp from
mm-ftp.cs.berkeley.edu in pub/multimedia/Tcl-DP, and is highly
recommended.  At the time of this writing, the versions that are fairly
certain to work with PLplot are:

tcl7.3
tk3.6
tcl-dp3.1
tcl-dp3.2

Earlier versions may be iffy.  PLplot does NOT yet work with tk4.0 (in beta
as I write this).

Note: the Tcl/TK, Tcl-DP header files should be found automatically by the
configure script if they are in a relatively predictable location.  Many
locations are checked; see cf/sysloc.in for more info.  If they aren't
found on your system, consider: (a) moving them, (b) making softlinks to
one of the searched-for locations, (c) if you REALLY think your location
should be searched for automatically, feel free to ask me to change it.


 4.2  How do I use "xauth"?

The 7.0/3.3 and later releases of Tcl/TK require xauth security in order
to accept send requests.  The only problem is that you have to
*completely* eliminate use of the older xhost method.  So typing "xhost -"
isn't good enough -- you must also explicitly delete all the names from
the xhost access list (type just "xhost" to see them).  That should do it
for your local node.  To grant remote nodes access, just ftp your
~/.Xauthority file (server machine) to your remote home directory.  There
are some notes on setting this up in the file Xauthority in the doc
directory.

I know from experience that setting up and using xauth security can be
a major pain in the neck.  For example, a site that's basically secure
can be configured by the system manager to enable xhost access to all
local nodes automatically through the /etc/X0.hosts file.  At such sites
the users are unaccustomed to explicitly granting permission and on a
secure group of machines there's no real security risk.  HOWEVER, a user
may need to occasionally access an "outside" machine, and since you can't
mix xhost and xauth, you are hosed.  And compiling TK without xauth
security is a gargantuan, tremendous security hazard.  A sickeningly vile,
disgusting mess.

Therefore I recommend that if you have any concerns about security or
problems with TK send, and ESPECIALLY if you are running from some remote
host, just forget about the TK driver altogether and use the DP driver
instead.  The DP driver uses a much superior method of communication
(sockets rather than X properties) and is distributable to boot.  It does
have a slightly longer startup time.  If you are running on a machine off
the network (where maybe you don't have a full TCP/IP implementation) the
TK driver is fine.  The DP driver only allows open connects between the
time it takes to launch the server and they do their initial handshaking,
a hole that I view as impossible to take advantage of.


 4.3  How do I use the Tcl/TK driver?

Get it going with the example programs, and play with it.  Read the online
docs.


 4.4  I've been having trouble getting the TK/TCL and PLplot working on
my Indigo running IRIX 4.0.5. I got TCL7.0 and TK3.3 as advised and built the
libraries and moved them to "/usr/lib" directory and then went about 
(re)building PLplot. I then compiled the c-demos and ran them. The tk driver
would pop up a window and disappear with the following complaints...
...
>>Starting up ./plserver
>>Server command "[list $plw_init $plwindow $client]" failed:
>>         remote interpreter did not respond
>>Program aborted

I think what is happening is that plserver is dumping core for some
reason.  So why don't you get a "core dumped" message?  It has something
to do with it being created through fork/exec from the TK driver.  Never
quite knew what, but now that I am thinking about it once again I bet I
know what the deal is.  It takes a little bit of time for it to dump core,
and in that time the sending interpreter in the TK driver times out, and
aborts.  Since the application is the parent process, once it exits you
don't see any pending messages that the plserver (child) has.  In this
circumstance I'm not sure if one should always get a core file or not.

So, the key is to find out why plserver is dumping core.  There are
a few things you can do.  When you built Tcl/TK, did you run the tests?
You need to type "make test" in either the tk3.3 or tcl7.0 directory, and
it will merrily go on its way.  After you have done that, try cd'ing to
the tk3.3/tests directory and running the tests using your installed
version of wish.  Some of the tests will fail because "make test" actually
compiles a custom version of wish with some extra functionality just for
the test suite.  But most of the tests will do ok.  If not, you hosed
the installation and that would explain the observed behavior.  If not
we need to do some more hunting.  

Here are some more things to try: define DEBUG at the head of the files:

	plserver.c	(will give you information at startup)
	tk.c		(this does the launching of plserver)

This should tell you at the very least if plserver is getting started
correctly.  In addition, to get a whole LOT of output about the current
state of the code, you can define also DEBUG_ENTER in:

	plserver.c
	tk.c

and even:
	plframe.c (also define DEBUG here, but be ready for lots of output)

The resulting messages often prove useful.


 4.5  I would like to issue a plot command, have the window appear,
or be re-painted, and allow the user to continue with command line operation
of RLaB. I would like the user to be able to resize the window at any time
or cover/un-cover it at any time and have it re-paint itself. The way  I 
can get it to work is: the user issues plot command, window appears and is
resizable, etc... the user must use the 3rd mouse button to "release" the
window, after that control returns to the command line, but the window will
no longer resize/repaint.

This is a feature, not a bug :-).

When the plotting package is waiting for the user to advance the page, it
is actually waiting for any X event.  So events like refresh and resize
get intercepted and processed.

Also during the normal course of plotting, the X server is periodically
polled to find out if there are any events that need processing, and
handles them if so.  I don't do this on every graphics instruction because
otherwise the overhead is too large -- currently on every 20 line draws,
every 10 polyline draws, and on every other call.

But once the user signals for the page advance, and control is returned to
the user program, there is no way for the X driver to process any events
simply because the control is in your program, not in the X driver.  The
single-headedness of your process becomes the culprit here.  You can
either sit in an event loop, or be doing user code specific things, but
not both.  If you want to periodically tell the driver to handle pending
events, there is an escape function call for that, but it's really just a
bandaid solution.

The best solution is to fork off the rendering into a separate process,
and this is just what I did with the Tcl/TK driver.  So, if you select
the tk driver, your code can go about its merry way while the graphics
window can be refreshed, resized, zoomed, printed, dumped, or whatever.

It'd also be a worthwhile project to split the X driver similarly, and
there has been some interest in doing that (but I don't plan to work on
it).


 4.6  The X driver seems to run slower than on older versions of PLplot.

This may be caused by writing into the pixmap.  Each instruction is
essentially done twice -- once to the screen and once to the offscreen
pixmap.  I'm not happy about the tradeoff but there's not much that can be
done.  With the pixmap, you get fast refreshes but slow draws, and the
other way around without it.  What made me decide on using a pixmap as the
default is the smooth scrolling that you can get (try a zoom followed by a
scroll in the TK driver -- without writing into a pixmap the scrolling
really sucks).  One way would be to write only to the pixmap and
occasionally blit it to the screen, but that would be jerky and you'd have
to worry about incomplete pages.  Try plotting with the -nopixmap option
to see if that's any better.  I do almost all my PLplot X development on
an HP 720 color console and graphics speed is usually not a problem :-).


 4.7  How do I change the title on the TK window menu bar, i.e.,

>   Plot >> plclient_#2
> 
>            ^^^^
>            I'd like this to read SuperCode

It uses the name of the main window if nothing else is set.  You can set
it two ways.  One, use plParseOpts to parse your command line, then it
will use argv[0] out of that list.  Two, just glom pls->program directly,
via: 

#include <plstream.h>

PLStream *pls;

...

    plgpls(&pls);
    pls->program = "myprogram";

Yes, by this method you have access to the complete internal state of
the current PLplot stream.  So be careful what you change :-).

There is one catch, though.  The way it is set up now it must be a unique
name when using the Tk driver (but not the DP driver) since it corresponds
to your main window name (to which X property messages are sent).  If
there is a previous Tcl interpreter of that name hanging around (say, as a
result of some sort of abnormal exit like a core dump) you will get the
mysterious _#2 appended (and _#3, and so on; note there are utilities
[zapinterps or delinterp] that will delete these zombie interpreters).


-4.8  How do I run plserver as a daemon?

> What would be really desirable, would be to make plserver into an
> actual daemon, as described in Stevens UNP.  Very cool idea, how
> daemons work.  The plan would be to have a guy sitting there
> monitoring a port/pipe/whatever, and when a connection request comes
> in, he forks, and calls back to the app with directives to use a new,
> previously unused (or reclaimed) port.  Then the daemon goes back to
> listening.  That way, you could run multiple apps simultaneously, each
> getting a new plserver if a spare one isn't already available...
> 
> I think the default action would be that when you punch >> on the last
> plot, the client goes ahead and terminates, but plserver stays up, for
> future invocations.  But when the user wants to get rid of it, if he
> doesn't plan to plot for a while, then there's a kill/off button
> somewhere on the pannel.

Actually it is possible now to start up a plserver and connect to it,
using the DP driver.  But one of the problems with this is the security
issue.  I get around the problem now by only allowing connects during
the brief time between the fork/exec and when the connection succeeds.
If it was open for longer we run into the same old possibility for
nasty interpreter commands being sent.  Dunno if there's a good way
around this.


 4.9  Problems printing from the Tk driver..

> We're having some big problems with the latest release of PLPLOT.
> Basically, we can't print and we can't save Postscript files. When we
> try to print we get
> 
> *** PLPLOT ERROR ***
> process_next: Unrecognized command
> Program aborted
> lpr: standard input: empty input file

Interesting.  Sounds like maybe an incompatibility with the plplot library
output and plrender [note: turns out it was indeed a previous version of
plrender in the user's search path].  The 'print' command saves the page
as a plplot metafile, and then invokes plrender to turn it into
postscript.  Either it was installed incorrectly, or (more likely), it is
a bug.  I have printed plots by this method without problem since the
4.99g release, but probably I didn't exercise everything.  Maybe try "Save
As.." with a variety of file types and see if anything turns out.  

> I have my PRINTER environment variable set. Am I supposed to do
> something else?  As for saving Postscript files, it seems to write part
> of the file and then just stop in the middle. It appears that some
> buffer is not getting flushed.  Any ideas?

Take a look at the plpr script, it is braindead, but I never had much time
to embellish it.  It doesn't allow you to set a particular printer, which
I guess is what you want.  You can always edit the file, for site-wise
customization.  Of course, this sucks, but is the best I have for now.
Isn't "lpr" supposed to obey the setting of PRINTER?  Even if so/not,
there's the question of how to render the saved metafile.  I use mono ps,
since that's usually what people want.  But sometimes I've wanted to print
grayscale output, and hit print without thinking, and got a nice,
completely black, plot. :-) So not only do I have to provide for a way to
select this in the GUI but also a way to read customized settings
automatically at startup.  Which brings up init file issues.. (see the
ToDo file).

So for now just modify plpr to your tastes and stick it in your path :-).
It should be located BEFORE the installed copy of plpr, which should just
be the site-wise default.  I usually have ~/bin before most significant
directories in my path anyway.  The exec() call used to invoke it does use
your path I believe.  And if you embellish it significantly, feel free to
send me a copy.


 4.10 Problems compiling xwin.c...

> I am trying to install PLPLOT on a DECstation 5000/240 running Ultrix
> 4.2a and an earlier version of X11R4. I am using gcc with the -ansi
> option.  Running make gives me the following errors:
> 
> In file included from xwin.c:50:
> /usr/local/lib/gcc-lib/decstation-ultrix4.2a/2.4.5/include/X11/Xlib.h:3958: parse error before `XSizeHints'

After poking around some on this system I found out that the header files
were hosed.  This is the kind of thing that crops up only when using an
ANSI compiler or C++ since it's in the function prototypes.  In
particular, Xlib.h uses XSizeHints before it's defined (in Xutil.h).  In
the X11R5 header files from HP-UX, all of the functions needing to
reference a variable of type XSizeHints* are prototyped in Xutil.h, after
the declaration of XSizeHints.  

I don't know how many systems I've seen with broken X11R4 header files --
a lot.  Seems the X11R4 distribution was partly to blame, but you'd think
the vendor would have at least checked to see whether an ANSI C compiler
would work with them.  In any case, there /should/ be an upgrade to fix
problems like this.  At worst, you can pull over a later X11 distribution
(as I write this X11R6 just came out) and build it yourself.  I do know
that some PLplot runs OK on some Ultrix systems so there should be an
upgrade available.  


 4.11 Problems saving files from the Tk driver.

> When I tried to save
> the .ps files (both color and mono) using "Save as.." in plrender,
> it doesn't seem to terminate the file properly. I had to add a
> "showpage" statement at the end before I send it to the printer 
> in order for my printer to print it properly. On the other hand, if
> I select the drivers (ps or psc) at the command line or upon start
> of the program, the output files looked fine. 

You either need to quit the program or pick "save close" before displaying
the saved file.  This is because "save as" leaves the file open so that
you can use "save" on multiple plots, each going to the same file.


+4.12 Why does the Tcl/TK driver use a separate process for rendering but
      not the X driver?

> The pgplot xwin driver forks a separate process to handle expose and other 
> events, and this works fine under SunOS 4.3.1 but fails under AIX 3.2.5 (and 
> I hear under other similar systems like Solaris 2). In your own code, you 
> seem to keep event handling inside the other routines, and periodically you 
> deal with the queue. Is that correct? Can you tell me a bit about the 
> philosophy behind the routines, and why such careful housekeeping is 
> necessary?

Forking it off as a separate process is much better, in principle.  The
xwin driver was contributed; I took it and improved it greatly and learned
a lot about X by experimenting with it.  I eventually wrote the Tk/Tcl-DP
driver(s), in which the rendering /is/ split off into a separate process.
The PLplot OS/2 driver written by Geoff Furnish works by similar
principles, but uses threads (something that more Unix systems should
support).  And, the Tk/DP drivers /do/ work under AIX, SunOS-4x, Solaris,
HPUX, Linux, Unicos, IRIX, OSF/1, etc.  I have become a bit of a
portability expert and what I don't have experience on, the users of
PLplot contribute (plus I've been working really hard on getting the
package as portable as is reasonable).  Nevertheless, the existing xwin
driver with its simpler paradigm (polling, rather than communication with
an external event-driven process) serves as a useful base level X driver.
There are definitely MANY more software and portability issues involved in
the separate process route.


+4.13 How do I create an interactive, widget-based application using PLplot?

> I would like to make an interactive widget so that the plot can be
> interactively changed by clicking and dragging on the plot.

Direct control of the plframe widget, or even better, the plxframe
"megawidget", is the way to go.

One problem: plxframe is not a true megawidget.  At the time of this
writing, there are few good ways to do this in straight Tcl, and I haven't
yet committed to rewriting the code in [incr Tcl].  I probably will
eventually, though, to make the plxframe truly controllable and robust.
Right now it's just a collection of Tcl procs that work together to
control a plframe.

Another problem: you have to do practically all the plot control from a high
level.  Graphical objects in the PLplot/tk interface are not objectized so
there are few low-level operations the user has access to.

The graphics representation in the plframe widget is just a bitmap.  I plan
to gradually raise the abstraction level up in order to make the package
more useful.  E.g. instead of a bunch of vector strokes, a character string
will be represented as a data structure, which only becomes vector strokes
when it gets to the driver.  That way the user can change its attributes;
most notably, the postscript font that is used to print it when sending the
plot through the ps driver.  Also something similar could be done with
color.  But these capabilities are a long way off and will be added very
conservatively.

BTW, a Tk canvas has good support for manipulating its components (at a
price). 

Now back to the high level way of doing it.  You can intercept keystrokes or
mouse clicks in Tk very easily using the "bind" command (Tcl API).  You can
set up an event handler that interprets the appropriate actions by the user
as commands to the plot library.  There are ways to return the world
coordinates of the cursor as well (a plframe widget command and API call),
which is important in controlling what gets done.

Each time the plot must be changed it would have to be redrawn.  This is not
unreasonable on today's killer micros or fast workstations.  In fact, the
scrolling you can do after a zoom is accomplished not by scrolling around in
some super bitmap but by redrawing the visible area of the plot each time
(it is buffered so that it appears smooth).  How well this works is a
function of the speed of your machine.  On my HP 720, scrolling simple line
plots (e.g. x01c) in zoom mode is quite fast.  Shaded plots are much slower.
And any routine that needs to do significant calculation (such as the
contour plotters) will be kind of slow to redraw.


+4.14 How do I shade between a 4 color range with the Tk driver?

The easiest way to experiment is to use the load palette option.
The last distribution came with some alternate choices -- cmap1a.pal
is the default, so try cmap1b.pal and cmap1c.pal.  And since they
are ASCII, it's trivial to create new ones.  Here's cmap1c.pal:
-----------cut-----------
6
#ff00ff 00
#0080ff 20
#00ffff 44
#00ff90 54
#fffb00 67
#ff0000 100
-----------cut-----------

The first number is the number of control points, and each control point is
set subsequently.  The first line after the '6' above is for the first
control point, and so on to the 6th.  The first number is the color in
hex, and the second number is the location in cmap1-space the control point
resides.  There is an optional third number, a boolean (0 or 1), that
results in the interpolation going "around the back" of the hue wheel
if set.  There is also an API function for setting control points.


==============================================================================
Section 5: All other drivers & supported platforms
==============================================================================

 5.1  What about support for platform..

Right now the package is most likely to be up-to-date under HP-UX and
Linux, since those are the two systems used most extensively by Maurice
and Geoff.  However we also use SunOS, AIX, UNICOS, and SUPER-UX enough
that probably there will be no problems on those systems also.  The DOS
and OS/2 support is being done mostly by other parties at this point (see
the README).  Any other systems are suspect.  Other Unix variants (IRIX,
OSF/1) are reasonably safe since the PLplot configure script is fairly
sophisticated and portable -- system dependencies tend to drop out without
notice.  I can't make any promises as to the Amiga support since I rarely
compile PLplot there these days.  Also no one is currently supporting the
NeXT.  As always, I'm looking for volunteers to help pick up the slack on
these systems (really, any other than say HPUX and Linux).  At the minimum
this means getting pre-beta releases and testing them, submitting any
fixes that need to be made, that's it!  If you have more ambitious plans
for supporting a particular platform, that'd be great -- let me know.


=5.2  What about PLplot support for VMS?

PLplot under VMS is now supported, thanks to the efforts of Hiromi Kimura
(hiromi@tac.tsukuba.ac.jp).  See the files in sys/vms.


 5.3  PLplot is aborting with: Error opening plot data storage file.

The most common reason I've seen for this is that the temporary file area
is set up incorrectly (wrong permissions).  Note: this directory is where
tmpfile() opens its temporaries, which may NOT be /tmp.  You can find the
true location typically by looking in stdio.h.  For example, on my HP
in stdio.h there is:

#  define _P_tmpdir "/usr/tmp/"

look for something similar on your machine, and make sure the directory
has the appropriate permissions (it should have global write set).


 5.4  Is there a Windows port of PLplot?

Look under sys/dos/bcc, there you'll see a file win3.c, which is a Windows
port by Paul Casteels.  I don't know much about it having never tried it,
but have heard some good comments about it.  One nice enhancement is the
ability to print the current plot.


+5.5  I'd like to develop a windowed interface to PLplot for..

For the systems that I've used, developing windowed interfaces is a fair
amount of work.  Most of my experience developing graphical interfaces is
under Unix (and a little on the Amiga).  Unix/X/Tcl/Tk on a fast
workstation makes for an excellent starting point -- it is powerful, and
the final product is fairly portable.  Virtually all my professional work
is on Unix machines, which also drives my effort -- the Tk driver is where
most of my attention has been going.  But it's still a /lot/ of work.

Of course there are still many reasons for using or developing on a
microcomputer -- if I used my Amiga more I'd be more inclined to spend
more time improving the interface there.  As it was, the Amiga had the
first PLplot windowed interface, and it gave me many ideas about how to
proceed with the Tk one.  Unfortunately, too many of these features were
built into the Amiga screen driver instead of the core, and didn't help
directly when I was doing the Tk driver.  So when I improved the package
in order to support the Tk driver I tried to make changes where they could
potentially benefit other windowing drivers.  This should help developers
of other windowed drivers some.

I originally started developing a Motif-based driver (in C), but abandoned
the effort when I saw how much easier Tk-based ones (in Tcl and C) are to
construct.  Tk is free to boot.  So at this point I'm very happy with Tcl/TK
and am probably finished with Motif.  There are still some reasons for going
with Motif -- such as needing a specific Motif widget or to satisfy company
policy, market demand, or whatever.  Also the recent development of
interpretive Motif environments that rival Tcl/TK in their ease of use and
prototyping speed (or so I've heard) makes Motif-based GUI construction more
palatable.  If you just want Motif widgets inside your app, you can do this
in Tk (see the comp.lang.tcl FAQ for more info).  Right now there is no way
to do the reverse as far as I know -- include Tk widgets inside a Motif app,
but maybe eventually there will be a way (I mention this because the
development of the plframe widget was the most time-consuming single thing
I've done as regards PLplot).

Under Windows, try the driver by Paul Casteels (see FAQ 5.4).  At the time
of this writing it is still somewhat sparse, but as per the comments above
it may not be unreasonable to extend it in the same directions as the Tk
driver.  Another alternative is to actually use Tk -- there are several
ports of Tk to Windows in various stages of completion.  I'd like to hear
about people's experiences with these, especially with PLplot.


+5.6  What about PLplot support for the Mac?

I've been asked several times about a Mac interface.  There is now a
Mac driver!  It needs someone to "adopt" it, i.e. keep it up to date,
answer questions about it, etc.  Email mjl@dino.ph.utexas.edu if you
want the job.  Otherwise it probably will end up broken sooner or later.

(Ian Searle writes:) Tzong-Shuoh Yang (tsyang@ce.berkeley.edu) has been
doing the RLaB Macintosh port for at least a year now (RLaB uses Plplot for
graphics).  Plplot works quite nicely on the Mac.


+5.7  What about PLplot support for OS/2?

>The stuff in sys/os2 worked under OS/2 1.3.  There is a port of that
>code to OS/2 2.x underway by another person, but I'm not sure of the
>current status of that port.  Presumably eventually PLplot will once
>again have OS/2 PM support, but there is no ETA.  You should be able
>to build PLplot to use file oriented drivers without difficulty.  Emx
>should be fine for that.

(John C. Peterson, KD6EKQ, {smart-host}!octagon!jcp,
jcp%octagon.UUCP@ucsd.edu writes:) That person would be me!  And, your
statement is correct, the only real "hitch" is the Presentation Manager
driver, a very desirable one to have of course. I've made pretty good
progress on the OS/2 port of the PM stuff using GCC/EMX. I've got all the
Presentation Manager and other APIs converted over to their 32 bit
equivalents.  It compiles cleanly under EMX without any "quibbling". At the
moment, there *are* a few bugs that need to be hunted down, about 1/2 of the
C examples fail to run correctly (or at all!) Most of this is because of
subtle changes to the design of the PLplot driver interface that have
occurred during the last couple years, during which time the driver was not
been updated.

   Unfortunately, I haven't had any time to work on it over the last
several months.  I've been very busy at my regular job for the last 4-5
months, working out of town for about 2 of those months. I tried to
recruit some help for this effort through the Usenet OS/2 groups, but
came up empty.  There is hope though, the big crunch at work is finally
behind me, and as soon as I get caught up with personal things, I hope
to get back to working on the port.

==============================================================================