diff --git a/docs/make.jl b/docs/make.jl
index 45ab3b6..09a2502 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -9,6 +9,7 @@ makedocs(sitename="Gnuplot.jl",
              "Installation" => "install.md",
              "Basic usage" => "basic.md",
              "Advanced techniques" => "advanced.md",
+             "Tips" => "tips.md",
              "Examples" => "examples.md",
              "API" => "api.md"
          ])
@@ -39,7 +40,7 @@ git clone --single-branch --branch gh-pages  https://github.com/gcalderone/Gnupl
 
 Now copy the documentation "build" directory into, e.g., "dev", then
 git add dev/*
-git commit -m 'Updated'
+git commit -m 'Docs updated'
 git push origin gh-pages
 
 - Documentation will be available online at:
diff --git a/docs/src/api.md b/docs/src/api.md
index 1f96a8a..54a4f24 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -4,10 +4,4 @@ The list of **Gnuplot.jl** exported symbols are as follows:
 
 ```@docs
 @gp
-@gsp
-save
-palette
-linestyles
-hist
-contourlines
 ```
diff --git a/docs/src/assets/basic1.png b/docs/src/assets/basic1.png
deleted file mode 100644
index 2b6394f..0000000
Binary files a/docs/src/assets/basic1.png and /dev/null differ
diff --git a/docs/src/assets/basic2.png b/docs/src/assets/basic2.png
deleted file mode 100644
index 08e431e..0000000
Binary files a/docs/src/assets/basic2.png and /dev/null differ
diff --git a/docs/src/assets/basic3.png b/docs/src/assets/basic3.png
deleted file mode 100644
index 550320c..0000000
Binary files a/docs/src/assets/basic3.png and /dev/null differ
diff --git a/docs/src/assets/basic4.png b/docs/src/assets/basic4.png
deleted file mode 100644
index 2885c2f..0000000
Binary files a/docs/src/assets/basic4.png and /dev/null differ
diff --git a/docs/src/assets/basic5.png b/docs/src/assets/basic5.png
deleted file mode 100644
index 4138c47..0000000
Binary files a/docs/src/assets/basic5.png and /dev/null differ
diff --git a/docs/src/assets/basic6.png b/docs/src/assets/basic6.png
deleted file mode 100644
index 5f1eab4..0000000
Binary files a/docs/src/assets/basic6.png and /dev/null differ
diff --git a/docs/src/assets/basic7a.png b/docs/src/assets/basic7a.png
deleted file mode 100644
index 02e29f5..0000000
Binary files a/docs/src/assets/basic7a.png and /dev/null differ
diff --git a/docs/src/assets/basic7b.jpg b/docs/src/assets/basic7b.jpg
deleted file mode 100644
index 030c9f1..0000000
Binary files a/docs/src/assets/basic7b.jpg and /dev/null differ
diff --git a/docs/src/assets/basic8.jpg b/docs/src/assets/basic8.jpg
deleted file mode 100644
index 773fe53..0000000
Binary files a/docs/src/assets/basic8.jpg and /dev/null differ
diff --git a/docs/src/assets/basic8a.jpg b/docs/src/assets/basic8a.jpg
deleted file mode 100644
index 65f33e1..0000000
Binary files a/docs/src/assets/basic8a.jpg and /dev/null differ
diff --git a/docs/src/assets/basic9.jpg b/docs/src/assets/basic9.jpg
deleted file mode 100644
index e0e22d2..0000000
Binary files a/docs/src/assets/basic9.jpg and /dev/null differ
diff --git a/docs/src/basic.md b/docs/src/basic.md
index 2d67d23..ce35f07 100644
--- a/docs/src/basic.md
+++ b/docs/src/basic.md
@@ -16,25 +16,40 @@ The above lists all the required concepts to follow the examples presented below
 
 [^1]: a previous knowledge of [`gnuplot`](http://gnuplot.sourceforge.net/documentation.html) usage is, nevertheless, required.
 
-## Plots in 2D
+## [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.
+
+```@setup abc
+using Gnuplot
+Gnuplot.quitall()
+push!(Gnuplot.options.init, "set term unknown")
+saveas(file) = save(term="pngcairo size 480,360", output="assets/$file")
+```
+
+
 
 ### Simple examples involving just `gnuplot` commands:
 
+---
 #### Plot a sinusoid:
-```julia
+```@example abc
 @gp "plot sin(x)"
-save(term="png size 480,360", output="src/assets/basic1.png") # hide
+saveas("basic1.png") # hide
 ```
 ![](assets/basic1.png)
 
 ---
 #### Plot two curves:
-```julia
+```@example abc
 @gp "set key left" "plot sin(x)" "pl cos(x)"
-save(term="png size 480,360", output="src/assets/basic2.png") # hide
+saveas("basic2.png") # hide
 ```
 ![](assets/basic2.png)
 
@@ -43,11 +58,11 @@ save(term="png size 480,360", output="src/assets/basic2.png") # hide
 
 ---
 #### Split a `@gp` call in three statements:
-```julia
+```@example abc
 @gp    "set grid"  :-
 @gp :- "p sin(x)"  :-
 @gp :- "plo cos(x)"
-save(term="png size 480,360", output="src/assets/basic3.png") # hide
+saveas("basic3.png") # hide
 ```
 ![](assets/basic3.png)
 
@@ -55,32 +70,32 @@ save(term="png size 480,360", output="src/assets/basic3.png") # hide
 ### 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
+```@example abc
+@gp (1:20).^2
+saveas("basic4.png") # hide
 ```
 ![](assets/basic4.png)
 
 
 ---
 #### Plot a parabola with scaled x axis, lines and legend
-```julia
+```@example abc
 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
+saveas("basic5.png") # hide
 ```
 ![](assets/basic5.png)
 
 ---
 #### Multiple datasets, logarithmic axis, labels and colors, etc.
-```julia
+```@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: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
+saveas("basic6.png") # hide
 ```
 ![](assets/basic6.png)
 
@@ -119,62 +134,61 @@ can be replaced with a shorter version:
 ## Plot images
 
 **Gnuplot.jl** can also display images, i.e. 2D arrays:
-```julia
+```@example abc
 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
+saveas("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
+```@example abc
 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
+@gp "set size square" "set autoscale fix" img "u 2:(-\$1):3:4:5 with rgbimage notit"
+save(term="jpeg size 480,360", output="assets/basic7b.jpg") # hide
 ```
 ![](assets/basic7b.jpg)
 
 
-## Plots in 3D
+## [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:
-```julia
+```@example abc
 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
+@gsp x  sin.(x) .* x  cos.(x) .* x  x./20  "w p pt 7 ps var lc pal"
+saveas("basic8.png") # hide
 ```
-![](assets/basic8.jpg)
+![](assets/basic8.png)
 
 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.
 
 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
+```@example abc
 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"
-save(term="jpeg size 640,480", output="src/assets/basic8a.jpg") # hide
+@gsp palette(:viridis) x  sin.(x) .* x  cos.(x) .* x  x./20  "w p pt 7 ps var lc pal"
+saveas("basic8a.png") # hide
 ```
-![](assets/basic8a.jpg)
+![](assets/basic8a.png)
 
 
 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
+```@example abc
 @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
+saveas("basic9.png") # hide
 ```
-![](assets/basic9.jpg)
+![](assets/basic9.png)
 
 
 
@@ -185,11 +199,11 @@ The `save()` function allows to export all plots (as well as multiplots, see [Mu
 
 All plots in this page have been saved with:
 ```julia
-save(term="png size 480,360", output="output.png")
+save(term="pngcairo size 480,360", output="assets/output.png")
 ```
 except the *Lena* image, saved with the `jpeg` terminal:
 ```julia
-save(term="jpeg size 480,360", output="output.png")
+save(term="jpeg size 480,360", output="assets/output.png")
 ```
 
 ## Gnuplot scripts
diff --git a/docs/src/index.md b/docs/src/index.md
index abccdc0..9e654ae 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -46,7 +46,7 @@ The functionalities 1, 2 and 3 listed above are similar to those provided by the
 
 ## 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.
+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 [2D plots](@ref plots2d)). 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.
 
 **Gnuplot.jl** aims to be ready for even the most challenging plots by relying on the widely and long lasting used `gnuplot` application, and by allowing each native feature (both present and future ones) to be immediately available in the Julia language.  Moreover, **Gnuplot.jl** provides a unique syntax specifically aimed to increase productivity while performing interactive data exploration.
 
diff --git a/docs/src/install.md b/docs/src/install.md
index 4297903..304b8dd 100644
--- a/docs/src/install.md
+++ b/docs/src/install.md
@@ -7,16 +7,16 @@ If `gnuplot` is not available in your platform you can still use **Gnuplot.jl**
 
 ## Package installation
 In the Julia REPL type:
-``` julia-repl
+```julia-repl
 julia> ]add 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()
+```@repl
+using Gnuplot
+Gnuplot.gpversion()
 ```
 
 Generate the first plot: