[Plplot-cvs] plplot OLD-README.release,NONE,1.1

[hbabcock <hba...@us...>]

Update of /cvsroot/plplot/plplot
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15840

Added Files:
	OLD-README.release 
Log Message:
Added record of past release notes

--- NEW FILE: OLD-README.release ---
PLplot Development Release 5.5.4
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the 
ongoing efforts of the community to improve the PLplot plotting 
package.  Development releases represent a "work in progress", and 
we expect to provide installments in the 5.5.x series every few weeks.  
The next full release will be 5.6.0.

     If you encounter a problem that is not already documented in the 
PROBLEMS file, then please send bug reports to PLplot developers via the 
mailing lists at http://sourceforge.net/mail/?group_id=2915 .

     Please see the license under which this software is distributed
(LGPL), and the disclaimer of all warrantees, given in the COPYING.LIB 
file.


INDEX

1. Build Instructions
2. Changes relative to PLplot 5.5.3
  2.1 API
    2.1.1 PlplotCanvas
    2.1.2 FCI
  2.2 Drivers
    2.2.1 GCW (Gnome 2)
    2.2.2 wxwidgets
3. Changes relative to PLplot 5.3.1
  3.1 API
    3.1.1 Deprecated functions
    3.1.2 Unicode
    3.1.3 Extended cmap0 support
    3.1.4 The PlplotCanvas Widget for Gnome/GTK Applications
  3.2 Drivers
    3.2.1 PostScript
    3.2.2 GD (png, jpeg, gif)
    3.2.3 GCW (Gnome 2)
    3.2.4 AquaTerm (Mac OS X)
    3.2.5 Tk
    3.2.6 wxwidgets


1. Build Instructions

For detailed instructions on how to build and install PLplot from this
tarball, please read the INSTALL file.  The basic procedure is to execute
the following commands:

  ./configure
  make
  make install

     There are a variety of configuration options, and these are explained 
in the INSTALL document, and below as required.  In particular, if you 
want to install the PLplot Programmer's Reference Manual, please use:

  ./configure --with-prebuiltdoc

Note that it is often helpful to use the --with-pkg-config option if your
system has the pkg-config program (typically *nix systems).


2. Changes relative to PLplot 5.5.3 (the previous development release)


2.1 API


2.1.1 PlplotCanvas

PlplotCanvas method wrappers for PLplot functions have dropped
the prefix "pl" from the function name.  For example, the
method plplot_canvas_plline is now plplot_canvas_line.


2.1.2 FCI

Backwards incompatible API change (with respect to 5.5.3, but not with
respect to 5.3.1 since this involves a new feature within the 5.5.x
development releases).  PL_FCI_MARK changed from 0x10000000 to 0x80000000.
This should only affect users who have been inserting absolute FCI (font
characterization integer) changes within their strings to change the font in
mid-string.

2.2 Drivers


2.2.1 GCW (Gnome 2)

Performance improvements have been implemented.

2.2.2 wxwidgets

