Docs updated

docs/make.jl

@@ -1,13 +1,47 @@
 using Documenter, Gnuplot
 
 makedocs(sitename="Gnuplot.jl",
-         #format = Documenter.HTML(prettyurls = false),
+         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",
+             "Advanced techniques" => "advanced.md",
              "Examples" => "examples.md",
              "API" => "api.md"
          ])
+
+
+#=
+- Make documentation:
+cd <repo>/docs
+julia --color=yes make.jl
+
+
+- Workflow to prepare `gh-pages` branch:
+
+Change to a temporary directory, then:
+git clone --no-checkout https://github.com/gcalderone/Gnuplot.jl.git
+git checkout --orphan gh-pages
+git rm -rf .
+
+Now copy the documentation "build" directory into, e.g., "dev", then
+git add dev/*
+git commit -m 'First commit'
+git push origin gh-pages
+
+
+- Workflow to push changes to `gh-pages` branch:
+Change to a temporary directory, then:
+git clone --single-branch --branch gh-pages  https://github.com/gcalderone/Gnuplot.jl.git
+
+Now copy the documentation "build" directory into, e.g., "dev", then
+git add dev/*
+git commit -m 'Updated'
+git push origin gh-pages
+
+- Documentation will be available online at:
+https://gcalderone.github.io/Gnuplot.jl/dev
+=#

docs/src/advanced.md

@@ -1,5 +1,20 @@
 # Advanced techniques
+
 ## Multiplot
+### Mixing 2D and 3D plots
+```julia
+
+@gp "set multiplot layout 1,2"
+@gp :- 1 "plot sin(x) w l"
+
+
+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 :- 2 x y fxy "w pm3d notit"
+
+```
 ## Multiple processes
 ## Named datasets
 ## Histograms (1D)

docs/src/api.md

@@ -1,3 +1,13 @@
+# API
+
+The list of **Gnuplot.jl** exported symbols are as follows:
+
 ```@docs
 @gp
+@gsp
+save
+palette
+linestyles
+hist
+contourlines
 ```

docs/src/basic.md

@@ -1,15 +1,210 @@
 # 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` (for 2D plots) and `@gsp` (for 3D plots) macros, both accepting any number of arguments, and 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 creating 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 lists all the required concepts to follow the examples presented below.  The `@gp` and `@gsp` macros also accepts further arguments, but their use will be discussed in [Advanced techniques](@ref).
+
+[^1]: a previous knowledge of [`gnuplot`](http://gnuplot.sourceforge.net/documentation.html) usage is, nevertheless, required.
+
 ## Plots in 2D
 
+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.
+
+
+### Simple examples involving just `gnuplot` commands:
+
+#### Plot a sinusoid:
+```julia
+@gp "plot sin(x)"
+save(term="png size 480,360", output="src/assets/basic1.png") # hide
+```
+![](assets/basic1.png)
+
+---
+#### Plot two curves:
+```julia
+@gp "set key left" "plot sin(x)" "pl cos(x)"
+save(term="png size 480,360", output="src/assets/basic2.png") # hide
+```
+![](assets/basic2.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:
+```julia
+@gp    "set grid"  :-
+@gp :- "p sin(x)"  :-
+@gp :- "plo cos(x)"
+save(term="png size 480,360", output="src/assets/basic3.png") # hide
+```
+![](assets/basic3.png)
+
+
+### Send data from Julia to `gnuplot`:
+
+#### Plot a parabola
+```julia
+@gp (1:20).^2 
+save(term="png size 480,360", output="src/assets/basic4.png") # hide
+```
+![](assets/basic4.png)
+
+
+---
+#### Plot a parabola with scaled x axis, lines and legend
+```julia
+x = 1:20
+@gp "set key left"   x ./ 20   x.^2   "with lines tit 'Parabola'"
+save(term="png size 480,360", output="src/assets/basic5.png") # hide
+```
+![](assets/basic5.png)
+
+---
+#### Multiple datasets, logarithmic axis, labels and colors, etc.
+```julia
+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:12]"
+@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'"
+save(term="png size 480,360", output="src/assets/basic6.png") # hide
+```
+![](assets/basic6.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 \"...\""`;
+ - `xlog=true`   => `set logscale x`;
+ - `ylog=true`   => `set logscale y`;
+ - `zlog=true`   => `set logscale z`;
+
+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:12]"
+```
+can be replaced with a shorter version:
+```julia
+@gp    "set grid" k="left" ylog=true
+@gp :- tit="Plot title" xlab="X label" xr=[0,12]
+```
+
+## Plot images
+
+**Gnuplot.jl** can also display images, i.e. 2D arrays:
+```julia
+img = randn(Float64, 30, 50)
+img[10,:] .= -4
+@gp img "w image notit"
+save(term="jpeg size 480,360", output="src/assets/basic7a.png") # hide
+```
+![](assets/basic7a.png)
+
+Note that the first index corresponds to the `X` coordinate when the image is displayed.
+
+The following example shows how to fix orientation of an image by means of the `using` clause (the `TestImages` package is required to run this example):
+```julia
+using TestImages
+img = testimage("lena");
+@gp "set size square" img "u 2:(-\$1):3:4:5 with rgbimage notit"
+save(term="jpeg size 480,360", output="src/assets/basic7b.jpg") # hide
+```
+![](assets/basic7b.jpg)
+
+
 ## Plots in 3D
+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:
+```julia
+x = 0:0.1:10pi
+@gsp x  sin.(x) .* x  cos.(x) .* x  x./15  "w p pt 7 ps var lc pal"
+save(term="jpeg size 640,480", output="src/assets/basic8.jpg") # hide
+```
+![](assets/basic8.jpg)
+
+The keywords discussed above can also be used in 3D plots.
+
 
 ## Palettes and line styles
+The **Gnuplot.jl** package comes with all the [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes readily available.
 
-## Exporting
+A `gnuplot`-compliant palette can be retrieved with `palette()`, and used as any other command.  The previous example may use an alternative palette with:
-
+```julia
-## Generating scripts
+x = 0:0.1:10pi
-
+@gsp palette(:viridis) x  sin.(x) .* x  cos.(x) .* x  x./15  "w p pt 7 ps var lc pal"
-## Quick reference
+save(term="jpeg size 640,480", output="src/assets/basic8a.jpg") # hide
+```
+![](assets/basic8a.jpg)
 
 
+The [ColorSchemes](https://juliagraphics.github.io/ColorSchemes.jl/stable/basics/#Pre-defined-schemes-1) palettes can also be used to generate line styles, by means of the `linestyles()` function, e.g.
+```julia
+@gp linestyles(:deepsea)
+x = 1:0.1:4pi
+for i in 1:5
+    @gp :- x i.* sin.(x) "w l notit ls $i lw 5"
+end
+save(term="jpeg size 480,360", output="src/assets/basic9.jpg") # hide
+```
+![](assets/basic9.jpg)
+
+
+
+
+## Exporting plots to files
+
+The `save()` function allows to export all plots (as well as multiplots, see [Multiplot](@ref)) to a file using one of the many available `gnuplot` terminals.  To check which terminals are available in your platform type `set term` in your `gnuplot` terminal.
+
+All plots in this page have been saved with:
+```julia
+save(term="png size 480,360", output="output.png")
+```
+except the *Lena* image, saved with the `jpeg` terminal:
+```julia
+save(term="jpeg size 480,360", output="output.png")
+```
+
+## Gnuplot scripts
+Besides exporting plots in a file **Gnuplot.jl** can also save a *script*, i.e. a file containing the minimum set of data and commands required to generate a plot within `gnuplot`.
+
+To generate a script for one of the example above use:
+```julia
+save("script.gp")
+```
+after the plot has been displayed.  The script can then be used within a `gnuplot` session as follows:
+```
+gunplot> load 'script.gp'
+```
+to generate a plot identical to the original one, without using the Julia language.
+
+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

@@ -1,27 +1,7 @@
 # Examples
 
-```julia
+An exhaustive gallery of example is available here:
 
-@gp "set multiplot layout 1,2"
+[https://lazarusa.github.io/gnuplot-examples/](https://lazarusa.github.io/gnuplot-examples/)
-@gp :- 1 "plot sin(x) w l"
 
-
+Further `gnuplot` examples can be found here: [http://www.gnuplotting.org/](http://www.gnuplotting.org/)
-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 :- 2 x y fxy "w pm3d notit"
-
-```
-
-
-
-@gp "set multiplot layout 1,2"
-@gp :- 2  "unset grid" "unset border" "unset tics" :-
-@gp :- 1 "plot sin(x) w l"
-
-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 :- 2 x y fxy "w pm3d notit"

docs/src/index.md

@@ -1,6 +1,5 @@
 # Gnuplot.jl
 ## A Julia interface to Gnuplot.
----
 
 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:
 
@@ -16,7 +15,7 @@ The **Gnuplot.jl** package allows easy and fast use of [`gnuplot`](http://gnuplo
 
 - availability of all the palettes from [ColorSchemes](https://github.com/JuliaGraphics/ColorSchemes.jl);
 
-- support for multiple plots in one window, mulitple plotting windows, as well as ASCII and Sixel plots (to plot directly in a terminal);
+- 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);
 
@@ -24,12 +23,12 @@ The **Gnuplot.jl** package allows easy and fast use of [`gnuplot`](http://gnuplo
 
 - export to a huge number of formats such as `pdf`, `png`, ``\LaTeX``, `svg`, etc. (actually all those supported by `gnuplot`);
 
-- save sessions into `gnuplot` scripts enables easy plot reproducibility and modfications.
+- save sessions into `gnuplot` scripts enables easy plot reproducibility and modifications.
+
 
----
 ## Yet another plotting package?
 
-A powerful plottig 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).
+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;
@@ -45,7 +44,6 @@ The **Gnuplot.jl** package development follows a minimalistic approach: it is es
 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.
 
 
----
 ## Do Gnuplot.jl suits my needs?
 
 Any modern plotting package 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 [Plots in 2D](@ref)). Still, producing complex and publication-quality plots is not an easy task.  As a consequence is also not easy to determine whether a package can cope with the most difficult cases (unless you actually try it out) and a reasonable choice is typically to rely on the size of the user base, the availability of documentation / tutorials, and the possibility to preview complex examples.
@@ -54,14 +52,14 @@ Any modern plotting package is able to produce a simple scatter plot, with custo
 
 Last but not least, have a look at the **Gnuplot.jl** [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
+## Table of Contents
 ```@contents
 Pages = ["index.md", "install.md", "basic.md", "advanced.md", "examples.md", "api.md"]
 ```

docs/src/install.md

@@ -1,14 +1,25 @@
 # 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.
+In order to use the **Gnuplot.jl** package you'll need [`gnuplot`](http://gnuplot.info/) (ver. >= 4.7) 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).
 
-## Installation
+## Package installation
-
 In the Julia REPL type:
-``` julia
+``` julia-repl
-using Pkg
+julia> ]add Gnuplot
-Pkg.add("Gnuplot")
+```
-using Gnuplot
+Then hit backspace key to return to Julia REPL.
+
+## Check installation
+Check execution and version of the underlying `gnuplot` process:
+```julia-repl
+julia> using Gnuplot
+julia> Gnuplot.gpversion()
+```
+
+Generate the first plot:
+```julia-repl
+julia> @gp 1:9
 ```