#
# Multi-Window-Plot
#
# Created by Joao Cardoso on Oct 20, 1995. jcardoso@bart.inescn.pt
#
# WHAT IS?
# 
# This package allows multi-plot-window (as opposed to multiplot) under octave.
# 
# It consist in a few new functions and in modifications to existing Octave
# functions. The modifications done are generally minor, and are done to make
# the new functionalities transparent to the user.
# Note however that Octave builtins `gsplot' and `gplot'  can't be modified
# and thus the new functionalities cannot be used with them.
# There is also the possibility of give meaningful names to the plot legend.
# 
# WHAT DO YOU NEED?
# 
# You need a version of gnuplot that support pipe input or standard input
# redirection, such as 3.6b188 (really a _pre_ 3.6 release, patch level 188 -
# Mar 1995). I have not experimented  with a vanilla 3.5.
# If your gnuplot works as `gnuplot < command_file' it should be OK.
# 
# This package works through pipes, creating a new gnuplot process for each
# window. Your system must support named pipes and the `mknod pipe_name p'
# command or equivalent.
# 
# All Octave functions that need to be modified are in this directory, and
# should be found by Octave _before_ the original ones; don't install this
# directory under the script distribution tree of Octave. You should setup your
# LOADPATH accordingly.
# E.g. my is: `LOADPATH = /u/jcard/octave//:/usr/local/lib/octave/1.1.1/m//',
# and this directory in under `/u/jcard/octave'.
# I do not advise overwriting Octave's original plot directory with the new
# functions.
# If you have any doubts about a plot, start another Octave, set
# `LOADPATH = /usr/local/lib/octave/1.1.1/m//' or equivalent, repeat the
# same plot commands, and compare the two plots. Any differences should be
# reported (preferably investigated...).
#
# DESCRIPTION:
# 
# Basically, if you use the standard Octave's plot functions, you will notice
# (hopefully) no alterations with this package. When you need a second plot
# window, just issue a `fig(2)' command, and a new plot window will appear, with
# all further plots directed to it. If you want to revert to the old plot window,
# just issue a `fig(1)' command. You can use as many plot windows as you want.
# `fig' without argument gives the number of the current plot-window.
# 
# If you want to close a plot-window, type `close_fig(n)', where `n' is the
# number of the plot-window that you want to close; with no argument, it closes
# the current plot-window. You should open plot-windows in increasing order;
# although you can reopen through `fig' a previously closed plot-window, in my
# system this does not work, because of a bug in Octave (I think).
# `close_all_fig' closes all plot-windows. In this case you can reopen the plot-
# windows.
# 
# `gnu_i(string_command)' send a command directly to gnuplot, and you should
# conform to gnuplot's syntax.
# All new functions use this command; you can use whatever gnuplot command you
# want. If you want to plot directly to gnuplot, use e.g., after having a plot-
# -window:
# 	
#   tmp = sin(1:0.1:10)';
#   tmp_file = octave_tmp_file_name;
#   eval(sprintf("save %s tmp", tmp_file));
#   gnu_i(sprintf("plot ""%s"" title ""This is a sin()"" with lines",tmp_file))
#   gnu_i("set title ""Voila'"";set grid;replot")
# 
# As the `set' command can't be disabled, a substitute, `gset', is provided.
# E.g. gset("set nokey; set grid; replot"). Also, `gclear' replaces Octave's
# `clearplot'.
# 
# Also, `gpurge_tmp_files' has the same functionality as `purge_tmp_files', as
# this can't also be disabled. `tmp_file_name' is the substitute for
# `octave_tmp_file_name' for internal use. You can, and should, use the octave
# equivalent. `strntok' is also for internal purposes.
#
# The `fmt' option of `plot' has been extended. `fmt' is now made up of two
# semi-colon separated fields. The first is the legend for the line plotted, the
# other the usual option. E.g. plot(sin(1:0.1:10),'This is a sin();b+') will
# plot a sin() in blue with crosses, and write the legend `This is a sin()'.
# If no name is given, there is no necessity for the semicolon.
#
# POSSIBILITIES:
#
# The mechanism is general enough to enable using several plot packages
# simultaneously. The only requirement is that the plot programs accept commands
# through a pipe or standard input. The name of the plot program is obtained
# through the `gnuplot_binary' command. If gnuplot_binary is set to another
# program other than gnuplot, before a plot-window is opened, than _that_ window
# will be driven by that program, while the others will be driven by other
# programs. You can use `gnu_i' to drive the alien program.
#
# IMPROVEMENTS:
#
# First, a user level `quit'. This is a must, for calling `gpurge_tmp_files'
# and `close_all_fig'. If you forget this, the plot-windows will not be
# destroyed when you leave Octave. You have to `kill' then by hand.
#
# Better handling of back-grounding jobs.
#
# Correct the problem (bug?) in `fig' in order to avoid the deadlock between
# launching the external program and opening the pipe in Octave. If the pipe
# is opened with a "w" flag, the open will not return until an external program
# open the pipe for read; if the program is launched before opening the pipe,
# the `system' will not return. Opening the pipe with a "w" would kill the
# external program as soon as Octave closed the pipe.
#
# The extended `fmt' for plot and the `hold' functionality was done very
# careless... They should be fine tuned (but don't rely on me for the job).
#
# Use pipes to send the data files to gnuplot. It would be faster and avoid
# the problem of having tmp files. In my system, pipes can be only 5K long
# before the sending job gets blocked. One had to send the command to gnuplot,
# and only after that starting to write to the pipes.
# One would dynamically allocate more pipes, reusing them after use. Attention
# to the `hold'! Ah, a serious problem! gnuplot does `replot' by rereading
# the files!.
# This is very promising... Does anybody want to do it?
#
# BUGS?
# 
# The functions `contour' and `mesh' are not completely converted. I am not
# familiarized with them. However, you can use the `sombrero' function, because
# that part of `mesh' is implemented. If you convert these functions, please
# e-mail them to me or to the Octave mailing list.
#
# Of course, there must exist BUGS. I hope that you use this package and report
# any bugs that you find. When the frequency of bugs start to decrease or cease,
# I will put the package in the `Archive of Octave contributions', at 
# `http://www.tsc.uvigo.es/GTS/Octave/oct_arch.html'.
# 
# NEW FUNCTIONS:
# 
# close_all_fig.m	- close all plot-windows and terminate all gnuplot proc.
# close_fig.m		- close the current or specified plot-window
# fig.m			- creates a new or makes current a specified. plot-window
# gclear.m		- clear the current plot-window
# gnu_i.m		- direct gnuplo interface
# gpurge_tmp_files.m	- purge tmp files created through `tmp_file_name'
# gset.m		- substitute for `set'
# strntok.m		- internal usage, retrieves a token from a string array
# tmp_file_name.m	- give a non-existing file name for posterior usage
# 
# Partially modified Octave functions:
# 
# contour.m
# mesh.m
#
# All other functions are modified Octave functions.
#
# Enjoy it,
#
# Joao Cardoso
#
