fix stuff

Don't run gnuplot process connected to stdout

.gitignore

@@ -1,3 +1 @@
-*.jl.cov
-*.jl.*.cov
-*.jl.mem
+docs/build/

.travis.yml

@@ -1,21 +1,26 @@
 ## Documentation: http://docs.travis-ci.com/user/languages/julia/
 language: julia
+
 os:
   - linux
-  - osx
+#  - osx
+
 julia:
-  - 1.0
-  - nightly
+  - 1.5
+#  - nightly
+
 notifications:
   email: false
-git:
-  depth: 99999999
 
-## uncomment the following lines to allow failures on nightly julia
-## (tests will run but not make your overall status red)
-matrix:
-  allow_failures:
-    - julia: nightly
+#matrix:
+#  allow_failures:
+#    - julia: nightly
+
+addons:
+  apt:
+      packages: gnuplot5
+#  homebrew:
+#      packages: gnuplot
 
 
 ## uncomment the following lines to override the default test script

ChangeLog.md

@@ -0,0 +1,121 @@
+# Version 1.4.1 (released on: )
+- New features:
+	* Implicit recipes can now returns a `Vector{PlotElement}`;
+
+	* Allow using single quotes in output file names (#52);
+
+	* New function: `palette_levels()` can be used to modify palette levels before passing them to gnuplot;
+
+- Bugfix:
+	* Fixed `BoundsErrors` in `hist()` (#49);
+
+	* Fixed problem when generating documentation (#51);
+
+
+# Version 1.4.0 (released on: May 5, 2021)
+- New features:
+    * Missing values are accepted if the input arrays have `eltype <:
+      AbstractFloat`;
+
+    * Missing values are also accepted in calls to `hist`;
+
+	* VSCode and Pluto sessions are now properly handled (#35 and #43);
+
+- Bugfix:
+	* Multiplot were not displayed in Jupyter (#25);
+
+	* `gpvars()` fails if gnuplot character encoding is utf8
+      (#24);
+
+
+# Version 1.3.0 (released on: Apr. 29, 2020)
+
+- New features:
+    * The new `dgrid3d()` allows to interpolate scattered 2D data on a
+       2D regular grid;
+
+    * The `Options` structure features a new `mime` field containing a
+      dictionary to map a MIME type to gnuplot terminals;
+
+    * The `Options` structure features a new `gpviewer` field allowing
+      to choose the display behaviour (using either gnuplot
+      interactive terminals or anexternal viewer such as Jupyter or
+      Juno);
+
+    * The `save()` function now accepts a `MIME` argument in place of
+      the `term=` keyword.  The actual terminal is retrieved from the
+      `Options.mime` dictionary;
+
+    * The `contourlines()` function now accepts `AbstractVector` and
+      `AbstractMatrix` as arguments, rather than `Vector` and
+      `Matrix`;
+
+    * The `contourlines()` function now accepts a `fractions` input to
+      generate contours encompassing given fractions of the total
+      counts in a 2D histogram;
+
+    * The `palette()` function now accept a boolean `smooth` keyword,
+      allowing to interpolate a discrete palette into a continuous one.
+
+- Breaking changes:
+    * The `Options` structure no longer provides the `term_svg` and
+      `term_png` fields.  They have been replaced by the `mime`
+      dictionary.
+
+
+# Version 1.2.0 (released on: Apr. 20, 2020)
+
+- New features:
+    * REPL mode: a new `Gnuplot.repl_init()` function is available to
+      install a gnuplot REPL;
+
+    * Implemented the "recipe" mechanism: the `recipe()` function can
+      now be extended to register new implicit recipes to display
+      data;
+
+    * `@gp` and `@gsp` now accepts a `Gnuplot.PlotElements` object,
+      containing commands, data and plot specifications in a single
+      argument;
+
+    * The `linetypes` function now accept the `lw`, `ps` (to set the
+      line width and point size respectively), and the `dashed` (to
+      use dashed patterns in place of solid lines) keywords;
+
+    * The new `Gnuplot.options.term::String` field allows to set the
+      default terminal for interactive sessions;
+
+    * New functions: `gpvars()` to retrieve all gnuplot variables,
+      `gpmargins()` to retrieve current plot margins (in screen
+      coordinates, `gpranges()` to retrieve current plot axis ranges;
+
+    * New keywords accepted by `@gp` and `@gsp`: `lmargin`, `rmargin`,
+      `bmargin`, `tmargin`, `margins`, to set plot margins;
+
+    * Implemented new implicit recipes to display histograms (as
+      returned by `hist()`), contour lines (as returned by
+      `contourlines()`) and images;
+
+    * Implemented automatic display of plots in both Jupyter and Juno;
+
+    * Documentation updated;
+
+
+- Breaking changes:
+    * The 2D matrix are now sent to gnuplot in a column-major order,
+      to comply with Julia array layout;
+
+
+- Bugfix:
+    * When a `Vector{String}` is passed to `driver()` it used to be
+    modified, and couldn't be used again in a second call.  Now the
+    original is preserved;
+
+    * `contourlines()` used to return a single blanck line to
+    distinguish iso-contour lines, and this may cause problems in 3D
+    plot.  Now two blanck lines are returned;
+
+
+# Version 1.1.0 (released on: Apr. 09, 2020)
+
+- First production ready version;
+- Completed documentation and example gallery;

Project.toml

@@ -0,0 +1,24 @@
+name = "Gnuplot"
+uuid = "dc211083-a33a-5b79-959f-2ff34033469d"
+version = "1.4.1"
+
+[deps]
+ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
+ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
+Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+REPL = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+ReplMaker = "b873ce64-0db9-51f5-a568-4457d8e49576"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StructC14N = "d2514e9c-36c4-5b8e-97e2-51e7675c221c"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[compat]
+ColorSchemes = "^3.12"
+ColorTypes = "^0.11"
+Colors = "^0.12"
+DataStructures = "^0.18"
+ReplMaker = "^0.2"
+StatsBase = "^0.33"
+StructC14N = "^0.3"
+julia = "^1.6"

README.md

@@ -1,208 +1,92 @@
 # Gnuplot.jl
-## A Julia interface to Gnuplot.
+## A Julia interface to gnuplot.
 
 [![Build Status](https://travis-ci.org/gcalderone/Gnuplot.jl.svg?branch=master)](https://travis-ci.org/gcalderone/Gnuplot.jl)
-
-**Gnuplot.jl** allows easy and fast use of [Gnuplot](http://gnuplot.info/) as data visualization tool in Julia.  Its main features are:
-
-- transparent interface between Julia and gnuplot to exploit all functionalities of the latter, both present and future ones;
-  
-- fast data transmission to gnuplot through system pipes (no temporary files involved);
-  
-- handles multiple gnuplot process simultaneously;
-
-- support for multiplots;
-
-- save sessions into gnuplot scripts;
-
-- extremely concise syntax (see examples below) makes it ideal for interactive data exploration;
-
-- very easy to use: if you know gnuplot you're ready to go.
+[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](LICENSE.md)
+[![DocumentationStatus](https://img.shields.io/badge/docs-stable-blue.svg?style=flat)](https://gcalderone.github.io/Gnuplot.jl/v1.4.0/index.html)
 
 
-The purpose is similar to the [Gaston](https://github.com/mbaz/Gaston.jl) package, but **Gnuplot.jl** main focus is on on the syntax conciseness and ease of use.
+**Gnuplot.jl** is a simple package able to send both data and commands from Julia to an underlying [gnuplot](http://gnuplot.sourceforge.net/) process.  Its main purpose it to provide a fast and powerful data visualization framework, using an extremely concise Julia syntax. It also has automatic display of plots in Jupyter, Juno and VS Code.
 
 
 ## Installation
-In the Julia REPL type:
 
+Install with:
 ```julia
-Pkg.add("Gnuplot")
+]add Gnuplot
 ```
+A working [gnuplot](http://gnuplot.sourceforge.net/) package must be installed on your platform.
 
-You'll also need [gnuplot](http://gnuplot.info/) (ver. >= 4.7) installed on your system.
+You may check the installed **Gnuplot.jl** version with:
+```julia
+]st Gnuplot
+```
+If the displayed version is not v1.4.0 you are probably having a dependency conflict. In this case try forcing installation of the latest version with:
+```julia
+]add Gnuplot@1.4.0
+```
+and check which package is causing the conflict.
 
 
-## Usage:
-The simplemost plot ever can be generated with just 8 characters:
-``` Julia
+Test package:
+```julia
 using Gnuplot
-@gp 1:10
-```
-
-A slightly more complicated one showing a parabola with a solid line and a title:
-``` Julia
-x = 1:10
-@gp x x.^2 "w l tit 'Parabola'"
-```
-
-A real life example showing some random noise generated data:
-
-``` Julia
-# Create some noisy data...
-x = range(-2pi, stop=2pi, length=100);
-y = 1.5 .* sin.(0.3 .+ 0.7x) ;
-noise = randn(length(x))./2;
-e = 0.5 * fill(1., length(x));
-
-# ...and show them using gnuplot.
-@gp("set key horizontal", "set grid", title="My title",
-    xrange=(-7,7), ylabel="Y label", xlab="X label", 
-    x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
-    x, y+noise, e, "w errorbars t 'Data'");
-```
-
-That's it for the first plots. The syntax should be familiar to most gnuplot users, with this code we:
-- set a few gnuplot properties (`key` and `grid`);
-- set the X axis range and Y axis label;
-- send the data to gnuplot;
-- plot two data sets specifying a few details (style, line width, color, legend, etc...).
-
-Note that this simple example already covers the vast majority of use cases, since the remaining details of the plot can be easily tweaked by adding the appropriate gnuplot command.  Also note that you would barely recognize the Julia language by just looking at the `@gp` call since **Gnuplot.jl** aims to be mostly transparent: the user is supposed to focus only on the data and on the gnuplot commands, rather than the package details.
-
-If you set the verbose option (`setverbosity(true)`, which is `false` by default) you'll be able to see all the communication taking place between the **Gnuplot.jl** package and the underlyng Gnuplot process.  Repeating the last command:
-```Julia
-julia> @gp("set key horizontal", "set grid", title="My title",
-    xrange=(-7,7), ylabel="Y label", xlab="X label", 
-    x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
-    x, y+noise, e, "w errorbars t 'Data'");
-GNUPLOT (default) reset session
-GNUPLOT (default) print GPVAL_TERM
-GNUPLOT (default) -> qt
-GNUPLOT (default) print GPVAL_TERMOPTIONS
-GNUPLOT (default) -> 0 title "Gnuplot.jl: default" font "Sans,9"
-GNUPLOT (default) set key horizontal
-GNUPLOT (default) set grid
-GNUPLOT (default) set title  'My title'
-GNUPLOT (default) set xrange  [-7:7]
-GNUPLOT (default) set ylabel 'Y label'
-GNUPLOT (default) set xlabel 'X label'
-GNUPLOT (default) $data0 << EOD
-GNUPLOT (default)  -6.283185307179586 1.2258873407968363
-GNUPLOT (default)  -6.156252270670907 1.1443471266509504
-GNUPLOT (default)  -6.029319234162229 1.05377837392046
-GNUPLOT (default) ...
-GNUPLOT (default) EOD
-GNUPLOT (default) $data1 << EOD
-GNUPLOT (default)  -6.283185307179586 1.516291874781302 0.5
-GNUPLOT (default)  -6.156252270670907 1.5490769687987143 0.5
-GNUPLOT (default)  -6.029319234162229 0.30753349072971314 0.5
-GNUPLOT (default) ...
-GNUPLOT (default) EOD
-GNUPLOT (default) set key horizontal
-GNUPLOT (default) set grid
-GNUPLOT (default) set title  'My title'
-GNUPLOT (default) set xrange  [-7:7]
-GNUPLOT (default) set ylabel 'Y label'
-GNUPLOT (default) set xlabel 'X label'
-GNUPLOT (default) plot  \
-  $data0 w l t 'Real model' dt 2 lw 2 lc rgb 'red', \
-  $data1 w errorbars t 'Data'
-GNUPLOT (default) 
-```
-The **Gnuplot.jl** package (note the leading `GNUPLOT`...) tells us which commands are being sent to the gnuplot process and the name of the current gnuplot session (`default`).  The **Gnuplot.jl** package will also print the replies from gnuplot, e.g.:
-``` Julia
-julia> Gnuplot.exec("print GPVAL_TERM");
-GNUPLOT (default) print GPVAL_TERM
-GNUPLOT (default) -> qt
-```
-Note the different color in the reply (if your terminal is able to display colors).
-
-So far we have shown how to produce plots with a single command, however such task can also be performed using multiple statements.  The syntax is exactly the same, but we should use the `:-` symbol at the beginning of each statement (except the first) and at the end of each statement (except the last), e.g.:
-``` Julia
-# Reset the gnuplot session and give the dataset the name `MyDataSet1`
-name = "\$MyDataSet1"
-@gp x y+noise e name :-
-
-# Define a model function to be fitted
-@gp :- "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;"  :-
-
-# Fit the function to the :aa dataset
-@gp :- "fit f(x) $name u 1:2:3 via a, b, c;" :-
-
-# Prepare a multiplot showing the data, the model...
-@gp :- "set multiplot layout 2,1" :-
-@gp :- "plot $name w points tit 'Data'" ylab="Data and model" :-
-@gp :- "plot $name u 1:(f(\$1)) w lines tit 'Best fit'" :-
-
-# ... and the residuals (the `2` here refer to the second plot in the multiplot).
-@gp :- 2 xlab="X label" ylab="Residuals" :-
-@gp :- "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit"
-```
-
-The **Gnuplot.jl** package also provide support 
-As discussed above, **Gnuplot.jl** allows to trasparently exploit all gnuplot functionalities.  E.g., we can show a random image with:
-```Julia
-@gp randn(Float64, 30, 50) "w image"
-```
-or show an interactive 3D plots using the `@gsp` macro in place of `@gp`, e.g.:
-
-``` Julia
-@gsp randn(Float64, 30, 50)
-```
-
-Further documentation for the `@gp` and `@gsp` macros is available in the REPL by means of the `@doc` macro or by typing `?` in the REPL followed by the macro name.
-
-
-
-### Multiple gnuplot istances
-
-The **Gnuplot.jl** package can handle multiple gnuplot istances simultaneously, each idenitified by a unique session name (actually a Julia symbol).  To use a specific session simply name it in a `@gp` or `@gsp` call.  If the session is not yet created it will be automatically started:
-
-``` Julia
-# Plot using session GP1 
-x = 1:10
-@gp :GP1 x x.^2
-
-# Plot using session GP2
-@gp x x.^2 :GP2
-
-# Plot using default session
-@gp x x.^2
-```
-
-If needed, a specific session can be started by specifying a complete file path for the gnuplot executable, e.g.
-``` Julia
-gp = gnuplot(:CUSTOM1, "/path/to/gnuplot/executable")
-```
-
-Also, a session can be started as a *dry* one, i.e. a session with no underlying gnuplot process, by omitting the path to the Gnuplot executable:
-``` Julia
-gp = gnuplot(:DRY_SESSION)
-```
-The prupose is to create gnuplot scripts without running them, e.g:
-```Julia
-@gp :DRY_SESSION x x.^2 "w l" 
-save("test.gp")
-```
-The `test.gp` can then be loaded directly in gnuplot with:
-```
-gnuplot> load 'test.gp'
+println(Gnuplot.gpversion())
+test_terminal()
 ```
 
 
-### Direct execution of gnuplot commands
-Both the `@gp` and `@gsp` macros stores data and commands in the package state to allow using multiple statements for a single plot, or to save all data and commands on a script file.  However the user may directly execute command on the underlying gnuplot process using the `gpeval` function.  E.g., we can retrieve the values of the fitting parameters of the previous example:
-```Julia
-# Retrieve values fr a, b and c
-a = parse(Float64, exec("print a"))
-b = parse(Float64, exec("print b"))
-c = parse(Float64, exec("print c"))
-```
+## Quick start
+The following examples are supposed to be self-explaining.  See [documentation](https://gcalderone.github.io/Gnuplot.jl/v1.4.0/) for further informations.
 
-### Terminating a session
-A session and the associated gnuplot process can be terminated by a call to `quit`, specifying the session name, e.g.:
-``` Julia
-julia> quit(:GP1)
+### A simple parabola
+```julia
+x = 1.:20
+@gp x x.^2 "with lines title 'Parabola'"
+save(term="pngcairo size 480,360", output="examples/ex1.png")
+save("parabola.gp")  # => save a script file with both data and command to re-create the plot.
 ```
-A call to `quitall()` will terminate all active sessions.
+![ex1.png](examples/ex1.png)
+
+
+### A slightly more complex plot, with unicode on X tics
+```julia
+x = -2pi:0.1:2pi
+approx = fill(0., length(x));
+@gp tit="Polynomial approximation of sin(x)" key="opaque" linetypes(:Blues_4)
+@gp :- "set encoding utf8" raw"""set xtics ('-π' -pi, '-π/2' -pi/2, 0, 'π/2' pi/2, 'π' pi)"""
+@gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] "set grid front"
+@gp :- x sin.(x) approx .+=  x          "w filledcurve t 'n=0' lt 1"
+@gp :- x sin.(x) approx .+= -x.^3/6     "w filledcurve t 'n=1' lt 2"
+@gp :- x sin.(x) approx .+=  x.^5/120   "w filledcurve t 'n=2' lt 3"
+@gp :- x sin.(x) approx .+= -x.^7/5040  "w filledcurve t 'n=3' lt 4"
+@gp :- x sin.(x)                        "w l t 'sin(x)' lw 2 lc rgb 'black'"
+save(term="pngcairo size 640,480", output="examples/ex2.png")
+```
+![ex2.png](examples/ex2.png)
+
+
+### Multiplot: a 2D histogram contour plot and a 3D surface plot
+```julia
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y, bs1=0.25, nbins2=20)
+@gp "set multiplot layout 1,2"
+@gp :- 1 key="outside top center box horizontal" "set size ratio -1" h
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
+for i in 1:length(clines)
+    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i lc rgb 'gray'" :-
+end
+@gsp :- 2 h.bins1 h.bins2 h.counts "w pm3d notit"
+save(term="pngcairo size 660,350 fontscale 0.8", output="examples/ex3.png")
+```
+![ex3.png](examples/ex3.png)
+
+
+## Further examples
+The main gallery of examples is maintained in a separate repository:
+https://lazarusa.github.io/gnuplot-examples/
+
+Since **Gnuplot.jl** is just a transparent interface (not a wrapper) it exposes all capabilities of the underlying gnuplot process, hence pure-gnuplot examples also applies to **Gnuplot.jl**.  Further examples are available here:
+- http://gnuplot.sourceforge.net/demo_5.2/
+- http://www.gnuplotting.org/

REQUIRE

@@ -1,5 +0,0 @@
-julia 1.0
-StructC14N
-ColorTypes
-StatsBase
-ReusePatterns

docs/make.jl

@@ -0,0 +1,19 @@
+using Documenter, Gnuplot
+empty!(Gnuplot.options.mime)
+
+makedocs(sitename="Gnuplot.jl",
+         authors = "Giorgio Calderone",
+         #format = Documenter.HTML(prettyurls = false),  # uncomment for local use, comment for deployment
+         modules=[Gnuplot],
+         pages = [
+             "Home" => "index.md",
+             "Installation" => "install.md",
+             "Basic usage" => "basic.md",
+             "Advanced usage" => "advanced.md",
+             "Package options" => "options.md",
+             "Style guide" => "style.md",
+             "Gnuplot terminals" => "terminals.md",
+             "Plot recipes" => "recipes.md",
+             "Examples" => "examples.md",
+             "API" => "api.md"
+         ])

docs/src/advanced.md

@@ -0,0 +1,374 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+# Advanced usage
+
+Here we will show a few advanced techniques for data visualization using **Gnuplot.jl**.
+
+## Named datasets
+
+A dataset may have an associated name whose purpose is to use it multiple times for plotting, while sending it only once to gnuplot. A dataset name must begin with a `$`.
+
+A named dataset is defined as a `Pair{String, Tuple}`, e.g.:
+```julia
+"\$name" => (1:10,)
+```
+and can be used as an argument to both `@gp` and `gsp`, e.g.:
+```@example abc
+x = range(-2pi, stop=2pi, length=100);
+y = sin.(x)
+name = "\$MyDataSet1"
+@gp name=>(x, y) "plot $name w l lc rgb 'black'" "pl $name u 1:(1.5*\$2) w l lc rgb 'red'"
+saveas("advanced010") # hide
+```
+![](assets/advanced010.png)
+
+Both curves use the same input data, but the red curve has the second column (`\$2`, corresponding to the *y* value) multiplied by a factor 1.5.
+
+A named dataset comes in hand also when using gnuplot to fit experimental data to a model, e.g.:
+```@example abc
+# Generate data and some noise to simulate measurements
+x = range(-2pi, stop=2pi, length=20);
+y = 1.5 * sin.(0.3 .+ 0.7x);
+err = 0.1 * maximum(abs.(y)) .* fill(1, size(x));
+y += err .* randn(length(x));
+name = "\$MyDataSet1"
+
+@gp    "f(x) = a * sin(b + c*x)"     :- # define an analytical model
+@gp :- "a=1" "b=1" "c=1"             :- # set parameter initial values
+@gp :- name=>(x, y, err)             :- # define a named dataset
+@gp :- "fit f(x) $name via a, b, c;"    # fit the data
+```
+
+The parameter best fit values can be retrieved as follows:
+```@example abc
+vars = gpvars();
+@info("Best fit values:",
+  a = vars.a,
+  b = vars.b,
+  c = vars.c)
+```
+
+## Multiplot
+
+**Gnuplot.jl** can draw multiple plots in the same figure by exploiting the `multiplot` command.  Each plot is identified by a positive integer number, which can be used as argument to `@gp` to redirect commands to the appropriate plot.
+
+Recycling data from the previous example we can plot both data and best fit model (in plot `1`) and residuals (in plot `2`):
+```@example abc
+@gp    "f(x) = a * sin(b + c*x)"
+@gp :- "a=$(vars.a)" "b=$(vars.b)" "c=$(vars.c)"
+@gp :- name=>(x, y, err)
+@gp :- "set multiplot layout 2,1"
+@gp :- 1 "p $name w errorbars t 'Data'"
+@gp :-   "p $name u 1:(f(\$1)) w l t 'Best fit model'"
+@gp :- 2 "p $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars t 'Resid. [{/Symbol s}]'"
+@gp :-   [extrema(x)...] [0,0] "w l notit dt 2 lc rgb 'black'" # reference line
+saveas("advanced011") # hide
+```
+![](assets/advanced011.png)
+
+Note that the order of the plots is not relevant, i.e. we would get the same results with:
+```julia
+@gp    "f(x) = a * sin(b + c*x)"
+@gp :- "a=$(vars.a)" "b=$(vars.b)" "c=$(vars.c)"
+@gp :- name=>(x, y, err)
+@gp :- "set multiplot layout 2,1"
+@gp :- 2 "p $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars t 'Resid. [{/Symbol s}]'"
+@gp :-   [extrema(x)...] [0,0] "w l notit dt 2 lc rgb 'black'" # reference line
+@gp :- 1 "p $name w errorbars t 'Data'"
+@gp :-   "p $name u 1:(f(\$1)) w l t 'Best fit model'"
+```
+
+## Customized layout
+
+It is also possible to customize the plot layout using the margin keywords (see [Histograms](@ref) for further info on how to generate andi display histograms):
+```@example abc
+# Generate random numbers
+x = randn(1000);
+y = randn(1000);
+
+# Overall plot margins (normalized in the range 0:1)
+margins = (l=0.08, r=0.98, b=0.13, t=0.98)
+
+# Right and top margins of main plot
+right, top = 0.8, 0.75
+
+# Gap between main plot and histograms
+gap  = 0.015
+
+# Main plot
+@gp "set multiplot"
+@gp :- 1 ma=margins rma=right tma=top :-
+@gp :-   x y "w p notit" xlab="X" ylab="Y"
+xr = gpranges().x  # save current X range
+yr = gpranges().y  # save current Y range
+
+# Histogram on X
+h = hist(x, nbins=10)
+@gp :- 2 ma=margins bma=top+gap rma=right :-
+@gp :-   "set xtics format ''" "set ytics format ''"  xlab="" ylab="" :-
+bs = fill(h.binsize, length(h.bins));
+@gp :-   xr=xr h.bins h.counts./2 bs./2 h.counts./2 "w boxxy notit fs solid 0.4" :-
+
+# Histogram on Y
+h = hist(y, nbins=10)
+@gp :- 3 ma=margins lma=right+gap tma=top :-
+@gp :-     "unset xrange" :-
+bs = fill(h.binsize, length(h.bins));
+@gp :-   yr=yr h.counts./2 h.bins h.counts./2 bs./2 "w boxxy notit fs solid 0.4" :-
+@gp
+saveas("advanced011b") # hide
+```
+![](assets/advanced011b.png)
+
+
+
+
+
+### Mixing 2D and 3D plots
+A multiplot can also mix 2D and 3D plots:
+
+```@example abc
+x = y = -10:0.33:10
+@gp "set multiplot layout 1,2"
+
+# 2D
+@gp :- 1 x sin.(x) ./ x "w l notit"
+
+# 3D
+sinc2d(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)
+fxy = [sinc2d(x,y) for x in x, y in y]
+@gsp :- 2 x y fxy "w pm3d notit"
+saveas("advanced012") # hide
+```
+![](assets/advanced012.png)
+
+
+## Multiple sessions
+
+**Gnuplot.jl** can handle multiple sessions, i.e. multiple gnuplot processes running simultaneously.  Each session is identified by an ID (`sid::Symbol`, in the documentation).
+
+In order to redirect commands to a specific session simply insert a symbol into your `@gp` or `@gsp` call, e.g.:
+```@example abc
+@gp :GP1 "plot sin(x)"    # opens first window
+@gp :GP2 "plot sin(x)"    # opens secondo window
+@gp :- :GP1 "plot cos(x)" # add a plot on first window
+```
+The session ID can appear in every position in the argument list, but only one ID can be present in each call.  If the session ID is not specified the `:default` session is used.
+
+The names of all current sessions can be retrieved with [`session_names()`](@ref):
+```@repl abc
+println(session_names())
+```
+
+To quit a specific session use [`Gnuplot.quit()`](@ref):
+```@repl abc
+Gnuplot.quit(:GP1)
+```
+The output value is the exit status of the underlying gnuplot process.
+
+You may also quit all active sessions at once with [`Gnuplot.quitall()`](@ref):
+```@repl abc
+Gnuplot.quitall()
+```
+
+## Histograms
+**Gnuplot.jl** provides facilities to compute and display histograms, e.g.:
+```@example abc
+x = randn(1000);
+@gp hist(x)
+saveas("advanced013a") # hide
+```
+![](assets/advanced013a.png)
+
+The [`hist()`](@ref) function also accept keywords to set the range to consider (`range=` keyword) and either the bin size (`bs=`) or the total number of bins (`nbins=`) in the histogram.  A finer control on the output is achieved by exploiting the fields of the returned ([`Gnuplot.Histogram1D`](@ref)) structure, e.g.:
+```@example abc
+x = randn(1000);
+h = hist(x, range=3 .* [-1,1], bs=0.5)
+@gp h.bins h.counts "w histep t 'Data' lc rgb 'red'"
+saveas("advanced013b") # hide
+```
+![](assets/advanced013b.png)
+
+The [`hist()`](@ref) function compute also 2D histograms by passing two vectors (with the same lengths), e.g.:
+```@example abc
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y)
+@gp h
+saveas("advanced014a") # hide
+```
+![](assets/advanced014a.png)
+
+Again, a finer control can be achieved by specifying ranges, bin size or number of bins (along both dimensions) and by explicitly using the content of the returned [`Gnuplot.Histogram2D`](@ref) structure:
+```@example abc
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y, bs1=0.25, nbins2=20, range1=[-3,3], range2=[-3,3])
+@gp "set size ratio -1" h.bins1 h.bins2 h.counts "w image notit"
+saveas("advanced014b") # hide
+```
+![](assets/advanced014b.png)
+
+
+Alternatively, 2D histograms may be displayed using the `boxxyerror` plot style which allows more flexibility in, e.g., handling transparencies and drawing the histogram grid.  In this case the data can be prepared using the [`boxxy()`](@ref) function, as follows:
+```@example abc
+@gp "set size ratio -1" "set style fill solid 0.5 border lc rgb 'gray'" :-
+@gp :- boxxy(h) "w boxxy notit lc pal"
+saveas("advanced014c") # hide
+```
+![](assets/advanced014c.png)
+
+
+
+## Contour lines
+Although gnuplot already handles contours by itself (with the `set contour` command), **Gnuplot.jl** provides a way to calculate contour lines paths before displaying them, using the [`contourlines()`](@ref) function.  We may preview such lines with:
+```@example abc
+x = randn(10_000)
+y = randn(10_000)
+h = hist(x, y)
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
+@gp clines
+saveas("advanced014d") # hide
+```
+![](assets/advanced014d.png)
+
+By exploiting the fields of the [`Gnuplot.IsoContourLines`](@ref) structure we may also customize line widths, colors and dashed pattern according to their z level, and plot them on top of the 2D histogram:
+
+```@example abc
+@gp "set size ratio -1" "set style fill solid 0.5 border lc rgb 'gray'" :-
+@gp :- boxxy(h) "w boxxy notit lc pal"
+for i in 1:length(clines)
+    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i dt $i lc pal" :-
+end
+@gp :- key="outside top center box horizontal"
+saveas("advanced014e") # hide
+```
+![](assets/advanced014e.png)
+
+
+The [`contourlines()`](@ref) function also allows to calculate the contour lines encompassing a given fraction of the total counts of a 2D histogram.  E.g. to plot the contours corresponding to 1, 2, and 3 $\sigma$ of a 2D Gaussian distribution:
+```@example abc
+x = randn(10^5);
+y = randn(10^5);
+h = hist(x, y, nbins1=20, nbins2=20);
+
+# Calculate probability within 0 < r < σ
+p(σ) = round(1 - exp(-(σ^2) / 2), sigdigits=3)
+
+# Draw contour lines at 1, 2 and 3 σ
+clines = contourlines(h, p.(1:3));
+@gp palette(:beach, smooth=true, rev=true) "set grid front" "set size ratio -1" h clines
+saveas("advanced014f") # hide
+```
+![](assets/advanced014f.png)
+
+
+## Interpolation of 2D scattered data
+The `dgrid3d()` function allows to interpolate 2D scattered data onto a 2D regular grid, e.g.:
+```@example abc
+x = (rand(200) .- 0.5) .* 3;
+y = (rand(200) .- 0.5) .* 3;
+z = exp.(-(x.^2 .+ y.^2));
+
+# Interpolate on a 20x30 regular grid with splines
+gx, gy, gz = dgrid3d(x, y, z, "20,30 splines")
+
+@gsp "set size ratio -1" "set xyplane at 0" xlab="X" ylab="Y" :-
+@gsp :-  x  y  z "w p t 'Scattered data' lc pal"
+@gsp :- gx gy gz "w l t 'Interpolation on a grid' lc pal"
+saveas("advanced015a") # hide
+```
+![](assets/advanced015a.png)
+
+
+!!! warn
+    The `splines` algorithm may be very slow on large datasets.  An alternative option is to use a smoothing kernel, such as `gauss`.
+
+
+The interpolated data in scarcely sampled regions are poorly constrained, i.e. they are actually *extrapolated values*.  By using the `extra=false` keyword all extrapolated values are set to `NaN`:
+
+```@example abc
+x = randn(2000) .* 0.5;
+y = randn(2000) .* 0.5;
+rsq = x.^2 + y.^2;
+z = exp.(-rsq) .* sin.(y) .* cos.(2 * rsq);
+
+@gsp "set size ratio -1" palette(:balance, smooth=true) "set view map" "set pm3d" :-
+@gsp :- "set multiplot layout 1,3" xr=[-2,2] yr=[-2,2] :-
+@gsp :- 1 tit="Scattered data"  x  y  z "w p notit lc pal"
+
+# Show extrapolated values
+gx, gy, gz = dgrid3d(x, y, z, "40,40 gauss 0.1,0.1")
+@gsp :- 2 tit="Interpolation on a grid\\n(extrapolated values are shown)"  gx gy gz "w l notit lc pal"
+
+# Hide exrapolated values
+gx, gy, gz = dgrid3d(x, y, z, "40,40 gauss 0.1,0.1", extra=false)
+@gsp :- 3 tit="Interpolation on a grid\\n(extrapolated values are hidden)" gx gy gz "w l notit lc pal"
+save(term="pngcairo size 1000,400 fontscale 1.0", output="assets/advanced015b.png")  # hide
+```
+![](assets/advanced015b.png)
+
+
+
+## Animations
+
+The [Multiplot](@ref) capabilities can also be used to stack plots one above the other in order to create an animation, as in the following example:
+```@example abc
+x = y = -10:0.33:10
+fz(x,y) = sin.(sqrt.(x.^2 + y.^2))./sqrt.(x.^2+y.^2)
+fxy = [fz(x,y) for x in x, y in y]
+@gsp "set xyplane at 0" "unset colorbox" cbr=[-1,1] zr=[-1,1]
+frame = 0
+for direction in [-1,1]
+    for factor in -1:0.1:1
+        global frame += 1
+        @gsp :- frame x y direction * factor .* fxy "w pm3d notit" :-
+    end
+end
+@gsp
+```
+Here the `frame` variable is used as multiplot index. The animation can be saved in a GIF file with:
+```@example abc
+save(term="gif animate size 480,360 delay 5", output="assets/animation.gif")
+```
+![](assets/animation.gif)
+
+
+## Direct command execution
+When gnuplot commands are passed to `@gp` or `@gsp` they are stored in a session for future use, or to be saved in [Gnuplot scripts](@ref).  If you simply wish to execute a command without storing it in the session, and possibly retrieve a value, use [`gpexec`](@ref).  E.g., to retrieve the value of a gnuplot variable:
+```@repl abc
+gpexec("print GPVAL_TERM")
+```
+
+You may also provide a session ID as first argument (see [Multiple sessions](@ref)) to redirect the command to a specific session.
+
+Alternatively you may start the [The gnuplot REPL](@ref) to type commands directly from the Julia prompt.
+
+
+## The gnuplot REPL
+The **Gnuplot.jl** package comes with a built-in REPL mode to directly send commands to the underlying gnuplot process.  Since the REPL is a global resource, the gnuplot mode is not enabled by default.  You can start it with:
+```julia
+Gnuplot.repl_init(start_key='>')
+```
+The customizable `start_key` character is the key which triggers activation of the REPL mode. To quit the gnuplot REPL mode hit the `backspace` key.
+
+
+## Dry sessions
+A "*dry session*" is a session with no underlying gnuplot process.  To enable dry sessions type:
+```julia
+Gnuplot.options.dry = true;
+```
+before starting a session (see also [Options](@ref)).  Note that the `dry` option is a global one, i.e. it affects all sessions started after setting the option.
+
+Clearly, no plot can be generated in dry sessions. Still, they are useful to run **Gnuplot.jl** code without raising errors (no attempt will be made to communicate with the underlying process).  Moreover, [Gnuplot scripts](@ref) can also be generated in a dry session, without the additional overhead of sending data to the gnuplot process.
+
+If a gnuplot process can not be started the package will print a warning, and automatically enable dry sessions.

docs/src/api.md

@@ -0,0 +1,57 @@
+# API
+
+## Index
+```@index
+```
+
+## Exported symbols
+The list of **Gnuplot.jl** exported symbols is as follows:
+
+```@docs
+@gp
+@gsp
+boxxy
+contourlines
+dataset_names
+dgrid3d
+gpexec
+gpmargins
+gpranges
+gpvars
+hist
+linetypes
+palette
+palette_levels
+palette_names
+recipe
+save
+session_names
+stats
+terminals
+terminal
+test_terminal
+```
+
+
+## Non-exported symbols
+The following functions are not exported by the **Gnuplot.jl** package since they are typically not used in every day work, or aimed to debugging purposes.  Still, they can be useful in some case, hence they are documented here.
+
+In order to call these functions you should add the `Gnuplot.` prefix to the function name.
+
+```@docs
+Gnuplot.Dataset
+Gnuplot.DatasetEmpty
+Gnuplot.DatasetText
+Gnuplot.DatasetBin
+Gnuplot.Histogram1D
+Gnuplot.Histogram2D
+Gnuplot.IsoContourLines
+Gnuplot.Options
+Gnuplot.Path2d
+Gnuplot.PlotElement
+Gnuplot.gpversion
+Gnuplot.quit
+Gnuplot.quitall
+Gnuplot.repl_init
+Gnuplot.version
+```

docs/src/basic.md

@@ -0,0 +1,339 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+Gnuplot.splash("assets/logo.png")
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+# Basic usage
+
+The main purpose of the **Gnuplot.jl** package is to send data and commands to the underlying gnuplot process, in order to generate plots.  Unlike other packages, however, the actual commands to plot, or the plot attributes, are not specified through function calls.  This is what makes **Gnuplot.jl** *easy to learn and use*: there are no functions or keywords names to memorize[^1].
+
+The most important symbols exported by the package are the [`@gp`](@ref) (for 2D plots) and [`@gsp`](@ref) (for 3D plots) macros.  The simplemost example is as follows:
+```@example abc
+using Gnuplot
+@gp 1:20
+saveas("basic000") # hide
+```
+![](assets/basic000.png)
+
+The plots are displayed either in an interactive window (if running in the Julia REPL), as an inline image (if running in Jupyter) or in the plot pane (if running in Juno).  See [Display options](@ref) for further informations.
+
+
+Both the [`@gp`](@ref) and [`@gsp`](@ref) macros accept any number of arguments, whose meaning is interpreted as follows:
+
+- one, or a group of consecutive, array(s) build up a dataset.  The different arrays are accessible as columns 1, 2, etc. from the gnuplot process.  The number of required input arrays depends on the chosen plot style (see gnuplot documentation);
+
+- a string occurring before a dataset is interpreted as a gnuplot command (e.g. `set grid`);
+
+- a string occurring immediately after a dataset is interpreted as a *plot element* for the dataset, by which you can specify `using` clause, `with` clause, line styles, etc.;
+
+- the special symbol `:-`, whose meaning is to avoid starting a new plot (if given as first argument), or to avoid immediately running all commands to create the final plot (if given as last argument).  Its purpose is to allow splitting one long statement into multiple (shorter) ones.
+
+The above list shows all the fundamental concepts to follow the examples presented below.  The [`@gp`](@ref) and [`@gsp`](@ref) macros also accepts further arguments, but their use will be discussed in [Advanced usage](@ref).
+
+[^1]: a previous knowledge of [gnuplot](http://gnuplot.sourceforge.net/documentation.html) usage is, nevertheless, required.
+
+## [2D plots](@id plots2d)
+
+Here we will show a few examples to generate 2D plots.  The examples are intentionally very simple to highlight the behavior of **Gnuplot.jl**.  See [Examples](@ref) for more complex ones.
+
+Remember to run:
+```julia
+using Gnuplot
+```
+before running the examples.
+
+
+
+
+### Simple examples involving just gnuplot commands:
+
+---
+#### Plot a sinusoid:
+```@example abc
+@gp "plot sin(x)"
+saveas("basic001") # hide
+```
+![](assets/basic001.png)
+
+---
+#### Plot two curves:
+```@example abc
+@gp "set key left" "plot sin(x)" "pl cos(x)"
+saveas("basic002") # hide
+```
+![](assets/basic002.png)
+
+!!! note
+    Note that all gnuplot commands can be abbreviated as long as the resulting string is not ambiguous.  In the example above we used `pl` in place of `plot`.
+
+---
+#### Split a `@gp` call in three statements:
+```@example abc
+@gp    "set grid"  :-
+@gp :- "p sin(x)"  :-
+@gp :- "plo cos(x)"
+saveas("basic003") # hide
+```
+![](assets/basic003.png)
+!!! note
+    The trailing `:-` symbol means the plot will not be updated until the last statement.
+
+
+### Send data from Julia to gnuplot:
+
+#### Plot a parabola
+```@example abc
+@gp (1:20).^2
+saveas("basic004") # hide
+```
+![](assets/basic004.png)
+
+
+---
+#### Plot a parabola with scaled x axis, lines and legend
+```@example abc
+x = 1:20
+@gp "set key left"   x ./ 20   x.^2   "with lines tit 'Parabola'"
+saveas("basic005") # hide
+```
+![](assets/basic005.png)
+
+---
+#### Multiple datasets, logarithmic axis, labels and colors, etc.
+```@example abc
+x = 1:0.1:10
+@gp    "set grid" "set key left" "set logscale y"
+@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:*]"
+@gp :- x x.^0.5 "w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'"
+@gp :- x x      "w l tit 'Pow 1'   dt 1 lw 3 lc rgb 'blue'"
+@gp :- x x.^2   "w l tit 'Pow 2'   dt 3 lw 2 lc rgb 'purple'"
+saveas("basic006") # hide
+```
+![](assets/basic006.png)
+
+!!! note
+    The above example lacks the trailing `:-` symbol.  This means the plot will be updated at each command, adding one curve at a time.
+
+---
+## Keywords for common commands
+In order to avoid typing long, and very frequently used gnuplot commands, **Gnuplot.jl** provides a few keywords which can be used in both `@gp` and `@sgp` calls:
+ - `xrange=[low, high]` => `"set xrange [low:high]`;
+ - `yrange=[low, high]` => `"set yrange [low:high]`;
+ - `zrange=[low, high]` => `"set zrange [low:high]`;
+ - `cbrange=[low, high]`=> `"set cbrange[low:high]`;
+ - `key="..."`  => `"set key ..."`;
+ - `title="..."`  => `"set title \"...\""`;
+ - `xlabel="..."` => `"set xlabel \"...\""`;
+ - `ylabel="..."` => `"set ylabel \"...\""`;
+ - `zlabel="..."` => `"set zlabel \"...\""`;
+ - `cblabel="..."` => `"set cblabel \"...\""`;
+ - `xlog=true`   => `set logscale x`;
+ - `ylog=true`   => `set logscale y`;
+ - `zlog=true`   => `set logscale z`;
+ - `margins=...` => `set margins ...`;
+ - `lmargin=...` => `set lmargin ...`;
+ - `rmargin=...` => `set rmargin ...`;
+ - `bmargin=...` => `set bmargin ...`;
+ - `tmargin=...` => `set tmargin ...`;
+
+All such keywords can be abbreviated to unambiguous names.
+
+By using the above keywords the first lines of the previous example:
+```julia
+@gp    "set grid" "set key left" "set logscale y"
+@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:*]"
+```
+can be replaced with a shorter version:
+```julia
+@gp    "set grid" k="left" ylog=true
+@gp :- tit="Plot title" xlab="X label" xr=[0,NaN]
+```
+where `NaN` in the `xrange` keyword means using axis autoscaling.
+
+
+## Plot matrix as images
+
+**Gnuplot.jl** can display a 2D matrix as an image:
+```@example abc
+img = randn(Float64, 8, 5)
+img[2,:] .= -5
+@gp img "w image notit"
+saveas("basic007a") # hide
+```
+![](assets/basic007a.png)
+
+Note that the first index in the `img` matrix corresponds to the rows in the displayed image.
+
+A simple way to remember the convention is to compare how a matrix is displayed in the REPL:
+```@example abc
+img = reshape(1:15, 5, 3)
+```
+and its image representation, which is essentially upside down (since the Y coordinates increase upwards):
+```@example abc
+@gp img "w image notit"
+saveas("basic007b") # hide
+```
+![](assets/basic007b.png)
+
+Also note that the `img[1,1]` pixel is shown at coordinates x=0, y=0.  See [Image recipes](@ref) for further info.
+
+
+## [3D plots](@id plots3d)
+3D plots follow the same rules as 2D ones, just replace the `@gp` macro with `@gsp` and add the required columns (according to the plotting style).
+
+E.g., to plot a spiral increasing in size along the `X` direction:
+```@example abc
+x = 0:0.1:10pi
+@gsp cbr=[-1,1].*30  x  x.*sin.(x)  x.*cos.(x)  x./20  "w p pt 7 ps var lc pal"
+saveas("basic008") # hide
+```
+![](assets/basic008.png)
+
+Note that the fourth array in the dataset, `x./20`, is used as by gnuplot as point size (`ps var`).  Also note that all the keywords discussed above can also be used in 3D plots.
+
+
+## Palettes and line types
+The **Gnuplot.jl** package comes with all the [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes readily available.
+
+A gnuplot-compliant palette can be retrieved with [`palette()`](@ref), and used as any other command.  The previous example may use an alternative palette with:
+```@example abc
+x = 0:0.1:10pi
+@gsp palette(:viridis) cbr=[-1,1].*30 :-
+@gsp :-  x  x.*sin.(x)  x.*cos.(x)  x./20  "w p pt 7 ps var lc pal"
+saveas("basic008a") # hide
+```
+![](assets/basic008a.png)
+
+The palette levels may be easily stretched by using the [`palette_levels()`](@ref) and modifying the numeric levels, e.g.:
+```@example abc
+x = 0:0.1:10pi
+v, l, n = palette_levels(:viridis)
+@gsp palette(v.^0.25, l, n) cbr=[-1,1].*30 :-
+@gsp :-  x  x.*sin.(x)  x.*cos.(x)  x./20  "w p pt 7 ps var lc pal"
+saveas("basic008b") # hide
+```
+![](assets/basic008b.png)
+
+The list of all available palette can be retrieved with [`palette_names()`](@ref):
+```@repl abc
+palette_names()
+```
+
+
+The [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes can also be used to generate line type colors, and optionally the line width, point size and dashed pattern, by means of the [`linetypes()`](@ref) function, e.g.
+```@example abc
+@gp key="left" linetypes(:Set1_5, lw=2)
+for i in 1:10
+    @gp :- i .* (0:10) "w lp t '$i'"
+end
+saveas("basic009a") # hide
+```
+![](assets/basic009a.png)
+
+
+```@example abc
+@gp key="left" linetypes(:Set1_5, dashed=true, ps=2)
+for i in 1:10
+    @gp :- i .* (0:10) "w lp t '$i'"
+end
+saveas("basic009b") # hide
+```
+![](assets/basic009b.png)
+
+The first plot features the `:Set1_5` palette, with solid lines whose width is 2 times the default.  The second plot shows the same palette but default line widths are 1, default point size is 2 (for the first N line types, where N is the number of discrete colors in the palette), and the dashed pattern is automatically changed.
+
+As discussed in [Options](@ref), you may set a default line types for all plots with:
+```julia
+push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+```
+All plot in this documentation were generated with these settings.
+
+
+## Exporting plots to files
+
+**Gnuplot.jl** can export all plots (as well as multiplots, see [Multiplot](@ref)) to an external file using one of the many available gnuplot terminals.  To check which terminals are available in your platform type:
+```@repl abc
+terminals()
+```
+(see also [`terminal()`](@ref) to check your current terminal).
+
+Once you choose the proper terminal (i.e. format of the exported file), use the [`save()`](@ref) function to export.  As an example, all the plots in this page have been saved with:
+```julia
+save(term="pngcairo size 550,350 fontscale 0.8", output="assets/output.png")
+```
+Note that you can pass both the terminal name and its options via the `term=` keyword.  See [Gnuplot terminals](@ref) for further info on the terminals.
+
+
+## Gnuplot scripts
+Besides exporting plots in image files, **Gnuplot.jl** can also save a *script*, i.e. a file containing the minimum set of data and commands required to re-create a figure using just gnuplot.
+
+The script allows a complete decoupling of plot data and aethetics, from the Julia code used to generate them.  With scripts you can:
+- modify all aesthetic details of a plot without re-running the (possibly complex and time-consuming) code used to generate it;
+- share both data and plots with colleagues without the need to share the Julia code.
+
+To generate a script for one of the examples above use:
+```julia
+save("script.gp")
+```
+after the plot has been displayed.  Note that when images or large datasets are involved, `save()` may store the data in binary files under a directory named `<script name>_data`. In order to work properly both the script and the associated directory must be available in the same directory.
+
+
+E.g., the following code:
+```@example abc
+x = 1:10
+@gp x x.^2 "w l"
+save("script1.gp")
+```
+will produce the following file, named `script1.gp`:
+```
+reset session
+$data1 << EOD
+ 1 1
+ 2 4
+ 3 9
+ 4 16
+ 5 25
+ 6 36
+ 7 49
+ 8 64
+ 9 81
+ 10 100
+EOD
+plot  \
+  $data1 w l
+set output
+```
+
+While the following:
+```@example abc
+img = randn(100, 300);
+@gp "set size ratio -1" "set autoscale fix" img "flipy with image notit"
+save("script2.gp")
+```
+will produce:
+```
+reset session
+set size ratio -1
+set autoscale fix
+plot  \
+   './script2_data/jl_OQrt9A' binary array=(300, 100) flipy with image notit
+set output
+```
+
+The above scripts can be loaded into a pure gnuplot session (Julia is no longer needed) as follows:
+```
+gunplot> load 'script1.gp'
+gunplot> load 'script2.gp'
+```
+to generate a plot identical to the original one.
+
+
+The purpose of gnuplot scripts is to allow sharing all data, alongside a plot, in order to foster collaboration among scientists and replicability of results.  Moreover, a script can be used at any time to change the details of a plot, without the need to re-run the Julia code used to generate it the first time.
+
+Finally, the scripts are the only possible output when [Dry sessions](@ref) are used (i.e. when gnuplot is not available in the user platform.

docs/src/examples.md

@@ -0,0 +1,12 @@
+# Examples
+
+The official gallery of high quality examples is maintained in a separate repository:
+
+[https://lazarusa.github.io/gnuplot-examples/](https://lazarusa.github.io/gnuplot-examples/)
+
+The examples in this documentation are intentionally very simple, in order to focus on the package functionalities.  The only relatively complex, publication-quality plot, is discussed in [The `cairolatex` terminal](@ref) section.
+
+Keep in mind that **Gnuplot.jl** is just an interface to gnuplot, so everything you can do with the latter is achievable from Julia.
+Further gnuplot examples can be found here:
+- [http://gnuplot.sourceforge.net/demo_5.2/](http://gnuplot.sourceforge.net/demo_5.2/)
+- [http://www.gnuplotting.org/](http://www.gnuplotting.org/)

docs/src/index.md

@@ -0,0 +1,80 @@
+# Gnuplot.jl
+## A Julia interface to gnuplot.
+[![Stars](https://img.shields.io/github/stars/gcalderone/Gnuplot.jl?style=social)](https://github.com/gcalderone/Gnuplot.jl)
+
+
+The **Gnuplot.jl** package allows easy and fast use of [gnuplot](http://gnuplot.info/) as a data visualization tool in Julia.  Have a look at [Basic usage](@ref) and [Examples](@ref) for a quick overview.  The package main features are:
+
+- fast time-to-first-plot;
+
+- extremely concise yet meaningful syntax, makes it ideal for interactive data exploration;
+
+- no need to learn new API functions or keywords: only two macros (`@gp` for 2D plots, `@gsp` for 3D plots) and a basic knowledge of gnuplot are enough to generate most plots;
+
+- transparent interface between Julia and gnuplot to exploit all functionalities of the latter, both present and future ones;
+
+- availability of all the palettes from [ColorSchemes](https://github.com/JuliaGraphics/ColorSchemes.jl);
+
+- support for multiple plots in one window, multiple plotting windows, as well as ASCII and Sixel plots (to plot directly in a terminal);
+
+- support for histograms (both 1D and 2D);
+
+- enhanced support for contour plots;
+
+- 2D interpolation of scattered data on a regular grid;
+
+- export to a huge number of formats such as `pdf`, `png`, `gif`, ``\LaTeX``, `svg`, etc. (actually all those supported by gnuplot);
+
+- compatibility with Jupyter and Juno;
+
+- save sessions into gnuplot scripts, to enable easy plot customization and reproducibility.
+
+If you're unfamiliar with gnuplot have a look at:
+
+- [Main gnuplot site](http://gnuplot.info/)
+- [gnuplot FAQ](http://gnuplot.info/faq/index.html)
+
+
+## Yet another plotting package?
+
+A powerful plotting framework is among the most important tool in the toolbox of any modern scientist and engineer.  As such, it is hard to find a single package to fit all needs, and many solutions are indeed available in the Julia [ecosystem](https://github.com/JuliaPlots).
+
+**Gnuplot.jl** package fills the niche of users who needs:
+
+1. publication-quality plots, by exploiting the capabilities of a widely used tool such as gnuplot, and its many output formats available;
+1. a well-documented framework, by taking advantage of all the gnuplot documentation, tutorials and examples available on the web;
+1. a fast response, by relying on an external program (rather than on a large Julia code base);
+1. an interactive data exploration framework, by exposing a carefully designed, extremely concise and easy to remember syntax (at least for users with minimal gnuplot knowledge);
+1. a procedure to decouple plot data and aesthetics from the Julia code used to generate them.
+
+Unlike other packages **Gnuplot.jl** is not a pure Julia solution as it depends on an external package to actually generate plots.  However, if gnuplot is not available on a given platform, the package could still be used in "*dry*" mode, and no error for a missing dependency will be raised (see [Dry sessions](@ref)).
+
+The **Gnuplot.jl** package development follows a minimalistic approach: it is essentially a thin layer to send data and commands to gnuplot.  This way all underlying capabilities, both present and future ones, are automatically exposed to the Julia user, with no need to implement dedicated wrappers.
+
+The functionalities 1, 2 and 3 listed above are similar to those provided by the [Gaston](https://github.com/mbaz/Gaston.jl) package.  **Gnuplot.jl** also provides features 4 and 5, as well as the minimalistic approach.
+
+
+## Does Gnuplot.jl suit my needs?
+
+Any modern plotting framework is able to produce a simple scatter plot, with custom symbols, line styles, colors and axis labels.  Indeed, this is exactly the example that is reported in every package documentation (also here: see [2D plots](@ref plots2d)). Still, producing complex and publication-quality plots is not an easy task.  As a consequence is also hard to tell whether a package can cope with the most difficult cases, unless you actually try it out.  A reasonable choice, then, is to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
+
+By allowing transparent access to the underlying gnuplot process, the **Gnuplot.jl** package immediately exposes all capabilities of the backend and allows to take advantage of the many resources available online.  The minimalistic approach allows to value the widely spread knowledge of gnuplot syntax, and ensures a shallow learning curve for the package.  Finally, its extremely concise syntax makes it ideal for interactive data exploration.
+
+As a final remark, note that the **Gnuplot.jl** features directly maps onto the different stages of production of a plot:
+- syntax conciseness, interactivity, [Plot recipes](@ref) => preliminary data exploration;
+- access to all gnuplot capabilities, allowing to tweak even the smallest detail of a plot => plot preparation;
+- [Gnuplot scripts](@ref) => post-production.
+
+Before continuing, have a look at the [Examples](@ref) page!
+
+
+## Notation
+In this documentation:
+- "**Gnuplot.jl**" refers to the Julia package;
+- "gnuplot" refers to the [gnuplot](http://gnuplot.info/) application.
+
+
+## Table of Contents
+```@contents
+Pages = ["index.md", "install.md", "basic.md", "advanced.md", "options.md", "style.md", "terminals.md", "recipes.md", "examples.md", "api.md"]
+```

docs/src/install.md

@@ -0,0 +1,48 @@
+# Installation
+
+## Prerequisite
+In order to use the **Gnuplot.jl** package you'll need [`gnuplot`](http://gnuplot.info/) (ver. >= 5.0) installed on your system, and its executable available in your path.
+
+If `gnuplot` is not available in your platform you can still use **Gnuplot.jl** in "*dry*" mode (see [Dry sessions](@ref)).  In this case a plot can not be generated, but you may still generate [Gnuplot scripts](@ref).
+
+## Package installation
+In the Julia REPL type:
+```julia-repl
+julia> ]add Gnuplot
+```
+The `]` character starts the Julia [package manager](https://julialang.github.io/Pkg.jl/v1/getting-started.html#Basic-Usage-1). Hit backspace key to return to Julia prompt.
+
+
+## Check installation
+
+Check **Gnuplot.jl** version with:
+```julia-repl
+julia> ]st Gnuplot
+Status `~/.julia/environments/v1.4/Project.toml`
+  [dc211083] Gnuplot v1.4.1
+```
+If the displayed version is not `v1.4.1` you are probably having a dependency conflict.  In this case try forcing installation of the latest version with:
+```julia-repl
+julia> ]add Gnuplot@1.4.1
+```
+and check which package is causing the conflict.
+
+
+
+Check execution and version of the underlying `gnuplot` process:
+```@repl
+using Gnuplot
+Gnuplot.gpversion()
+```
+The minimum required version is `v5.0`.
+
+
+Generate the first plot:
+```julia-repl
+julia> @gp 1:9
+```
+
+Test default terminal capabilities:
+```julia-repl
+test_terminal()
+```

docs/src/options.md

@@ -0,0 +1,114 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+# Display options
+
+The display behaviour of **Gnuplot.jl** depends on the value of the `Gnuplot.options.gpviewer` flag:
+
+- if `true` the plot is displayed in a gnuplot window, using one of the interactive terminals such as `wxt`, `qt` or `aqua`.  This is the default setting when running a Julia REPL session; The terminal options can be customized using `Gnuplot.options.term`;
+
+- if `false` the plot is displayed through the Julia [multimedia interface](https://docs.julialang.org/en/v1/base/io-network/#Multimedia-I/O-1), i.e. it is exported as either a `png`, `svg` or `html` file, and displayed in an external viewer.  This is the default setting when running a Jupyter, JupyterLab or Juno session.  The terminal options can be customized using the `Gnuplot.options.mime` dictionary.
+
+The `Gnuplot.options.gpviewer` flag is automatically set when the package is first loaded according to the runtime environment, however the user can change its value at any time to fit specific needs.  Further informations and examples for both options are available in this Jupyter [notebook](https://github.com/gcalderone/Gnuplot.jl/blob/gh-pages/v1.3.0/options/display.ipynb).
+
+
+
+
+# Package options and initialization
+
+## Options
+The package options are stored in a global structure available in Julia as `Gnuplot.option` (the type of the structure is [`Gnuplot.Options`](@ref)).  The most important settings are as follows:
+
+- `dry::Bool`: if true all new sessions will be started as [Dry sessions](@ref).  Default is `false`, but if the package is not able to start a gnuplot process it will automatically switch to `true`;
+
+- `cmd::String`: command to start the gnuplot process, default value is `"gnuplot"`.  Use this field to specify a custom path to the gnuplot executable;
+
+- `gpviewer::Bool`: use a gnuplot terminal as main plotting device (if `true`) or an external viewer (if `false`);
+
+- `term::String`: default terminal for interactive use (default is an empty string, i.e. use gnuplot settings).  A custom terminal can be set with, e.g.:
+```@repl abc
+Gnuplot.options.term = "wxt size 700,400";
+```
+
+- `mime::Dict{MIME, String}`: dictionary of MIME types and corresponding gnuplot terminals.  Used to export images with either [`save()`](@ref) or `show()` (see [Display options](@ref)).  Default values are:
+  - `MIME"application/pdf" => "pdfcairo enhanced"`
+  - `MIME"image/jpeg"      => "jpeg enhanced"`
+  - `MIME"image/png"       => "pngcairo enhanced"`
+  - `MIME"image/svg+xml"   => "svg enhanced mouse standalone dynamic background rgb 'white'"`
+  - `MIME"text/html"       => "svg enhanced mouse standalone dynamic"`
+  - `MIME"text/plain"      => "dumb enhanced ansi"`
+
+
+- `init::Vector{String}`: commands to initialize the session when it is created or reset.  It can be used to, e.g., set a custom linetypes or palette:
+```@repl abc
+push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5));
+```
+Note that this option affect all the sessions, and that all inserted commands are saved in [Gnuplot scripts](@ref);
+
+- `verbose::Bool`: a flag to set verbosity of the package.  If `true` all communication with the underlying process will be printed on stdout. E.g.:
+```@repl abc
+empty!(Gnuplot.options.init);                              # hide
+gpexec("set term wxt");                                    # hide
+Gnuplot.options.verbose = true;
+x = 1.:10;
+@gp x x.^2 "w l t 'Parabola'"
+save(term="pngcairo size 480,360 fontscale 0.8", output="output.png")
+Gnuplot.options.verbose = false                            # hide
+push!(Gnuplot.options.init, linetypes(:Set1_5, lw=1.5));   # hide
+gpexec("set term unknown");                                # hide
+```
+Each line reports the package name (`GNUPLOT`), the session name (`default`), the command or string being sent to gnuplot process, and the returned response (line starting with `->`).  Default value is `false`;
+
+
+## Package initialization
+
+If you use **Gnuplot.jl** frequently you may find convenient to automatically apply the package settings ([Options](@ref)) whenever the package is loaded.  A possibility is to use [Requires.jl](https://github.com/JuliaPackaging/Requires.jl) and put the following code in the `~/.julia/config/startup.jl` initialization file (further info [here](https://docs.julialang.org/en/v1/stdlib/REPL/)):
+```julia
+using Requires
+@require Gnuplot="dc211083-a33a-5b79-959f-2ff34033469d" begin
+        @info "Custom Gnuplot initialization"
+        # Uncomment the following if you don't have the gnuplot
+        # executable installed on your platform:
+        #Gnuplot.options.dry = true;
+
+        # Set the proper path if the gnuplot executable is not
+        # available in your $PATH
+        #Gnuplot.options.cmd = "/path/to/gnuplot";
+
+        # Force a specific display behaviour (see documentation).  If
+        # not given explicit Gnuplot.jl will choose the best option
+        # according to your runtime environment.
+        #Gnuplot.options.gpviewer = true
+
+        # Set the default terminal for interacitve use
+        Gnuplot.options.term = "wxt size 700,400";
+
+        # Set the terminal options for the exported MIME types:
+        #Gnuplot.options.mime[MIME"image/png"] = "";
+        #Gnuplot.options.mime[MIME"image/svg+xml"] = "svg enhanced standalone dynamic";
+        #Gnuplot.options.mime[MIME"text/html"] = "svg enhanced standalone mouse dynamic";
+
+        # Set the terminal to plot in a terminal emulator:
+        # (try with `save(MIME"text/plain")`):
+        #Gnuplot.options.mime[MIME"text/plain"] = "sixelgd enhanced"; # requires vt340 emulation
+
+        # Set the default linetypes
+        empty!(Gnuplot.options.init);
+        push!(Gnuplot.options.init, Gnuplot.linetypes(:Set1_5, lw=1.5, ps=1.5));
+
+        # Initialize the gnuplot REPL using the provided `start_key`.
+        if Gnuplot.options.gpviewer;
+            Gnuplot.repl_init(start_key='>');
+        end;
+end
+```
+
+The above code will be automatically when you first load the package with `using Gnuplot`.

docs/src/recipes.md

@@ -0,0 +1,136 @@
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+mkpath("assets")
+
+Gnuplot.options.term = "unknown"
+empty!(Gnuplot.options.init)
+push!( Gnuplot.options.init, linetypes(:Set1_5, lw=1.5, ps=1.5))
+saveas(file) = save(term="pngcairo size 550,350 fontscale 0.8", output="assets/$(file).png")
+```
+
+
+# Plot recipes
+
+A plot *recipe* is a quicklook visualization procedure aimed at reducing the amount of repetitive code to generate a plot.  More specifically, a recipe is a function that convert data from the "Julia world" into a form suitable to be ingested in **Gnuplot.jl**, namely a scalar (or a vector of) [`Gnuplot.PlotElement`](@ref) object(s).  The latter contain informations on how to create a plot, or a part of it, and can be used directly as arguments in a `@gp` or `@gsp` call.
+
+There are two kinds of recipes:
+
+- *explicit* recipe: a function which is explicitly invoked by the user.  It can have any name and accept any number of arguments and keywords.  It is typically used when the visualization of a data type requires some extra information, beside data itself (e.g. to plot data from a `DataFrame` object, see [Explicit recipe (example)](@ref));
+
+- *implicit* recipe: a function which is automatically called by **Gnuplot.jl**.  It must extend the [`recipe()`](@ref) function, and accept exactly one mandatory argument.  It is typically used when the visualization is completely determined by the data type itself (e.g. the visualization of a `Matrix{ColorTypes.RGB}` object as an image, see [Image recipes](@ref));
+
+An implicit recipe is invoked whenever the data type of an argument to `@gp` or `@gsp` is not among the allowed ones (see [`@gp()`](@ref) documentation).  If a suitable recipe do not exists an error is raised.  On the other hand, an explicit recipe needs to be invoked by the user, and the output passed directly to `@gp` or `@gsp`.
+
+Although recipes provides very efficient tools for data exploration, their use typically hide the details of plot generation.  As a consequence they provide less flexibility than the approaches described in [Basic usage](@ref) and [Advanced usage](@ref).
+
+Currently, the **Gnuplot.jl** package provides no built-in explicit recipe.  The implicit recipes are implemented in [recipes.jl](https://github.com/gcalderone/Gnuplot.jl/blob/master/src/recipes.jl).
+
+
+
+## Explicit recipe (example)
+
+To generate a plot using the data contained in a `DataFrame` object we need, beside the data itself, the name of the columns to use for the X and Y coordinates.  The following example shows how to implement an explicit recipe to plot a `DataFrame` object:
+```@example abc
+using RDatasets, DataFrames, Gnuplot
+import Gnuplot: PlotElement, DatasetText
+
+function plotdf(df::DataFrame, colx::Symbol, coly::Symbol; group=nothing)
+    if isnothing(group)
+        return PlotElement(data=DatasetText(df[:, colx], df[:, coly]),
+                           plot="w p notit",
+                           xlab=string(colx), ylab=string(coly))
+    end
+
+    out = Vector{Gnuplot.PlotElement}()
+    push!(out, PlotElement(;xlab=string(colx), ylab=string(coly)))
+    for g in sort(unique(df[:, group]))
+        i = findall(df[:, group] .== g)
+        if length(i) > 0
+            push!(out, PlotElement(data=DatasetText(df[i, colx], df[i, coly]),
+                                   plot="w p t '$g'"))
+        end
+    end
+    return out
+end
+
+# Load a DataFrame and convert it to a PlotElement
+iris = dataset("datasets", "iris")
+@gp plotdf(iris, :SepalLength, :SepalWidth, group=:Species)
+saveas("recipes001") # hide
+```
+![](assets/recipes001.png)
+
+
+
+## Histogram recipes
+The object returned by the [`hist()`](@ref) function can be readily visualized by means of implicit recipes defined on the `Gnuplot.Histogram1D` and `Gnuplot.Histogram2D` types:
+
+```@example abc
+x = randn(1000);
+@gp hist(x)
+saveas("recipes002") # hide
+```
+![](assets/recipes002.png)
+
+
+```@example abc
+x = randn(10_000);
+y = randn(10_000);
+@gp hist(x, y)
+saveas("recipes002a") # hide
+```
+![](assets/recipes002a.png)
+
+
+## Contour lines recipes
+The object returned by the [`contourlines()`](@ref) function can be readily visualized by means of implicit recipes defined on the `Gnuplot.IsoContourLines` types:
+```@example abc
+x = randn(10_000);
+y = randn(10_000);
+h = hist(x, y)
+clines = contourlines(h, "levels discrete 10, 30, 60, 90");
+@gp clines
+saveas("recipes002b") # hide
+```
+![](assets/recipes002b.png)
+
+
+
+
+## Image recipes
+
+The **Gnuplot.jl** package provides implicit recipes to display images in the following formats:
+- `Matrix{ColorTypes.RGB{T}}`;
+- `Matrix{ColorTypes.RGBA{T}}`
+- `Matrix{ColorTypes.Gray{T}}`;
+- `Matrix{ColorTypes.GrayA{T}}`;
+
+To use these recipes simply pass an image to `@gp`, e.g.:
+```@example abc
+using TestImages
+img = testimage("lighthouse");
+@gp img
+saveas("recipes007b") # hide
+```
+![](assets/recipes007b.png)
+
+
+All such recipes are defined as:
+```julia
+function recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy")
+  ...
+end
+```
+with only one mandatory argument.  In order to exploit the optional keyword we can explicitly invoke the recipe as follows:
+```@example abc
+img = testimage("walkbridge");
+@gp palette(:gray1) recipe(img, "flipy rot=15deg")
+saveas("recipes007c") # hide
+```
+![](assets/recipes007c.png)
+
+Note that we used both a palette (`:gray`, see [Palettes and line types](@ref)) and a custom rotation angle.
+
+
+The `flipy` option is necessary for proper visualization (see discussion in [Plot matrix as images](@ref)).

docs/src/style.md

@@ -0,0 +1,101 @@
+# Style Guide
+
+The **Gnuplot.jl** loose syntax allows to create a plot using very different approaches.  While this was one of the initial purposes for the package, it may lead to a reduced code readability if not used judiciously.
+
+Here I will summarize a few, non-mandatory, guidelines which allows to maintain a neat syntax and a high readability:
+
+### 1 - Use macros without parentheses and commas:
+The two most important symbols exported by the package (`@gp` and `@gsp`) are macros.  As such they are supposed to be invoked without parentheses and commas.  E.g. use:
+```julia
+@gp x y "with lines"
+```
+in place of
+```julia
+@gp(x, y, "with lines")
+```
+
+If you have very long lines you may split them in multiple statements using the `:-` symbol, which resembles both hyphenation in natural language and indentation for the plot-producing code:
+```julia
+@gp    "set grid" :-
+@gp :- x y "with lines"
+```
+Note that the trailing `:-` symbol is not mandatory.  If omitted, the plot will be updated at each statement (rather than at the last one).
+
+
+### 2 - Use keywords in place of gnuplot commands:
+
+As discussed in [Keywords for common commands](@ref) several commonly used gnuplot commands can be replaced with a keyword.  E.g. you can use
+```julia
+@gp ... xrange=[-1,5] ...
+```
+in place of
+```julia
+@gp ... "set xrange [-1:5]" ...
+```
+This help reducing the number of strings, as well as the associated interpolating characters (`$`), and results in a more concise syntax.
+
+
+### 3 - Use abbreviations for commands and keywords:
+
+Many gnuplot commands, as well as all keywords (see [Keywords for common commands](@ref)), can be abbreviated as long as the abbreviation is unambiguous.  E.g., the following code:
+```julia
+@gp    "set grid" "set key left" "set logscale y"
+@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:*]"
+@gp :- x y "with lines"
+```
+can be replaced with a shorter version:
+```julia
+@gp    "set grid" k="left" ylog=true
+@gp :- tit="Plot title" xlab="X label" xr=[0,NaN]
+@gp :- x y "w l"
+```
+Besides being more idiomatic, the possibility to exploit abbreviations is of great importance when performing interactive data exploration.
+
+Moreover, in many gnuplot examples and documentation it is very common to use abbreviations (i.e. `w l` in place of `with lines`) so there is no reason to avoid them in **Gnuplot.jl**.
+
+
+
+### 4 - If possible, follow the *commands* -> *data* + *plot specs* order
+
+The two following examples produce exactly the same plot:
+```julia
+x = -10.:10
+@gp    "set grid" "set multiplot layout 2,1"
+@gp :- 1 x x.^2 "w l t 'f(x) = x^2"  # first plot
+@gp :- 2 x x.^3 "w l t 'f(x) = x^3"  # second plot
+```
+and
+```julia
+@gp    2 x x.^3 "w l t 'f(x) = x^3"  # second plot
+@gp :- 1 x x.^2 "w l t 'f(x) = x^2"  # first plot
+@gp :- "set grid" "set multiplot layout 2,1"
+```
+However, the first form appears more *logical* and easy to follow.
+
+In analogy with previous example, even on single plot, the following form
+```julia
+@gp    "set grid"
+@gp :- x x.^2 "w l t 'f(x) = x^2"
+```
+should be preferred over
+```julia
+@gp    x x.^2 "w l t 'f(x) = x^2"
+@gp :- "set grid"
+```
+even if the output is exactly the same.
+
+
+### 5 - Join multiple command strings:
+
+Instead of specifying several commands as strings
+```julia
+@gp :- "set key off"  "set auto fix"  "set size square"
+@gp :- "set offsets graph .05, graph .05, graph .05, graph .05"
+@gp :- "set border lw 1 lc rgb 'white'"
+```
+join them in a single string using triple quotes and `;`
+```julia
+@gp :- """set key off;  set auto fix;  set size square;
+          set offsets graph .05, graph .05, graph .05, graph .05;
+          set border lw 1 lc rgb 'white'; """
+```

docs/src/terminals.md

@@ -0,0 +1,115 @@
+# Gnuplot terminals
+
+Gnuplot provides dozens of terminals to display plots or export them into files (see [`terminals()`](@ref) to get a list of enabled terminals on your platform).  This section discuss a few tips on how to use the most common terminals.
+
+To use a specific terminal for interactive use you may either set it as initialization command for all new session with (see [Options](@ref)):
+```julia
+Gnuplot.options.term = "wxt"
+```
+See official [gnuplot documentation](http://gnuplot.sourceforge.net/documentation.html) for further info on terminals and their options.
+
+
+## Interactive terminals (`wxt` and `qt`)
+The multiplatform `wxt` and `qt` terminals are among the most widely used ones for their nicely looking outputs on display and for their interactive capabilities.
+
+You may use such terminals with:
+```
+Gnuplot.options.term = "wxt size 800,600"
+```
+or
+```
+Gnuplot.options.term = "qt  size 800,600"
+```
+(the `size 800,600` is optional and can be omitted).
+
+Press the `h` key on the window to display an help message with all available keyboard shortcuts.  In particular press `6` to enable printing plot coordinates on Julia stdout (ensure mouse is enabled with `m`).
+
+
+## Plot in a terminal application (`dumb`, `sixel` and `sixelgd`)
+Gnuplot supports plotting in a terminal application, with no need for X11 or other GUI support, via the `dumb`, `sixel` and `sixelgd` terminals.  These are extremely useful when you run Julia on a remote shell through `ssh`, with no X11 forwarding. The `dumb` terminal uses ASCII characters to draw a plot, while `sixel` and `sixelgd` actually use bitmaps (but require Sixel support to be enabled in the terminal, e.g. `xterm -ti vt340`).
+
+Dumb terminal can be used as follows:
+
+```jldoctest; setup = :(using Gnuplot)
+julia> origterm = Gnuplot.options.term;
+
+julia> Gnuplot.options.term = "dumb size 60,15";
+
+julia> @gp "plot sin(x)"
+
+    1 +-------------------------------------------------+
+  0.8 |-+         *+ *         + ** **      +    *  * +-|
+  0.6 |-+        *   **          *   *   sin(x) *******-|
+  0.4 |*+        *    *         *     *         *    *+-|
+  0.2 |*+       *      *        *     *        *      *-|
+    0 |*+       *      *       *       *       *      *-|
+      | *      *       *       *       *      *        *|
+ -0.2 |-*      *        *     *        *      *       +*|
+ -0.4 |-+*    *         *     *         *    *        +*|
+ -0.6 |-+*    *          *   *          **   *        +-|
+ -0.8 |-+ *  *     +     ** ** +         *  *         +-|
+   -1 +-------------------------------------------------+
+     -10          -5           0            5           10
+
+julia> Gnuplot.options.term = origterm;
+
+```
+A sixel plot on `xterm` looks as follows:
+![](assets/sixelgd.png)
+
+The above terminals are available if gnuplot has been compiled with the `--with-bitmap-terminals` option enabled and Libgd (only for `sixelgd`).
+
+
+## Export to image files
+
+Gnuplot provides dozens of terminals able to export on files.  Examples are:
+- `pngcairo` to export PNG files;
+- `pdfcairo` for PDF;
+- `jpeg` for JPG;
+- `gif` for GIF (see [Animations](@ref)).
+
+All the above terminals support the `size` and `fontscale` options to quickly adjust the size of the rasterized image and the size of the font respectively.  E.g.:
+```julia
+save(term="pngcairo size 480,360 fontscale 0.8", output="output.png")
+```
+(see also [`save()`](@ref)).
+
+Gnuplot is also able to export vector (i.e. non-raster) plots through the `svg` terminal.
+
+## The `cairolatex` terminal
+The `cairolatex` terminal allows to produce high quality plots by splitting the output into a PDF file (containing a rasterized image of a plot) and a `.tex` file (containing all the text as ``\LaTeX`` code).  The following example shows how to write plot tics and an equation in ``\LaTeX``:
+```julia
+x = LinRange(-2pi, 2pi, 1000)
+@gp tit="Polynomial approximation of sin(x)"  "set style fill transparent solid 0.6 noborder"
+@gp :- raw"""set xtics ('$-\pi$' -pi, '$-\pi/2$' -pi/2, 0, '$\pi/2$' pi/2, '$\pi$' pi)"""
+@gp :- xr=3.8.*[-1, 1] yr=[-1.5,1.5] key="box opaque left horiz" linetypes(:Blues_3) "set grid front"
+latex = raw"""\begin{minipage}[c]{\textwidth}\begin{equation*}""" *
+	raw"""\sin(x) = \sum_0^{+\infty} \frac{(-1)^n}{(2n + 1)!} x^{2n+1}""" * 
+	raw"""\end{equation*} \end{minipage}"""
+@gp :- "set label at graph 0.62,0.2 front center '$latex'"
+approx = fill(0., length(x));
+@gp :- x sin.(x) approx .+=  x          "w filledcurve t 'n=0' lt 1"
+@gp :- x sin.(x) approx .+= -x.^3/6     "w filledcurve t 'n=1' lt 2"
+@gp :- x sin.(x) approx .+=  x.^5/120   "w filledcurve t 'n=2' lt 3"
+@gp :- x sin.(x) approx .+= -x.^7/5040  "w filledcurve t 'n=3' lt 4"
+@gp :- x sin.(x)                        "w l t 'sin(x)' lw 2 lc rgb 'black'"
+save(term="cairolatex pdf input color dashed size 5in,3.3in", output="test.tex")
+```
+!!! warning
+    If you add a path in the `output=` keyword this will also be copied in the the `.tex` file, and may generate errors when compiling ``\LaTeX`` code.  The simplest way to solve this problem is to use just filenames, with no paths.
+
+The two output files (`test.tex` and `test.pdf`) can then be included in a ``\LaTeX`` file as follows:
+```latex
+\documentclass{article}
+\usepackage{amsmath}
+\usepackage{graphicx}
+\usepackage{color}
+
+\begin{document}
+\begin{figure}
+  \input{test.tex}
+\end{figure}
+\end{document}
+```
+And the output is:
+![](assets/cairolatex.png)

examples/hidden2.1.jl

@@ -0,0 +1,19 @@
+# Original example:
+# http://gnuplot.sourceforge.net/demo/hidden2.html
+
+using Gnuplot
+
+x = LinRange(-10, 10, 25)
+y = LinRange(-10, 10, 25)
+
+@gsp    "set xyplane at 0"
+@gsp :- "unset key" :-
+@gsp :- "set palette rgbformulae 31,-11,32"
+@gsp :- "set style fill solid 0.5"
+@gsp :- "set cbrange [-1:1]"
+@gsp :- title="Mixing pm3d surfaces with hidden-line plots"
+@gsp :- "set hidden3d front"
+
+f = [sin(-sqrt((x+5)^2+(y-7)^2)*0.5) for x in x, y in y]
+z = [x*x-y*y for x in x, y in y]
+@gsp :- x y f "w pm3d" x y z "w l lc rgb 'black'"

examples/hidden2.3.jl

@@ -0,0 +1,41 @@
+# Original example:
+# http://gnuplot.sourceforge.net/demo/hidden2.html
+
+using Gnuplot
+
+@gsp "set multiplot title 'Interlocking Tori'"
+U = LinRange(-pi, pi, 100); # 50
+V = LinRange(-pi, pi, 20);
+
+@gsp :- "unset key"
+@gsp :- "unset xtics"
+@gsp :- "unset ytics"
+@gsp :- "unset ztics"
+@gsp :- "set border 0"
+@gsp :- "set view 60, 30, 1.5, 0.9"
+@gsp :- "unset colorbox"
+@gsp :- "set colorbox vertical user origin 0.9, 0.15 size 0.02, 0.50"
+@gsp :- "set format cb '%.1f'"
+
+for loop in 1:2
+    if loop == 1
+        @gsp :- 1 title="PM3D surface\\nno depth sorting"
+        @gsp :- "set origin -0.02,0.0"
+        @gsp :- "set size 0.55, 0.9"
+        @gsp :- "set pm3d scansforward" :-  # scansbackward
+    else
+        @gsp :- 2 title="PM3D surface\\ndepth sorting"
+        @gsp :- "set origin 0.40,0.0"
+        @gsp :- "set size 0.55, 0.9"
+        @gsp :- "set pm3d depthorder"
+    end
+    x = [cos(u) + .5 * cos(u) * cos(v)      for u in U, v in V]
+    y = [sin(u) + .5 * sin(u) * cos(v)      for u in U, v in V]
+    z = [.5 * sin(v)                        for u in U, v in V]
+    @gsp :- x' y' z' "w pm3d"
+
+    x = [1 + cos(u) + .5 * cos(u) * cos(v)  for u in U, v in V]
+    y = [.5 * sin(v)                        for u in U, v in V]
+    z = [sin(u) + .5 * sin(u) * cos(v)      for u in U, v in V]
+    @gsp :- x' y' z' "w pm3d"
+end

src/recipes.jl

@@ -0,0 +1,73 @@
+# ╭───────────────────────────────────────────────────────────────────╮
+# │                       IMPLICIT RECIPES                            │
+# ╰───────────────────────────────────────────────────────────────────╯
+
+# --------------------------------------------------------------------
+# Histograms
+"""
+    recipe(h::Histogram1D)
+    recipe(h::Histogram2D)
+
+Implicit recipes to visualize 1D and 2D histograms.
+"""
+recipe(h::Histogram1D) =
+    PlotElement(cmds="set grid",
+                data=DatasetText(h.bins, h.counts),
+                plot="w histep notit lw 2 lc rgb 'black'")
+
+recipe(h::Histogram2D) =
+    PlotElement(cmds=["set autoscale fix"],
+                data=DatasetText(h.bins1, h.bins2, h.counts),
+                plot="w image notit")
+
+
+# --------------------------------------------------------------------
+# Contour lines
+"""
+    recipe(c::IsoContourLines)
+    recipe(v::Vector{IsoContourLines})
+
+Implicit recipes to visualize iso-contour lines.
+"""
+function recipe(c::IsoContourLines)
+    if isnan(c.prob)
+        return PlotElement(data=c.data, plot="w l t '$(c.z)'")
+    end
+    return PlotElement(data=c.data, plot="w l t '$(round(c.prob * 100, sigdigits=6))%'")
+end
+recipe(v::Vector{IsoContourLines}) = recipe.(v)
+
+
+# --------------------------------------------------------------------
+# Images
+"""
+    recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.RGBA{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.Gray{T}}, opt="flipy")
+    recipe(M::Matrix{ColorTypes.GrayA{T}}, opt="flipy")
+
+Implicit recipes to show images.
+"""
+recipe(M::Matrix{ColorTypes.RGB{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :r),
+                                256 .* getfield.(M, :g),
+                                256 .* getfield.(M, :b)),
+                plot="$opt with rgbimage notit")
+
+recipe(M::Matrix{ColorTypes.RGBA{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :r),
+                                256 .* getfield.(M, :g),
+                                256 .* getfield.(M, :b)),
+                plot="$opt with rgbimage notit")
+
+recipe(M::Matrix{ColorTypes.Gray{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :val)),
+                plot="$opt with image notit")
+
+recipe(M::Matrix{ColorTypes.GrayA{T}}, opt="flipy") where T =
+    PlotElement(cmds=["set autoscale fix", "set size ratio -1"],
+                data=DatasetBin(256 .* getfield.(M, :val)),
+                plot="$opt with image notit")

test/runtests.jl

@@ -1,52 +1,175 @@
-using Gnuplot
+using Test, Gnuplot
+try
+    @info "Gnuplot.jl version: " * string(Gnuplot.version())
+    @info "gnuplot    version: " * string(Gnuplot.gpversion())
+catch
+    Gnuplot.options.dry = true
+end
+Gnuplot.options.gpviewer = true
+
+x = [1, 2, 3]
+y = [4, 5, 6]
+
+s = Gnuplot.arrays2datablock(x)
+@test all(s .== [" 1"   ,
+                 " 2"   ,
+                 " 3"   ])
+
+s = Gnuplot.arrays2datablock(x, y)
+@test all(s .== [" 1 4",
+                 " 2 5",
+                 " 3 6"])
+
+s = Gnuplot.arrays2datablock(x, y, x.+y)
+@test all(s .== [" 1 4 5",
+                 " 2 5 7",
+                 " 3 6 9"])
+
+z = [X+Y for X in x, Y in y];
+s = Gnuplot.arrays2datablock(z)
+@test all(s .== ["0 0 5",
+                 "1 0 6",
+                 "2 0 7",
+                 ""     ,
+                 "0 1 6",
+                 "1 1 7",
+                 "2 1 8",
+                 ""     ,
+                 "0 2 7",
+                 "1 2 8",
+                 "2 2 9"])
+
+s = Gnuplot.arrays2datablock(z, z)
+@test all(s .== [" 5 5",
+                 " 6 6",
+                 " 7 7",
+                 ""    ,
+                 " 6 6",
+                 " 7 7",
+                 " 8 8",
+                 ""    ,
+                 " 7 7",
+                 " 8 8",
+                 " 9 9"])
+
+s = Gnuplot.arrays2datablock(x, y, z)
+@test all(s .== [" 1 4 5" ,
+                 " 2 4 6" ,
+                 " 3 4 7" ,
+                 ""       ,
+                 " 1 5 6" ,
+                 " 2 5 7" ,
+                 " 3 5 8" ,
+                 ""       ,
+                 " 1 6 7" ,
+                 " 2 6 8" ,
+                 " 3 6 9" ])
+
+c = [[X, Y] for Y in y for X in x];  # First Y (i.e. rows) then X (i.e. columns)
+u = getindex.(c, 1)
+v = getindex.(c, 2)
+
+s = Gnuplot.arrays2datablock(u, v, z)
+@test all(s .== [" 1 4 5" ,
+                 " 2 4 6" ,
+                 " 3 4 7" ,
+                 ""       ,
+                 " 1 5 6" ,
+                 " 2 5 7" ,
+                 " 3 5 8" ,
+                 ""       ,
+                 " 1 6 7" ,
+                 " 2 6 8" ,
+                 " 3 6 9" ])
+
+s = Gnuplot.arrays2datablock(1:3, 1:3, ["One", "Two", "Three"])
+@test all(s .== [ " 1 1 \"One\""  ,
+                  " 2 2 \"Two\""  ,
+                  " 3 3 \"Three\""])
 
-x = collect(1.:100);
 
 #-----------------------------------------------------------------
+dummy = palette_names()
+pal = palette(:deepsea)
+@test pal == "set palette defined (0.0 '#2B004D', 0.25 '#4E0F99', 0.5 '#3C54D4', 0.75 '#48A9F8', 1.0 '#C5ECFF')\nset palette maxcol 5\n"
+ls = linetypes(:Set1_5, lw=1.5, ps=2)
+@test ls == "unset for [i=1:256] linetype i\nset linetype 1 lc rgb '#E41A1C' lw 1.5 dt solid pt 1 ps 2\nset linetype 2 lc rgb '#377EB8' lw 1.5 dt solid pt 2 ps 2\nset linetype 3 lc rgb '#4DAF4A' lw 1.5 dt solid pt 3 ps 2\nset linetype 4 lc rgb '#984EA3' lw 1.5 dt solid pt 4 ps 2\nset linetype 5 lc rgb '#FF7F00' lw 1.5 dt solid pt 5 ps 2\nset linetype cycle 5\n"
+
+dummy = terminals()
+# if "sixelgd" in terminals()
+#     Gnuplot.options.term = "sixelgd enhanced"
+# elseif "sixel" in terminals()
+#     Gnuplot.options.term = "sixel enhanced"
+# elseif "dumb" in terminals()
+#     Gnuplot.options.term = "dumb"
+# else
+#     Gnuplot.options.term = "unknown"
+# end
+# Gnuplot.quitall()
+
+# Force unknown on Travis CI
+Gnuplot.options.term = "unknown"
+
+@gp 1:9
+@info "using terminal: " terminal()
+#test_terminal("unknown")
+
+#-----------------------------------------------------------------
+# Test wth empty dataset
+@gp Float64[]
+@gsp Float64[]
+@gp Float64[] Float64[]
+@gsp Float64[] Float64[]
+
+
+#-----------------------------------------------------------------
+x = collect(1.:100);
+
 for i in 1:10
     @gp :gp1 "plot sin($i*x)"
     @gp :gp2 "plot sin($i*x)"
     @gp :gp3 "plot sin($i*x)"
     sleep(0.3)
 end
-quitall()
+Gnuplot.quitall()
 
 #-----------------------------------------------------------------
 @gp "plot sin(x)"
 @gp "plot sin(x)" "pl cos(x)"
 @gp "plo sin(x)" "s cos(x)"
 
-@gp "plot sin(x)" :-
-@gp :- "plot cos(x)"
-
+@gp mar="0,1,0,1" "plot sin(x)"
+@gp :- mar=gpmargins() "plot cos(x)"
+@gp :- 0. 0.
 
 @gp "plot sin(x)" 2 xr=(-2pi,2pi) "pause 2" "plot cos(4*x)"
 
 x = range(-2pi, stop=2pi, length=100);
 y = 1.5 * sin.(0.3 .+ 0.7x);
-noise = randn(length(x))./2;
-e = 0.5 * fill(1, size(x));
-
-@gp hist(noise, nbins=10)
+err = 0.1 * maximum(abs.(y)) .* fill(1, size(x));
+noise = err .* randn(length(x));
 
+h = hist(noise, nbins=10)
+@gp h.bins h.counts "w histeps"
+@gp h
 
 @gp x y
 @gp x y "w l"
 
 name = "\$MyDataSet1"
-@gp x y name "plot $name w l" "pl $name u 1:(2*\$2) w l"
+@gp name=>(x, y) "plot $name w l" "pl $name u 1:(2*\$2) w l"
 
 @gsp randn(Float64, 30, 50)
-@gp randn(Float64, 30, 50) "w image"
+@gp 1:30 1:50 randn(Float64, 30, 50) "w image"
 @gsp x y y
 
 @gp("set key horizontal", "set grid",
     xrange=(-7,7), ylabel="Y label",
     x, y, "w l t 'Real model' dt 2 lw 2 lc rgb 'red'",
-    x, y+noise, e, "w errorbars t 'Data'")
+    x, y+noise, err, "w errorbars t 'Data'")
 
 @gp "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;"   :-
-@gp :- x y+noise e name                               :-
+@gp :- name=>(x, y+noise, err)                        :-
 @gp :- "fit f(x) $name u 1:2:3 via a, b, c;"          :-
 @gp :- "set multiplot layout 2,1"                     :-
 @gp :- "plot $name w points" ylab="Data and model"    :-
@@ -55,27 +178,29 @@ name = "\$MyDataSet1"
 @gp :- "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit"
 
 # Retrieve values for a, b and c
-a = 0; b = 0; c = 0;
-try
-    a = parse(Float64, exec("print a"))
-    b = parse(Float64, exec("print b"))
-    c = parse(Float64, exec("print c"))
-catch
+if Gnuplot.options.dry
+    a = 1.5
+    b = 0.3
+    c = 0.7
+else
+    a = Meta.parse(gpexec("print a"))
+    b = Meta.parse(gpexec("print b"))
+    c = Meta.parse(gpexec("print c"))
 end
-gnuplot(:dry)
+
 @gp    :dry "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;"  :-
 @gp :- :dry "a = $a; b = $b; c = $c"                         :-
 @gp :- :dry "set multiplot layout 2,1" ylab="Data and model" :-
 name = "\$MyDataSet1"
-@gp :- :dry x y+noise e name                                 :-
+@gp :- :dry name=>(x, y+noise, err)                          :-
 @gp :- :dry "plot $name w points"                            :-
 @gp :- :dry "plot $name u 1:(f(\$1)) w lines"                :-
 @gp :- :dry 2 xlab="X label" ylab="Residuals"                :-
 @gp :- :dry "plot $name u 1:((f(\$1)-\$2) / \$3):(1) w errorbars notit" :-
 @gp :- :dry
-save("test.gp")        # write on file test.gp
-quitall()
-exec("load 'test.gp'") # load file test.gp
+save(:dry, "test.gp")        # write on file test.gp
+Gnuplot.quitall()
+#gpexec("load 'test.gp'") # load file test.gp, commented to avoid errors in CI
 
 #-----------------------------------------------------------------
 @gp("""
@@ -140,4 +265,29 @@ exec("load 'test.gp'") # load file test.gp
 	"splot x8, v, (u<0.5) ? -1 : sinc(x8,v) notitle",
 	"splot x9, v, (u<0.5) ? -1 : sinc(x9,v) notitle")
 
-quitall()
+
+
+x = randn(5000);
+y = randn(5000);
+h = hist(x, y, nbins1=20, nbins2=20);
+clines = contourlines(h, "levels discrete 15, 30, 45");
+@gp clines
+@gp "set size ratio -1"
+for i in 1:length(clines)
+    @gp :- clines[i].data "w l t '$(clines[i].z)' lw $i dt $i"
+end
+
+
+Gnuplot.options.verbose = true
+@gp randn(10^6) randn(10^6)
+@gp :- 0. 0.
+Gnuplot.quit(:default)
+
+Gnuplot.options.dry = true
+@gp hist(randn(1000))
+
+# Various hist() corner cases
+@gp hist([1,2,3], bs=2)
+@gp hist([1,1,1], bs=1)
+
+Gnuplot.quitall()