This instructions are somehow out of date. Read also the USAGE file.


Install:

plplot_octave_org.h is the main important file. It is a massaged version
of plplot's plplot.h file, ready for use with Holt's matwrap, which you
can find at

	http://lnc.usc.edu/~holt/matwrap/

As usual, you should get the last version, 0.57 at the time of this
writing. You also need perl.
If you don't have Holt's matwrap, don't worry, a copy is available
in this distribution and will be automatically used.

You must compile PLplot with shared libraries, which 'configure' does
by default if your OS is supported.

Make sure that you have octave-2.0.16 or latter, matwrap and perl.
Make sure that you have a correctly installed octave, configured with
--enable-shared and --enable-dl. The command

	ldd `which octave`

should report octave dynamic libs, liboctave.so, libcruft.so and
liboctinterp.so

Configure PLplot with the --enable-octave, which is the default,
plus any other options in the main directory, e.g.,

	./configure --enable-octave

and then type 'make'.

Testing:

Before installing, you can test plplot_octave:
[you must install PLplot before, this will change soon]

'cd' to the directory bindings/octave within the build tree.

If you have another version of plplot installed, check, after invoking
octave and making same plots, the plplot version, typing "plgver'" (note
the apostrophe in plgver, meaning transpose). You should get the same
version that you have just compiled, not the installed version.

Invoke octave, (the path is automatically set by the .octaverc file
which exists in that directory).

There are several Octave demos, 'p1' up to 'p20'. Try them:

octave> for i=[1:15 19:20]; feval(sprintf("p%d",i));kbhit;endfor;oneplot

and a set of script files that emulate the well known x??c plplot demos. Try:

octave> plplot_octave_demo

Demo x14c might fail, if you have problems with tk.

You can set some preferences in the file 'pldef.m'

Don't worry if you see the following warning:

	warning: empty matrix found in matrix list

You can avoid it setting "empty_list_elements_ok = 1;" in your
~/.octaverc Octave startup file (see below). This is being corrected
in plplot_octave, meanwhile keep remembering me :-).


Using:

After testing, type "make install". The default path to instalation is
$prefix/share/plplot_octave. If you don't like it, reconfigure PLplot
using the configure option --prefix=<preferred path> and rebuild and
install, or try "make install PREFIX=<install path>"; this last option
might not yet work. In the following discussion the default prefix of
/usr/local is used.

There are three paths that you can add to LOADPATH:

1-The *needed* path is /usr/local/share/plplot_octave//
2-The demos path is /usr/local/lib/plplotx.y.z/examples/octave//
3-The path to switch between PLplot and gnuplot is /usr/local/share/octave//

Note: If you are using octave2.9 then LOADPATH is obsolete and you must 
use addpath instead. Note also that a trailing // no longer includes 
all subdirectories. You must explicitly add them. In particular you need
the support subdirectory of plplot_octave.

If you want to test the installation with the demos, call octave and
set the LOADPATH as in

LOADPATH ="/usr/local/lib/plplotx.y.z/examples/octave//:\
/usr/local/share/plplot_octave//:"

You can now repeat the demos you already tried. Or just type 'p1'<CR>,
'p2'<CR> ... my preferred test is "plot(sin(1:10),'-o')". As usual,
'help command' gives you some help.

For everyday usage, you must setup your LOADPATH to include the install
path *before* the standard Octave LOADPATH. The best way of doing it
is to use the file ~/.octaverc to set it up. Add the following line to
it, using of course the real install prefix:

LOADPATH="/usr/local/share/plplot_octave//:<other path>:<other path>";

You can use the standard Octave plot commands if in the LOADPATH a
":" appears *before* the plplot_octave path, as in

LOADPATH=":/usr/local/share/plplot_octave//:<other path>:<other path>";

You can use the command toggle_plplot_use to change between the two
sets of commands, but for this you must set an additional path in LOADPATH.
It must be set as:

LOADPATH="/usr/local/share/plplot_octave//:/usr/local/share/octave//:"

You are done. You can now use almost all the standard Octave plot
commands plus a whole bunch of new ones.

If you want to use another driver othen than the "xwin" one, which is
the defaul, you must first open a new plot window using "figure", e.g.

	figure(1,"tk")
	p1
	fig(2,"xwin")	# fig() is an alias to figure()
	p2

To print or save a plot, use
	save_fig("foo.ps")
	save_fig("|lp","ps")

Use `lp_setup' to setup your printer.

If you just want to use the PLplot API, use it as you would from a C
program, with the exception that you don't need to specify matrices
dimensions; e.g., for plline(n,x,y) you just need to call it as
plline(x,y), where x and y are column vectors. Look at the various
x??c.m examples in the demos directory.

You can't call API functions whose arguments are pointers to
functions. Some wrappers for common situations are however available.

What you get:

You have a 'demo' directory, with the equivalent octave script files
x??c.m of PLplot C demos, and some new demos, p??.m.

You have a 'PLplot' directory with modified versions of the standard
octave plot command, plus a lot of new ones ready for Octave usage. You
must have it on your LOADPATH before the standard octave/gnuplot plot
scripts. If you install it in the default directory, use the octave
command `octave_plplot_path' to setup the path. You can change between
the default gnuplot plotter and octave_plplot using the octave command
`use_plplot'.

You have a misc directory with some other octave demos/utilities.

You have an etc directory where the "documentation" is (not anymore,
documentation is built from the main documentation file, api.xml.

You have the directory where the README, INSTALL, PROBLEMS,
BUGS, ToDo, are, plus 'plplot_octave_org.h', massage.c, etc.

As with every program, except D. Knuth ones, the programs in this
package are not finished nor bug free. Please report bugs and send
patches. I will not send checks for each bug discovered :-)

Enjoy,

Joao

Update for octave 2.9 by Andrew Ross.
