		GNUPLOT Version 5.2.4 Release Notes
		===================================

These release notes are for version 5.2 patchlevel 4 (5.2.4).

This release contains
- a fix for a serious regression in 5.2.3 (spurious evaluation of logscale
  coordinates as UNDEFINED)
- re-implementation of the "refresh" command to correct regressions in
  5.2.0 through 5.2.3
- sanity checks for several invalid command sequences found by fuzzing
- several minor bug-fixes
- two recent minor changes back-ported from the development version

Please see the ChangeLog file for a complete list of changes made during the
course of development from 5.0 to 5.2.

Release Notes date: 31-May-2018

CHANGES IN 5.2.4
================
* NEW "call" parameters ARG1, ARG2, ... are also present as ARGV[1]...ARGV[ARGC]
* CHANGE generalize the test for missing data flag in input data
* CHANGE "set []range writeback" is now essentially always in effect
* CHANGE consistent placement of timestamp at true bottom of page
* FIX spurious evaluation of logscale coordinates as UNDEFINED
* FIX column header title assignments for histogram with errorbars
* FIX re-implement "refresh" command to use autoscale writeback/restore
* FIX font-handling bug; line-spacing of previous font still in effect
* FIX post, svg, dumb terminals: early fontsize initialization

CHANGES IN 5.2.3
================
* NEW "set grid {no}vertical" adds grid lines in the xz and yz planes
* NEW "set cntrparam {firstlinetype N} {{un}sorted}"
* CHANGE drop non-working support for YIQ color space
* CHANGE expand \n characters when printing into a datablock
* CHANGE allow contour plots to opt out of hidden3d processing
* CHANGE special-case code to speed up handling of logscale axes
* CHANGE do not write GPFUN_* variables to "save" output file
* CHANGE default to density 100 for "set fs solid", 50 for "set fs transparent"
* FIX potential buffer overflow in gprintf formats containing %%
* FIX immediate response to ctrl-Z when libreadline is used for input
* FIX warning messages inside a bracketed clause could trigger early exit
* FIX tweak logscale tic range limits and minor tic generation intervals
* FIX stats FOO using 'namedcolumn' name columnhead
* FIX clipping of INRANGE->UNDEFINED line segments
* FIX use of logscale y axis in "set view map" or "set pm3d map" modes
* FIX placement of colorbox in "set view map" mode
* FIX autoscaled axis range of logscale axes in "set view map" mode
* FIX polar mode "with yerrorbars" error bars are radial, not vertical
* FIX clipping of circles whose center is offscreen to the left or bottom
* FIX canvas terminal: apply both color and alpha channel to points and lines
* FIX svg terminal: apply current color to dots
* FIX qt terminal: include "notitle" plots in accounting for toggle operations
* FIX svg terminal: point plot empty title produced spurious mousing directive
* FIX tikz terminal: failed to recognize dashtype 1

CHANGES IN 5.2.2
================
* NEW set table separator {tab|comma|"char"} allows creation of csv files
* NEW hotkey for changing azimuth in 3D plots with mousing
* NEW titles for "splot .. with lines" can be placed at {beg|end} of plotted line
* NEW Rework gstrptime() to handle relative time formats tH tM tS
* NEW command 'set rgbmax <value>' controls interpretation of input RGB values
* CHANGE restore pre-5.2 interpretation of logscaled tic increment as a multiplier
* CHANGE allow mixed use of in-key plot titles and manually placed titles
* CHANGE more documentation on use of pipes to input data
* FIX autoscaling of plots with spline or bezier smoothing
* FIX autoscaling of plots with linked axes where data is plotted on x2 or y2
* FIX "with filledcurves below y=foo" mishandled the case of y value exactly = foo
* FIX [windows] repair breakage of stderr/stdout redirection to console
* FIX postscript terminal artifacts when drawing dot/dash circles
* FIX handle empty range on logscale y axis as a warning, not an error
* FIX allow set xrange [explicit_min:*] for stacked histograms


FEATURES INTRODUCED IN VERSION 5.2
==================================

* NEW plot styles and options
	o splot ... using <x>:<y>:<z>:<zlow>:<zhigh> with zerrorfill
	o "set jitter" allows creation of bee swarm plots
	o data filter "bins" sorts input into equal width bins on x
	o "with points" and "with linespoints" accept `pointtype variable`
	o hidden3d now treats 'image' and 'rgbimage' as occluding rectangles
	o "smooth fnormal" plots normalized frequency
	o allow sampling interval in range specifiers for pseudofiles '+' '++'
	o "plot with table" can handle string-valued output columns

