Documentation updated

src/Gnuplot.jl

@@ -74,7 +74,7 @@ const state = State()
 #---------------------------------------------------------------------
 """
   # CheckGnuplotVersion
-  
+
   Check whether gnuplot is runnable with the command given in `cmd`.
   Also check that gnuplot version is >= 4.7 (required to use data
   blocks).
@@ -128,12 +128,12 @@ end
 #---------------------------------------------------------------------
 """
   # send
-  
+
   Send a string to gnuplot's STDIN.
-  
+
   The commands sent through `send` are not stored in the current
   session (use `addCmd` to save commands in the current session).
-  
+
   ## Arguments:
   - `gp`: a `Session` object;
   - `str::String`: command to be sent;
@@ -340,7 +340,7 @@ function addData(gp::Session, args...; name="")
         if length(i) > 0
             v = getfield.(gp.data[i], :str)
             push!(v, " ")
-            
+
             if state.verbosity >= 1
                 for ii in 1:length(v)
                     printstyled(color=:light_black, "GNUPLOT ($(gp.id)) -> $(v[ii])\n")
@@ -394,7 +394,7 @@ end
 #---------------------------------------------------------------------
 """
   # addCmd
-  
+
   Send a command to gnuplot process and store it in the current session.
 """
 function addCmd(gp::Session, v::String; mid::Int=0)
@@ -524,7 +524,7 @@ function gpDriver(args...; splot=false)
     data = Vector{Any}()
     dataname = ""
     dataplot = nothing
-    
+
     function dataCompleted()
         if length(data) > 0
             last = addData(gp, data...; name=dataname)
@@ -560,12 +560,12 @@ function gpDriver(args...; splot=false)
             doReset  &&  reset(gp)
             gp.plot[gp.multi].splot = splot
         end
-        
+
         for iarg in 1:length(args)
             arg = args[iarg]
 
             if typeof(arg) == Symbol
-                if arg == :-   
+                if arg == :-
                     (loop == 1)  &&  (iarg < length(args)) &&  (doReset = false)
                     (loop == 1)  &&  (iarg >  1)           &&  (doDump  = false)
                 else
@@ -642,7 +642,7 @@ end
 #---------------------------------------------------------------------
 """
   # gnuplot
-  
+
   Initialize a new session and (optionally) the associated Gnuplot process
 
   ## Arguments:
@@ -666,7 +666,7 @@ function gnuplot(id::Symbol; dry=false, cmd="gnuplot")
             line = convert(String, readline(stream))
             if line == "GNUPLOT_CAPTURE_BEGIN"
                 saveOutput = true
-            else                
+            else
                 (saveOutput)  &&  (put!(channel, line))
                 if line == "GNUPLOT_CAPTURE_END"
                     saveOutput = false
@@ -679,7 +679,7 @@ function gnuplot(id::Symbol; dry=false, cmd="gnuplot")
         delete!(state.sessions, id)
         return nothing
     end
-    
+
     global state
     proc = nothing
     if !dry
@@ -718,7 +718,7 @@ end
 #---------------------------------------------------------------------
 """
   # quit
-  
+
   Quit the session and the associated gnuplot process (if any).
 """
 function quit(id::Symbol)
@@ -731,7 +731,7 @@ end
 
 """
   # quitall
-  
+
   Quit all the sessions and the associated gnuplot processes.
 """
 function quitall()
@@ -747,12 +747,12 @@ end
 #---------------------------------------------------------------------
 """
   # @gp
-  
+
-  The `@gp` macro, and its companion `@gsp` (for `splot`
+  The `@gp` macro, and its companion `@gsp` (for `splot` operations)
-  operations) allows to exploit all of the **Gnuplot** package
+  allows to exploit all of the **Gnuplot** package functionalities
-  functionalities using an extremely efficient and concise syntax.  Both
+  using an extremely efficient and concise syntax.  Both macros accept
-  macros accept the same syntax, described below:
+  the same syntax, described below:
-  
+
   The macros accepts any number of arguments, with the following
   meaning:
 
@@ -771,13 +771,13 @@ end
     Gnuplot session.  Used as last argument avoids immediate execution
     of the plot/splot command.  This symbol can be used to split a
     single call into multiple ones.
-  
+
   All entries are optional, and there is no mandatory order.  The plot
   specification can either be: a complete plot/splot command (e.g.,
   "plot sin(x)", both "plot" and "splot" can be abbreviated to "p" and
-  "s" respectively), or a partial specification starting with the "with"
+  "s" respectively), or a partial specification starting with the
-  clause (if it follows a data set).
+  "with" clause (if it follows a data set).
-  
+
   The list of accepted keyword is as follows:
   - `title::String`: plot title;
   - `xlabel::String`: X axis label;
@@ -790,37 +790,41 @@ end
   - `yrange::NTuple{2, Number}`: Y axis range;
   - `zrange::NTuple{2, Number}`: Z axis range;
   - `cbrange::NTuple{2, Number}`: Color box axis range;
-  
+
   The symbol for the above-mentioned keywords may also be used in a
-  shortened form, as long as there is no ambiguity with other keywords.
+  shortened form, as long as there is no ambiguity with other
-  E.g. you can use: `xr=(1,10)` in place of `xrange=(1,10)`.
+  keywords.  E.g. you can use: `xr=(1,10)` in place of
-  
+  `xrange=(1,10)`.
+
   Beside the above-mentioned keyword the following can also be used
   (although with no symbol shortening):
-  
+
-  - verb=Int: 0 or 1, to set the verbosity level;
+  - `verb`: 0 or 1, to set the verbosity level;
-  - file="output.gp": send all the data and command to a file rather than
+  - `file`: send all the data and command to a file rather than
     to a Gnuplot process;
-  - stream=: send all the data and command to a stream rather than
+  - `stream`: send all the data and command to a stream rather than
     to a Gnuplot process;
-  - term="a string", or term=("a string", "a filename"): to specify the
+  - `term`: `"a string"`, or `("a string", "a filename")`: to specify
-    terminal (and optionally the output file);
+    the terminal (and optionally the output file);
-  
+
   ## Examples:
 
-  # Simple examples with no data
+  ### Simple examples with no data:
+  ```
   @gp "plot sin(x)"
   @gp "plot sin(x)" "pl cos(x)"
   @gp "plo sin(x)" "s cos(x)"
-  
+
   # Split a `@gp` call in two
   @gp "plot sin(x)" :-
   @gp :- "plot cos(x)"
-  
+
   # Insert a 3 second pause between one plot and the next
   @gp "plot sin(x)" 2 xr=(-2pi,2pi) "pause 3" "plot cos(4*x)"
-  
+  ```
-  # Simple examples with data:
+
+  ### Simple examples with data:
+  ```
   @gp "set key left" tit="My title" xr=(1,12) 1:10 "with lines tit 'Data'"
 
   x = collect(1.:10)
@@ -829,54 +833,63 @@ end
   @gp x -x
   @gp x x.^2
   @gp x x.^2 "w l"
-  
+
   lw = 3
   @gp x x.^2 "w l lw \$lw"
-  
+  ```
-  # A more complex example
+
+  ### A more complex example
+  ```
   @gp("set grid", "set key left", xlog=true, ylog=true,
       title="My title", xlab="X label", ylab="Y label",
       x, x.^0.5, "w l tit 'Pow 0.5' dt 2 lw 2 lc rgb 'red'",
       x, x     , "w l tit 'Pow 1'   dt 1 lw 3 lc rgb 'blue'",
       x, x.^2  , "w l tit 'Pow 2'   dt 3 lw 2 lc rgb 'purple'")
-  
+  ```
-  # Multiplot example:
+
+  ### Multiplot example:
+  ```
   @gp(xr=(-2pi,2pi), "unset key",
       "set multi layout 2,2 title 'Multiplot title'",
       1, "p sin(x)"  ,
       2, "p sin(2*x)",
       3, "p sin(3*x)",
       4, "p sin(4*x)")
-  
+  ```
-  # or equivalently
+  or equivalently
+  ```
   @gp xr=(-2pi,2pi) "unset key" "set multi layout 2,2 title 'Multiplot title'" :-
   for i in 1:4
     @gp :- i "p sin(\$i*x)" :-
   end
   @gp
-  
+  ```
-  # Multiple gnuplot instances
+
+  ### Multiple gnuplot sessions
+  ```
   @gp :GP1 "plot sin(x)"
   @gp :GP2 "plot sin(x)"
-  
+
   quitall()
-  
+  ```
-  # Further examples
+
+  ### Further examples
+  ```
   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 verb=2 x y :aa "plot \\\$aa w l" "pl \\\$aa u 1:(2*\\\$2) w l"
-  
+
   @gsp randn(Float64, 30, 50)
   @gp randn(Float64, 30, 50) "w image"
-  
+
   @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'");
-  
+
   @gp "f(x) = a * sin(b + c*x); a = 1; b = 1; c = 1;"            :-
   @gp :- x y+noise e :aa                                         :-
   @gp :- "fit f(x) \\\$aa u 1:2:3 via a, b, c;"                  :-
@@ -885,8 +898,10 @@ end
   @gp :- "plot \\\$aa u 1:(f(\\\$1)) w lines tit 'Best fit'"     :-
   @gp :- 2 xlab="X label" ylab="Residuals"                       :-
   @gp :- "plot \\\$aa u 1:((f(\\\$1)-\\\$2) / \\\$3):(1) w errorbars notit"
-  
+  ```
-  # Display an image
+
+  ### Display an image
+  ```
   using TestImages
   img = testimage("lena");
   @gp img "w image"
@@ -927,7 +942,7 @@ end
 # #---------------------------------------------------------------------
 # """
 #   # repl
-#   
+#
 #   Read/evaluate/print/loop
 # """
 # function repl(id::Symbol)
@@ -954,10 +969,10 @@ end
 #---------------------------------------------------------------------
 """
   # gpeval
-  
+
   Directly execute commands on the underlying gnuplot process, and return the result(s).
   functions.
-  
+
   ## Examples:
   ```
   gpeval("print GPVAL_TERM")