Initial version of a device to run on the wxWidgets cross-platform GUI (see
http://www.wxwidgets.org/) has been donated by Werner Smekal.  Most examples
work out of the box, but some (e.g., a segfault for example 8) currently
have problems.  More development of this immature device driver is planned.

3. Changes Relative to PLplot 5.3.1 (the previous stable release)


3.1 API


3.1.1 Deprecated functions

plParseOpts, plHLS_RGB, and plRGB_HLS are now deprecated and will eventually
be removed from the API.  Use plparseopts, plhlsrgb, and plrgbhls instead
for all language interfaces.


3.1.2 Unicode

PLplot now supports unicode text.  The escape sequence for unicode
characters is

     #[nnn]

where nnn can be decimal or hexadecimal.  Escape sequences are also defined
to change fonts mid-string.

     There are known bugs for our unicode font implementation that are 
listed in a special section of the PROBLEMS file, but the current 
implementation is good enough so we turn on unicode support by default 
for the psc, ps, png, gif, jpeg, and gcw devices.  Although all examples 
look better with unicode fonts, the new PLplot unicode capabilities are 
especially demonstrated in examples x23 and x24.  (The latter example 
requires special fonts to be installed and at run time environment 
variables have to be set to access them;  see the self-documentation of 
the example 24 source code).  


3.1.3 Extended cmap0 support.

There have been many updates to cmap0 handling in the effort to wipe away 
all vestiges of the old 16 color limit.  The theoretical limit should now 
be 2^15 colors, since the metafile and tk drivers use a short for 
communication of the cmap0 index.  Should be *plenty* for the given 
application, i.e. fixing colors for lines, points, labels, and such.
 
     Since both the metafile & tk data stream formats have changed due to 
the change from U_CHAR -> short for cmap0 index representation, the format
versions have been upgraded.  If you see something like this:
 
  $ x02c -dev tk 
  Error: incapable of reading output of version 2005a. 
  plr_init: Please obtain a newer copy of plserver. 
  Command code: 1, byte count: 14 
  plr_process1: Unrecognized command code 0 
  ... 
 
then you know it's using the wrong version of plserver (in which case 
either you didn't install or your path is wrong). 

     The second example program (multiple bindings available) contains 
a demo of the expanded cmap0 capability.


3.1.4 The PlplotCanvas Widget for Gnome/GTK Applications

PlplotCanvas is a widget for use in Gnome/GTK applications, and
is contained in the libplplotgnome2d library.  A specialzed API is
provided, and bindings are included for the C and Python programming 
languages.  Special example programs that demonstrate the use of 
PlplotCanvas in Gnome/GTK applications are given for each language 
binding.


3.2 Drivers

Some of the drivers have undergone important revisions in order to provide
unicode support.  Several now present TrueType or PostScript fonts by
default, which produces higher-quality output than in the past: see the
examples from the GD (png) driver on the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html .


3.2.1 PostScript

The PostScript driver produces "publication quality" output files.  It
is unicode-enabled, and Type 1 PostScript fonts are used by default.  
Although the Type 1 symbol fonts have a significant number of 
mathemetical symbols available, some key special symbols (squares,
triangles) are missing.  Thus, by default, Hershey fonts are used to 
produce the symbols generated by calls to "plpoin" and "plsym", while 
PostScript fonts are used for calls to PLplot routines that plot text 
strings (e.g., "plmtex").  If you prefer a pure Hershey font environment, 
specify -drvopt text=0, and if you prefer a pure Postscript font 
environment, specify -drvopt hrshsym=0.


3.2.2 GD (png, jpeg, gif)

The GD driver is used to produce png, jpeg, and gif files.  It is 
unicode-enabled, and uses TrueType fonts by default.  The examples on 
the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html were produced using 
this driver.


3.2.3 GCW (Gnome 2)

GCW is a new driver for Gnome 2 that displays plots in a tabbed window.  
The driver is unicode-enabled, and uses TrueType fonts.  The GCW user 
interface supports zooming, and saves to a variety of output file 
formats (ps, psc, png, jpg, gif).  All of the relevant command-line 
options for PLplot are supported.

     A specialized API, which allows interaction with the driver,
is provided in libplplotgnome2d.  Bindings are provided for the C and 
Python programming languages.


3.2.4 AquaTerm (Mac OS X)

AquaTerm is a new driver for Mac OS X that provides PLplot output in 
the AquaTerm graphics terminal program.  Aquaterm is a native Cocoa 
graphics terminal program for Mac OS X that provides a familiar look and 
feel to Mac users.  More details about AquaTerm and how to install it can 
be found at http://aquaterm.sourceforge.net/.

     The driver is unicode-enabled and uses default OS X fonts.

     To install the AquaTerm driver, use the options "--disable-dyndrivers" 
and "--disable-f77" during the configure step of the install process.
 

3.2.5 Tk

The plframe widget (and by extension, the Tk driver) now saves a plot using 
the correct aspect ratio, as represented by the actual window size.  For 
complicit output drivers only, e.g. png.

3.2.6 wxwidgets

Initial version of a device to run on the wxWidgets cross-platform GUI (see
http://www.wxwidgets.org/) has been donated by Werner Smekal.  Most examples
work out of the box, but some (e.g., a segfault for example 8) currently
have problems.  More development of this immature device driver is planned.




PLplot Development Release 5.5.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the 
ongoing efforts of the community to improve the PLplot plotting 
package.  Development releases represent a "work in progress", and 
we expect to provide installments in the 5.5.x series every few weeks.  
The next full release will be 5.6.0.

If you encounter a problem that is not already documented in the PROBLEMS
file then please send bug reports to PLplot developers via the mailing lists
at http://sourceforge.net/mail/?group_id=2915 .

Please see the license under which this software is distributed, and the
disclaimer of all warrantees, given in the COPYING.LIB file.


INDEX

1. Build Instructions
2. Changes Relative to PLplot 5.5.1
  2.1 API
  2.2 Drivers
3. Changes Relative to PLplot 5.3.1
  3.1 API
    3.1.1 Unicode
    3.1.2 Extended cmap0 support
  3.2 Drivers
    3.2.1 PostScript
    3.2.2 GD (png, jpeg, gif)
    3.2.3 GCW "Gnome Canvas Widget"
    3.2.4 AquaTerm (Mac OS X)
    3.2.5 Tk


1. Build Instructions

For detailed instructions on how to build and install PLplot from this
tarball, please read the INSTALL file.  The basic procedure is to execute
the following commands:

     ./configure
     make
     make install

There are a variety of configuration options, and these are explained in the
INSTALL document, and below as required.  In particular, if you want to
install the PLplot Programmer's Reference Manual (which is required for
documentation on any new feature since PLplot 5.3.1), you must use:

     ./configure --with-prebuiltdoc

Note that it is often helpful to use the --with-pkg-config option if your
system has the pkg-config program (typically *nix systems).


2. Changes Relative to our last development release, PLplot 5.5.1

Progress toward our next major release with documentation improvements and a
substantial number of minor tweaks and bug fixes.

2.1 API

No change.


2.2 Drivers

No change.


3. Changes Relative to our last stable release, PLplot 5.3.1


3.1 API


3.1.1 Unicode

PLplot now allows unicode text, and this is detailed in the PLplot
Programmers Reference Manual in the section on "Setting Character
Attributes".  The escape sequence for unicode characters is

     #[nnn]

where nnn can be decimal or hexadecimal.  Escape sequences are also defined
to change fonts mid-string.

There are known bugs for our unicode font implementation that are listed in
a special section of the PROBLEMS file, but the current implementation is
good enough so we turn on unicode support by default for the psc, ps, png,
gif, jpeg, and gcw devices. Although all examples look better with unicode
fonts, the new PLplot unicode capabilities are especially demonstrated in
examples x23 and x24.  (The latter example requires special fonts to be
installed and at run time environment variables have to be set to access
them, see the self-documentation of the example 24 source code).  


3.1.2 Extended cmap0 support.

There have been many updates to cmap0 handling in the effort to wipe away all
vestiges of the old 16 color limit.  The theoretical limit should now be 2^15
colors, since the metafile and tk drivers use a short for communication of the
cmap0 index.  Should be *plenty* for the given application, i.e. fixing colors
for lines, points, labels, and such.
 
Since both the metafile & tk data stream formats have changed due to the
change from U_CHAR -> short for cmap0 index representation, the format
versions have been upgraded.  If you see something like this:
 
$ x02c -dev tk 
Error: incapable of reading output of version 2005a. 
plr_init: Please obtain a newer copy of plserver. 
Command code: 1, byte count: 14 
plr_process1: Unrecognized command code 0 
... 
 
then you know it's using the wrong version of plserver (in which case either 
you didn't install or your path is wrong). 

The second example program (multiple bindings available) contains a demo of
the expanded cmap0 capability.


3.2 Drivers

Some of the drivers have undergone important revisions in order to provide
unicode support.  Several now present TrueType or PostScript fonts by
default, which produces higher-quality output than in the past: see the
examples from the GD (png) driver on the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html .


3.2.1 PostScript

The PostScript driver is unicode-enabled, and Type 1 PostScript fonts are
used by default.  Although the Type 1 symbol fonts do have a significant
number of mathemetical symbols available some key special symbols (squares,
triangles) are missing so that by default Hershey fonts are used to produce
the symbols generated by calls to "plpoin" and "plsym" while PostScript
fonts are used for calls to PLplot routines that plot text strings (e.g.,
"plmtex").  If you prefer a pure Hershey font environment, specify -drvopt
text=0, and if you prefer a pure Postscript font environment, specify
-drvopt hrshsym=0.

Tranforms to the text (i.e., rotations, shears)
have been dramatically improved, and the PostScript driver now produces
"publication quality" output with the default PostScript fonts for text
and Hershey fonts for special symbols.


3.2.2 GD (png, jpeg, gif)

The GD driver is unicode-enabled, and uses TrueType fonts by default.  The
examples on the PLplot Web site at
http://plplot.sourceforge.net/examples/index.html were produced using this
driver.


3.2.3 GCW "Gnome Canvas Widget"

The GCW "Gnome Canvas Widget" is a new driver that provides PLplot output in
a tabbed Gnome window.  It can alternatively be used to drive a special
widget called the PlplotCanvas that can be embedded in Gnome applications.
The driver, associated widget, and specialized API are fully documented in
the PLplot Programmer's Reference Manual in the sections titled "The GCW
Driver" and "Embedding Plots in Gnome/GTK Applications", respectively.

The GCW driver is unicode-enabled, and uses TrueType fonts by default.

Special examples that demonstrate the use of the PlplotCanvas are provided
for both the C and Python programming languages.

To install the GCW driver, use the "--enable-gcw" option during the
configure step of the install process.

For more information on GTK, see http://www.gtk.org/ .


3.2.4 AquaTerm (Mac OS X)

AquaTerm is a new driver that provides PLplot output in the AquaTerm
graphics terminal program. Aquaterm is a native Cocoa graphics terminal 
program for Mac OS X that provides a familiar look and feel to Mac users. 
More details about AquaTerm and how to install it can be found at 
http://aquaterm.sourceforge.net/.

The driver is unicode-enabled, however it currently only supports the 
default OS X fonts which are not TrueType.

To install the AquaTerm driver, use the options "--disable-dyndrivers" and
"--disable-f77" during the configure step of the install process.
 

3.2.5 Tk

The plframe widget (and by extension, the Tk driver) now saves a plot using the
correct aspect ratio, as represented by the actual window size.  For complicit
output drivers only, e.g. png.




PLplot Development Release 5.5.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the 
ongoing efforts of the community to improve the PLplot plotting 
package.  Development releases represent a "work in progress", and 
we expect to provide installments in the 5.5.x series every few weeks.  
The next full release will be 5.6.0.

Feedback on this development release can be communicated to PLplot
developers via the mailing lists at 
http://sourceforge.net/mail/?group_id=2915 .

Please see the license under which this software is distributed, and the
disclaimer of all warrantees, given in the COPYING.LIB file.


INDEX

1. Build Instructions
  1.1 Tcl
2. Changes
  2.1 API
  2.2 Drivers


1. Build Instructions

For detailed instructions on how to build and install PLplot from this
tarball, please read the INSTALL file.  The basic procedure is to execute
the following commands:

     ./configure
     make
     make install

There are a variety of configuration options, and these are explained in the
INSTALL document, and below as required.  In particular, if you want to
install the PLplot Programmer's Reference Manual (which is required for
documentation on any new feature since PLplot 5.3.1), you must use:

     ./configure --with-prebuiltdoc