* NEW polar mode improvements and extensions
	o "set [m]ttics" places theta tics and labels on perimeter of polar grid
	o "set rlabel" places a label above the r axis
	o "set rrange [90:0]" plots in celestial horizontal coordinates
	o "set border polar" uses border linetype for perimeter of polar plot
	o "set theta <origin> <sense>" orientation of polar coordinate theta
	o label, arrow, and object positions may be given in polar coordinates

* NEW nonlinear coordinate systems
	o "set nonlinear <axis> via f(axis) inverse g(axis)"
	o "set log" re-implemented as special case of "set nonlinear"

* NEW data type array[size]
	o any element A[i] of an array may be an integer, complex, or string value
	o operator |A| gives the cardinality of array A

* NEW commands and command options
	o "break" exits from iteration loop
	o "continue" begins next iteration immediately
	o "toggle {<plotno> | "plottitle" | all}"
	o "set pm3d lighting" specifies lighting model with specular highlighting
	o "set table OUTFILE {append}"
	o "set minussign" and "set micro" (first appeared in 5.0.5)
	o "set view azimuth <angle>" controls azimuth of the z axis in 3D plots
	o "save fit <filename>" replaces deprecated command "update"
	o "set style textbox" supports fillcolor and bordercolor

* NEW terminals and terminal options
	o terminal domterm (supports in-line SVG in DomTerm terminal emulator)
	o terminal sixelgd (sixel terminal graphics using gdlib)
	o svg 'standalone' embeds images rather than including by reference
	o windows terminal supports saving graph as bitmap
	o windows graph windows can be docked to the wgnuplot text window
	o wxt supports saving graph as EMF on Windows
	o wxt supports printing on Windows
	o dumb supports ANSI colors and filled polygons

* NEW gnuplot on Windows
	o converts Unicode (BMP) input to current `set encoding`, including UTF-8
	o the program is system DPI aware


CHANGES FROM PREVIOUS VERSIONS
==============================

Backward compatibility
----------------------

Gnuplot development assigns very high priority to backward compatibility
with earlier versions.  However changes introduced in version 5 can affect
the operation of some version 4 scripts.  Please see section
"Differences from Version 4" in the User Manual.

Deprecated commands
-------------------

The "update" command is still recognized in version 5.2 but is deprecated
and will be removed in the next version. Use "save fit" instead.

Scope of variables
------------------

The control variable of an iteration loop is strictly limited in scope
to the iteration it controls.  The value of any previous variable with
that name is restored after iteration.  The same is true for an iteration
associated with a sampling range in a plot or splot command.

Other minor changes
-------------------

* Auto-placement of axis labels, title, and other text items
  on the page has changed slightly since version 5.0
* point style associated with "plot with labels" is shown in the key
* text properties for the key title are separate from the key entries
* order of margins in `set margins <left>, <right>, <bottom>, <top>`
* Store and reuse x,y dimensions at the time image data is read in
* Some STATS_foo variables are of type integer rather than real (complex) 
* ^R starts a backward search when using the built-in readline
* Only update axis->data_min/max if the point being stored is INRANGE
* auto-generation of minitics on logscale axis has changed
* revised printing dialogs on Windows
* preserve whitespace following opening { in enhanced text strings
* windows terminal provides better oversampling
* New default "set key fixed" prevents 3D key box from rotating with plot
* windows terminal also uses GDI+ for printing and copy-to-clipboard
* raxis/polar grid can coexist with Cartesian axes
* evaluation of norm(x) or x**y returns 0 on floating underflow
* support for space-in-x11-raises-KDE3-konsole is now a configure option
* don't use loadpath to choose output directory for "save"
* GNUTERM may contain terminal options in addition to bare terminal name
* RGB color components of "with rgbimage" are always in the range [0:255]
  (i.e. not affected by "set cbrange")


ONLINE DEMO PLOTS
=================

Demo plots illustrating new and old features are online at
  http://gnuplot.sourceforge.net/demo_5.2/


KNOWN ISSUES
============

* If you configure in the wxt terminal on linux you may need
  to manually set the environmental variable TERMLIBS during configuration:

    * TERMLIBS="-lX11"  ./configure

* Some people have reported runtime problems when the wxt terminal uses 
  wxgtk library versions 3.0.x.  If you have the option of linking against
  wxgtk version 2.8 instead, this may be a better choice.

* Compilation on Solaris may require adding -liconv to LIB_FLAGS
  Building the plugin demo with a SunPro Compiler requires changing the
  build flags as shown in comments in ./demo/plugin/Makefile.am

* Font initialization on OSX can be very slow, causing the qt terminal to
  issue warning or error messages for the first plot command.

* The antialiasing option produces artifacts in some versions of Qt.
  In particular point types 1 and 2 appear unbalanced due to shading.

* You can configure support for both wxt and qt into the same gnuplot
  executable, but only one of these can be used in any given gnuplot session.

* The gnuplot build system is not very good at figuring out where to find
  or install LaTeX-related files.  This can affect use of the lua/tikz
  and ConTeXt terminals.

* Using mouse clicks to toggle individual plots on/off does not always
  work correctly for multiplots if the key box is opaque.
  Toggling plots drawn in hidden3d mode (hidden line removal) does not work.

* Mouse double-click to export terminal coordinates to the X11 clipboard
  no longer works reliably, and may be deprecated in the future.


		 NOTES TO PACKAGERS AND TESTERS 
		===============================

Obsolete or deprecated components
---------------------------------

The "gnuplot mode" elisp and TeX files for use with emacs are now
maintained as a separate project: https://github.com/bruceravel/gnuplot-mode
so there is no longer a configuration option --with-lisp-files.

The TeX tutorial produced by --with-tutorial is horribly out of date.

./configure --enable-backwards-compatibility will allow use of some
deprecated syntax from old gnuplot versions.  However the result of
using these deprecated commands may not match the old version output.


Configuration options for interactive use
-----------------------------------------

The 5.2 source code supports three primary cross-platform interactive
modes in addition to several platform-specific modes.

1) Qt
   The qt terminal supports interactive display with menu-driven
   output to png, svg or pdf.  If either Qt4 or Qt5 is detected by the
   configure script, this will be the default terminal.  It is now the
   fastest and most full-featured interactive terminal option.

   To disable this terminal:
      ./configure --without-qt

   To force use of Qt4 even if Qt5 is present:
      ./configure --with-qt=qt4

