Docstrings updated

docs/src/advanced.md

@@ -7,7 +7,7 @@ Here we will show a few advanced techniques for data visualization using **Gnupl
 using Gnuplot
 Gnuplot.quitall()
 mkpath("assets")
-saveas(file) = save(term="pngcairo size 480,360", output="assets/$(file).png")
+saveas(file) = save(term="pngcairo size 480,360 fontscale 0.8", output="assets/$(file).png")
 empty!(Gnuplot.options.init)
 Gnuplot.exec("set term unknown")
 ```
@@ -104,7 +104,7 @@ saveas("ex012") # hide
 
 ## Multiple sessions
 
-**Gnuplot.jl** can handle multiple sessions, i.e. multiple gnuplot processes running simultaneously.  Each session is identified by a symbol.
+**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
@@ -112,7 +112,7 @@ In order to redirect commands to a specific session simply insert a symbol into
 @gp :GP2 "plot sin(x)"    # opens secondo window
 @gp :- :GP1 "plot cos(x)" # add a plot on first window
 ```
-If the session ID is not specified the `:default` session is considered.
+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 considered.
 
 The names of all current sessions can be retrieved with [`session_names()`](@ref):
 ```@repl abc
@@ -130,8 +130,47 @@ You may also quit all active sessions at once with [`Gnuplot.quitall()`](@ref):
 Gnuplot.quitall()
 ```
 
-## Histograms (1D)
-## Histograms (2D)
+## Histograms
+**Gnuplot.jl** provides facilities to compute and display histograms, through the [`hist()`](@ref) function.  E.g., to quickly preview an histogram:
+```@example abc
+x = randn(1000);
+@gp hist(x)
+saveas("ex013a") # hide
+```
+![](assets/ex013a.png)
+
+A finer control on the output is achieved by setting the range to consider (`range=` keyword) and either the bin size (`bs=`) or the total number of bins (`nbins=`) in the histogram.  See [`hist()`](@ref) documentation for further information.
+
+Moreover, the [`hist()`](@ref) return a [`Gnuplot.Histogram1D`](@ref) structure, whose content can be exploited to customize histogram appearence, 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("ex013b") # hide
+```
+![](assets/ex013b.png)
+
+
+**Gnuplot.jl** also allows to compute 2D histograms by passing two vectors (with the same lengths) to [`hist()`](@ref).  A quick preview is simply obtained by:
+```@example abc
+x = randn(5000)
+y = randn(5000)
+@gp "set size ratio -1" hist(x, y)
+saveas("ex014a") # hide
+```
+![](assets/ex014a.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
+h = hist(x, y, bs1=0.25, nbins2=10, range1=[-3,3], range2=[-3,3])
+@gp "set size ratio -1" h.bins1 h.bins2 h.counts "w image notit"
+saveas("ex014b") # hide
+```
+![](assets/ex014b.png)
+
+
+
+
 ## Contour lines
 ## Animations
 ## Dry sessions

docs/src/basic.md

@@ -31,7 +31,7 @@ using Gnuplot
 Gnuplot.quitall()
 mkpath("assets")
 Gnuplot.splash("assets/logo.png")
-saveas(file) = save(term="pngcairo size 480,360", output="assets/$(file).png")
+saveas(file) = save(term="pngcairo size 480,360 fontscale 0.8", output="assets/$(file).png")
 empty!(Gnuplot.options.init)
 Gnuplot.exec("set term unknown")
 ```
@@ -221,15 +221,12 @@ The [`save()`](@ref) function allows to export all plots (as well as multiplots,
 
 All plots in this page have been saved with:
 ```julia
-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="assets/output.png")
+save(term="pngcairo size 480,360 fontscale 0.8", output="assets/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.
+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 re-create a figures using just gnuplot (Julia will be no longer needed).
 
 To generate a script for one of the example above use:
 ```julia
@@ -239,7 +236,9 @@ after the plot has been displayed.  The script can then be used within a gnuplot
 ```
 gunplot> load 'script.gp'
 ```
-to generate a plot identical to the original one, without using the Julia language.
+to generate a plot identical to the original one.
+
+Note that when images or large datasets are involved, `save()` may store the data in binary files under a directory whose name is `<script name>_data`. In order to work properly both the script and the created directory must be available in the same directory.
 
 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.
 

src/Gnuplot.jl

@@ -1343,8 +1343,8 @@ end
 A 1D histogram data.
 
 # Fields
-- `bins::Vector{Float64}`: middle points of the bins;
-- `counts::Vector{Float64}`: couts in the bins;
+- `bins::Vector{Float64}`: bin center values;
+- `counts::Vector{Float64}`: counts in the bins;
 - `binsize::Float64`: size of each bin;
 """
 mutable struct Histogram1D
@@ -1359,9 +1359,9 @@ end
 A 2D histogram data.
 
 # Fields
-- `bins1::Vector{Float64}`: middle points of the bins along first dimension;
-- `bins2::Vector{Float64}`: middle points of the bins along second dimension;
-- `counts::Vector{Float64}`: couts in the bins;
+- `bins1::Vector{Float64}`: bin center values along first dimension;
+- `bins2::Vector{Float64}`: bin center values along second dimension;
+- `counts::Vector{Float64}`: counts in the bins;
 - `binsize1::Float64`: size of each bin along first dimension;
 - `binsize2::Float64`: size of each bin along second dimension;
 """