Note that it is often helpful to use the --with-pkg-config option if your
system has the pkg-config program (typically *nix).


1.1 Tcl

Due to unresolved problems in the build process, tcl has been temporarily
disabled for this release.

If you must have tcl, here are the instrutions.  DO NOT ATTEMPT THIS
UNLESS YOU ARE SURE YOU KNOW WHAT YOU ARE DOING.

  1) Move all plplot files in /usr/lib and /usr/local/lib into a
     temporary directory.

  2) Use the --enable-tcl and --enable-itcl options during configure.


2. Changes


2.1 API


2.2 Drivers




PLplot Development Release 5.5.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a routine development release of PLplot, and represents the ongoing efforts of the community to improve the PLplot plotting package.  The next full release will be 5.6.0.


INDEX

1. Build Instructions
2. Changes
  2.1 API
    2.1.1 Unicode
  2.2 Drivers
    2.2.1 Postscript
    2.2.2 GD (png, jpeg, gif)
    2.2.3 GCW "Gnome Canvas Widget"


1. Build Instructions

For detailed instructions on how to build and install PLplot from this tarball, please read the INSTALL file.  The basic procedure is to execute the following commands:

     ./configure
     make
     make install

There are a variety of configuration options, and these are explained in the INSTALL document, and below as required.  In particular, if you want to build and install the PLplot Programmer's Reference Manual (which is required for documentation on any new feature since PLplot 5.3.1), you must use:

     ./configure --enable-builddoc