2) Cairo/pango/wxWidgets
   This set of terminals includes
   - pngcairo, pdfcairo, epscairo, and cairolatex for output to a file
   - wxt for interactive display
   All of these will be built by default if the configuration script finds
   the required libcairo, libpango, libcairo, libwxgtk, and related
   support libraries
   To disable these terminals:
       ./configure --without-cairo
       ./configure --with-cairo --disable-wxwidgets

3) X11 (the "classic" interactive interface)
   This used to be the preferred interactive interface, but the newer
   wxt and qt terminals offer nicer output and a wider range of features.


Options for output to files
---------------------------

Of course the terminals (output modes) present in previous gnuplot versions
are also still available. These include, among many more obscure options:

- png/jpeg/gif output via libgd
- PostScript (*.ps or *.eps)
- Many flavors of TeX/LaTeX output, including TikZ and ConTeXt
- Bitmapped output to support older devices (e.g. HP deskjet, epson, and
  seiko printers, pbm bitmapped graphics files) is available if needed
  but is no longer configured in by default.
      ./configure --with-bitmap-terminals

Options for generating interactive plots for web display
--------------------------------------------------------

- Mouseable output for display on the web can be created using either 
  the canvas terminal (HTML5 2D canvas element) or the svg terminal.

			OTHER NOTES
			===========

Installation
------------

You can download a source tarball for gnuplot version 5.2.3 from the 
gnuplot development site on SourceForge.
	http://sourceforge.net/projects/gnuplot

Installation instructions are available in the source itself; the short
version for linux/unix-like systems is to unpack the tarball and then
<PRE>
build it:
      cd gnuplot-5.2.3 ; ./configure ; make
test it:
      make check
install it:
      make install
</PRE>

Pay careful attention to the output of the ./configure script.
It may indicate that some output drivers have been omitted because the
necessary support libraries were not found.  In general you need to have
previously installed the "*-devel-*" versions of these libraries. 


Support
-------
Please report all bugs and installation problems to the bug tracker
on SourceForge:
	https://sourceforge.net/p/gnuplot/bugs/

There is also an gnuplot discussion forum on usenet group
	comp.graphics.apps.gnuplot


Development
-----------
Gnuplot development is ongoing. The development branch contains preliminary
implementations of new features.  The current development version is 5.3
(odd minor number) and will eventually be released as version 5.4 (even 
minor number).  Bugfixes to version 5.2 will appear in patchlevel releases
5.2.1, 5.2.2, etc., approximately twice a year or as needed to correct a
serious problem.

Note: development has recently moved from cvs to git. Many of the files
in the 5.2.4 source distribution still contain a cvs version identifier
$RCSid and date, but these are not current if the file has been changed
since the move to git.
