diff --git a/docs/src/advanced.md b/docs/src/advanced.md index 729b268..b4adac2 100644 --- a/docs/src/advanced.md +++ b/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; diff --git a/docs/src/api.md b/docs/src/api.md index 4cd3307..a5b1942 100644 --- a/docs/src/api.md +++ b/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 diff --git a/docs/src/assets/sixelgd.png b/docs/src/assets/sixelgd.png new file mode 100644 index 0000000..92c1bc4 Binary files /dev/null and b/docs/src/assets/sixelgd.png differ diff --git a/docs/src/basic.md b/docs/src/basic.md index dc7f766..1839f27 100644 --- a/docs/src/basic.md +++ b/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 diff --git a/docs/src/tips.md b/docs/src/tips.md index 2940a0c..6cbeb00 100644 --- a/docs/src/tips.md +++ b/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.