Detailed instructions on building the documentation, including the packages that you will need for a successful build, are provided in this tarball under doc/docbook/README.developers.


2. Changes


2.1 API


2.1.1 Unicode

PLplot now allows unicode text, and this is detailed in the PLplot Programmers Reference Manual in the section on "Setting Character Attributes".  The escape sequence for unicode characters is

     #[nnn]

where nnn can be decimal or hexdecimal.  Escape sequences are also defined to change fonts mid-string.

The new unicode capabilities are demonstrated in example x23.


2.2 Drivers

Some of the drivers have undergone important revisions in order to provide unicode support.  Several now present truetype or postscript fonts by default, which produces higher-quality output than in the past: see the examples from the GD (png) driver on the PLplot Web site at http://plplot.sourceforge.net/examples/index.html.


2.2.1 PostScript

The PostScript driver is unicode-enabled, and Type 1 PostScript fonts are used by default.  Because many symbols are missing from the Type 1 PostScript fonts, Hershey fonts are used for calls to "plpoin".  Tranforms to the text (i.e., rotations, shears) have been dramatically improved, and the PostScript driver now produces "publication quality" output.


2.2.2 GD (png, jpeg, gif)

The GD driver is unicode-enabled, and uses truetype fonts by default.  The examples on the PLplot Web site at http://plplot.sourceforge.net/examples/index.html were produced using this driver.


2.2.3 GCW "Gnome Canvas Widget"

The GCW "Gnome Canvas Widget" is a new driver that provides PLplot output in a tabbed Gnome window.  It can alternatively be used to drive a special widget called the PlplotCanvas that can be embedded in Gnome applications.  The driver, associated widget, and specialized API are fully documented in the PLplot Programmer's Reference Manual in the sections titled "The GCW Driver" and "Embedding Plots in Gnome/GTK Applications", respectively.

The GCW driver is unicode-enabled, and uses truetype fonts by default.

Special examples that demonstrate the use of the PlplotCanvas are provided for both the C and Python programming languages.

To install the GCW driver, use the "--enable-gcw" option during the configure step of the install process.