Docstrings updated

docs/src/advanced.md

@@ -9,7 +9,7 @@ Gnuplot.quitall()
 mkpath("assets")
 saveas(file) = save(term="pngcairo size 480,360 fontscale 0.8", output="assets/$(file).png")
 empty!(Gnuplot.options.init)
-Gnuplot.exec("set term unknown")
+gpexec("set term unknown")
 ```
 
 
@@ -51,9 +51,9 @@ name = "\$MyDataSet1"
 The parameter best fit values can be retrieved as follows:
 ```@example abc
 @info("Best fit values:",
-a=Gnuplot.exec("print a"),
-b=Gnuplot.exec("print b"),
-c=Gnuplot.exec("print c"))
+a = gpexec("print a"),
+b = gpexec("print b"),
+c = gpexec("print c"))
 ```
 
 A named dataset is available until the session is reset, i.e. as long as `:-` is used as first argument to `@gp`.
@@ -128,7 +128,7 @@ 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()
-Gnuplot.exec("set term unknown") # hide
+gpexec("set term unknown") # hide
 ```
 
 ## Histograms
@@ -217,6 +217,15 @@ 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, use [`gpexec`](@ref).  E.g. if you wish to temporarily change the current terminal:
+```@repl abc
+gpexec("set term wxt");
+gpexec("set term unknown")  #hide
+```
+You may also provide a session ID as first argument (see [Multiple sessions](@ref), to redirect the command to a specific session.
+
+
 ## Dry sessions
 A "*dry session*" is a session with no underlying gnuplot process.  To enable dry sessions type:
 ```@repl abc
@@ -235,15 +244,15 @@ Thepackage options are stored in a global structure available in Julia as `Gnupl
 
 - `dry::Bool`: if true all new sessions will be started [Dry sessions](@ref).  Default is `false`, but if the package is not able to start a gnuplot it will automatically switch to `false`;
 
-- `init::Vector{String}`: This vector can be used to `push!` initialization commands to be executed when a new session is started.  Default is an empty vector.  It can be used to, e.g., set a terminal for all sessions which is different from the gnuplot default one:
+- `init::Vector{String}`: This vector can be used to `push!` initialization commands to be executed when a new session is started.  Default is an empty vector.  It can be used to, e.g., set a custom terminal for all new sessions:
 ```@repl abc
 push!(Gnuplot.options.init, "set term sixelgd");
 ```
-Note that this is a global option, i.e. it will affect **all** new sessions;
+Note that this is a global option, i.e. it will affect all new sessions.  Also note that the commands in `Gnuplot.options.init` are not saved in [Gnuplot scripts](@ref);
 
 - `verbose::Bool`: a flag to set verbosity of the package.  In particular if it is `true` all communication with the underlying process will be printed on stdout. E.g.:
 ```@repl abc
-Gnuplot.exec("set term wxt")  #hide
+gpexec("set term wxt")  #hide
 Gnuplot.options.verbose = true;
 x = 1.:10;
 @gp x x.^2 "w l t 'Parabola'"
@@ -253,7 +262,7 @@ Each line reports the package name (`GNUPLOT`), the session name (`default`), th
 
 ```@setup abc
 Gnuplot.options.verbose = false
-Gnuplot.exec("set term unknown")
+gpexec("set term unknown")
 ```
 
 - `cmd::String`: command to start the gnuplot process, default value is `"gnuplot"`.  If you need to specify a custom path to the gnuplot executable you may change this value;

docs/src/api.md

@@ -13,6 +13,7 @@ The list of **Gnuplot.jl** exported symbols is as follows:
 boxxyerror
 contourlines
 dataset_names
+gpexec
 hist
 linetypes
 palette
@@ -37,7 +38,6 @@ Gnuplot.Histogram2D
 Gnuplot.IsoContourLines
 Gnuplot.Options
 Gnuplot.Path2d
-Gnuplot.exec
 Gnuplot.gpversion
 Gnuplot.quit
 Gnuplot.quitall

docs/src/basic.md

@@ -33,7 +33,7 @@ mkpath("assets")
 Gnuplot.splash("assets/logo.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")
+gpexec("set term unknown")
 ```
 
 
@@ -221,6 +221,7 @@ palette_names()
 ```@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

docs/src/tips.md

@@ -4,13 +4,47 @@ This page collects useful tips in using **Gnuplot.jl**.
 
 
 ## Which terminal should I use ?
-`Gnuplot` provides dozens of terminals to display and export plots.  Here we report a few tips on how to exploit the most used 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.
 
-### `wxt` and `qt`
+To use a specific terminal for interactive use you may either add it as initialization command for all new session with (see [Options](@ref):
+```julia
+push!(Gnuplot.options.init, "set term wxt")
+```
+or directly send the command to a specific session (see [Direct command execution](@ref))
+```julia
+gpexec("set term wxt")
+```
 
-#### Mouse interactions
 
-### `dumb` and `sixelgd`
+### 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 set them as terminal with:
+```
+"set term wxt size 800,600"
+```
+or
+```
+"set 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 (`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 useful when you run Julia on a remote shell through `ssh`.  You may set these terminals with one of the following command:
+```
+"set term dumb"
+"set term sixel"
+"set term sixelgd"
+```
+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`).  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. Also, `sixelgd` requires support for Libgd to be enabled.
+
+### Export to image files
 
 ### `cairopng`
 
@@ -20,6 +54,3 @@ see [Animations](@ref).
 ### `pdf`
 
 ### `latex` and `cairolatex`
-
-### `unknown`
-This is a *dummy* terminal, it produces no output.  It is mainly used for debugging purposes.